#Device Attestation API

Server-verifiable, hardware-backed device attestation via the opt-in package react-native-nitro-device-integrity.

• Android → Play Integrity API
• iOS → App Attest (DCAppAttestService) + DeviceCheck (DCDevice)

This is a separate, opt-in package from the core library. Install it only if you need real attestation; it pulls in Play Integrity / App Attest dependencies and requires Google Cloud / Apple console setup.

#The responsibility boundary

#Installation

yarn add react-native-nitro-device-integrity react-native-nitro-modules
cd ios && pod install

Requirements: iOS 14.0+ (App Attest) / 11.0+ (DeviceCheck), Android API 23+ with Google Play Services.

#API Reference

import { createDeviceIntegrity } from 'react-native-nitro-device-integrity';

const integrity = createDeviceIntegrity();

#Availability

#isSupported

readonly isSupported: boolean

Best-effort check. On Android, true when Google Play Services is available (does not guarantee the Play Integrity API is onboarded for your app). On iOS, DCAppAttestService.shared.isSupported — always false on the Simulator.

#providerType

readonly providerType: 'playIntegrity' | 'appAttest' | 'unsupported'

Which provider backs this device. Branch your client logic on this before calling platform-specific methods.

#Android — Play Integrity

#prepareStandardProvider()

prepareStandardProvider(cloudProjectNumber: string): Promise<void>

Warms up the Play Integrity Standard token provider. Call once per session; the provider is cached natively. cloudProjectNumber is passed as a string to avoid JS number-precision loss.

Rejects with (in the error message): CLOUD_PROJECT_NUMBER_IS_INVALID, PLAY_STORE_NOT_FOUND, NETWORK_ERROR, etc. On iOS: UNSUPPORTED_PLATFORM.

#requestIntegrityToken()

requestIntegrityToken(requestHash: string): Promise<string>

Requests a Standard token. Requires a prior prepareStandardProvider. If the cached provider has expired (INTEGRITY_TOKEN_PROVIDER_INVALID), it is re-prepared once automatically and the request retried.

requestHash is a base64 SHA-256 of your request's critical parameters (max 500 bytes) — not a server nonce; the caller computes it. Returns an opaque, encrypted token string.

#requestClassicIntegrityToken()

requestClassicIntegrityToken(nonce: string, cloudProjectNumber: string): Promise<string>

Play Integrity Classic flow (one-off, server-nonce based). Prefer Standard for frequent checks. nonce must be a server-generated, single-use, URL-safe base64 value of 16–500 bytes.

#iOS — App Attest

#generateKey()

generateKey(): Promise<string>

Generates an App Attest key pair in the Secure Enclave and returns its keyId.

#attestKey()

attestKey(keyId: string, clientDataHash: string): Promise<string>

Attests a key (once per key, per install). Makes a network call to Apple. clientDataHash is base64 of SHA-256(server challenge) — the library does not hash for you. Returns base64 of the opaque CBOR attestation object.

#generateAssertion()

generateAssertion(keyId: string, clientDataHash: string): Promise<string>

Generates an assertion for a subsequent request (offline). Returns base64 of the opaque CBOR assertion object. Your server checks its monotonic counter to detect replays.

#iOS — DeviceCheck

#getDeviceCheckToken()

getDeviceCheckToken(): Promise<string>

Generates an Apple DeviceCheck token (device-level, lighter than App Attest). Your server queries/updates the device's 2 bits of state via Apple's DeviceCheck API.

#Usage

import { createDeviceIntegrity } from 'react-native-nitro-device-integrity';

const integrity = createDeviceIntegrity();

if (integrity.providerType === 'playIntegrity') {
  // Android
  await integrity.prepareStandardProvider('123456789012'); // once
  const requestHash = base64Sha256('checkout:item-42');    // your request params
  const token = await integrity.requestIntegrityToken(requestHash);
  await postToYourServer({ token });                        // server verifies
} else if (integrity.providerType === 'appAttest') {
  // iOS
  const keyId = await integrity.generateKey();              // persist this
  const clientDataHash = base64Sha256(serverChallenge);
  const attestation = await integrity.attestKey(keyId, clientDataHash); // once
  await postToYourServer({ keyId, attestation });           // one-time validation
  // ...per request:
  const assertion = await integrity.generateAssertion(keyId, base64Sha256(payload));
  await postToYourServer({ keyId, assertion });
}

#Server verification (your responsibility)

This library stops at issuing the token. Your backend verifies it.

#Play Integrity (Android)

Send the token to your server, then call Google's decode endpoint (recommended):

POST https://playintegrity.googleapis.com/v1/{packageName}:decodeIntegrityToken

Interpret the decoded verdict:

• deviceIntegrity.deviceRecognitionVerdict containing MEETS_DEVICE_INTEGRITY
• appIntegrity.appRecognitionVerdict === 'PLAY_RECOGNIZED'
• An empty deviceRecognitionVerdict signals a compromised/emulated device.

See Play Integrity verdicts.

#App Attest (iOS)

1. Validate the attestation once per key against Apple's App Attest Root CA (cert chain, nonce, app-ID hash, counter = 0). Store the public key + counter.
2. For each assertion, verify its signature with the stored public key and that the counter strictly increased.

See Validating apps that connect to your server.

#Setup requirements

#Android (Play Integrity)

1. Create/select a Google Cloud project and enable the Play Integrity API.
2. Link it in Play Console → Play Integrity API.
3. Pass that Cloud project number to prepareStandardProvider / requestClassicIntegrityToken.
4. On your server, set up the Google service account (or response-encryption keys).

#iOS (App Attest / DeviceCheck)

1. Add the App Attest capability to your app target (Xcode → Signing & Capabilities), which adds the com.apple.developer.devicecheck.appattest-environment entitlement.
2. Use a bundle identifier you own and set your Development Team.
3. For DeviceCheck server queries, create a DeviceCheck .p8 key in the Apple Developer portal.

#Limitations

:::warning Be honest about what attestation can and cannot do

• App Attest is not a jailbreak detector. It proves a genuine, unmodified app on genuine Apple hardware — use it as a positive signal.
• Simulators / emulators: isSupported is false on the iOS Simulator; Play Integrity returns weak/empty verdicts on emulators.
• Rooted devices: Play Integrity still returns a token, but with an empty deviceRecognitionVerdict — your server must treat that as a failure.
• Bypasses exist (e.g. PlayIntegrityFix). Attestation is one signal in a broader anti-abuse strategy, not an absolute guarantee.
• Network + console configuration required. Without them, token issuance rejects — handle the rejection; don't treat it as "safe".
• App Attest throttling: Apple rate-limits attestKey. Control call frequency in your app; the library adds no retry/timer (it stays stateless). :::