npm package: @nestedapps/device-attestation-rn
Description: React Native bridge for VerifyYou Device Attestation SDK
Author: Rohit Deshmukh
Latest version: 0.1.1

# @verifyyou/device-attestation-rn

React Native bridge for VerifyYou Device Attestation SDK. This library provides device attestation functionality using native SDKs for iOS and Android.

## Features

- ✅ Device attestation using native iOS and Android SDKs
- ✅ Biometric verification support
- ✅ Promise-based API with TypeScript types
- ✅ Automatic device enrollment (once per install)
- ✅ Secure call verification (challenge → sign → verify)
- ✅ Error handling with structured error codes

## Installation

### Prerequisites

- React Native 0.73+
- iOS 15.0+ (for App Attest support)
- Android API 24+ (for Play Integrity API support)

### Install the package

```bash
npm install @verifyyou/device-attestation-rn
# or
yarn add @verifyyou/device-attestation-rn
```

### iOS Setup

1. Install CocoaPods dependencies:

```bash
cd ios && pod install && cd ..
```

2. **Enable App Attest capability** in Xcode:
   - Open your project in Xcode
   - Select your target → Signing & Capabilities
   - Click "+ Capability"
   - Add "App Attest"

3. The package includes its own iOS App Attest implementation and does not require external SDK dependencies.

### Android Setup

1. The package includes its own Android Play Integrity implementation and does not require external SDK dependencies.

2. The library will automatically link via autolinking.

## Usage

### Basic Example

```typescript
import DeviceAttestation from '@verifyyou/device-attestation-rn';

// Initialize the SDK
await DeviceAttestation.initialize({
  serverURL: 'https://api.verifyyou.com',
  environment: 'production',
  enableLogging: true,
});

// Perform device attestation
const result = await DeviceAttestation.attestDevice({
  requesterUserId: 'user-123',
  stagingId: 'staging-456',
  clientId: 'client-789',
  useBiometric: true,
});

if (result.success) {
  console.log('Attestation token:', result.token);
  console.log('Key ID:', result.keyId);
} else {
  console.error('Attestation failed:', result.error);
}
```

### Get Device Info

```typescript
const deviceInfo = await DeviceAttestation.getDeviceInfo();

console.log('Is supported:', deviceInfo.isSupported);
console.log('Status:', deviceInfo.status); // 'unavailable' | 'not_enrolled' | 'enrolled'
console.log('Key ID:', deviceInfo.keyId);
```

## API Reference

### `initialize(config: AttestationInitConfig): Promise<void>`

Initialize the Device Attestation SDK. Must be called before using any other functions.

**Parameters:**
- `config.serverURL` (required): Server URL for attestation API
- `config.apiKey` (optional): API key for attestation requests
- `config.appID` (optional): App ID (defaults to bundle identifier/package name)
- `config.environment` (optional): 'development' | 'production' (default: 'development')
- `config.enableLogging` (optional): Enable debug logging (default: false)
- `config.cloudProjectNumber` (optional, Android): Play Integrity cloud project number
- `config.networkTimeoutMs` (optional): Network timeout in milliseconds

### `attestDevice(params: AttestDeviceParams): Promise<AttestationResult>`

Perform device attestation. This will:
- Ensure the device is attested (performs attestation once per install if needed)
- Perform secure call verification (challenge → sign → verify)
- Return attestation token/payload

**Parameters:**
- `params.requesterUserId` (required): User ID making the request
- `params.stagingId` (optional): Staging ID
- `params.clientId` (optional): Client ID
- `params.nonce` (optional): Nonce/challenge for verification
- `params.useBiometric` (optional): Whether to use biometric verification (default: false)
- `params.dataRequestType` (optional): Type of data request (default: 'identity_verification')

**Returns:**
```typescript
{
  success: boolean;
  token?: string;           // Attestation token/payload
  keyId?: string;           // Key ID of the attested device
  platform: 'ios' | 'android';
  timestamp: number;
  nonce?: string;
  metadata?: Record<string, unknown>;
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
}
```

### `getDeviceInfo(): Promise<DeviceInfo>`

Get device attestation information including support status and enrollment state.

**Returns:**
```typescript
{
  platform: 'ios' | 'android';
  isSupported: boolean;
  status: 'unavailable' | 'not_enrolled' | 'enrolled';
  keyId?: string;
  unavailableReason?: string;
}
```

### `getSdkVersion(): Promise<{ ios?: string; android?: string; rn: string }>`

Get SDK version information.

### `reset(): Promise<void>`

Reset attestation data (for testing/debugging). WARNING: This will clear all attestation data and require re-attestation.

## Error Codes

The library returns structured errors with the following codes:

- `UNSUPPORTED`: Device does not support App Attest / Play Integrity
- `KEY_GENERATION_FAILED`: Failed to generate attestation key
- `ATTESTATION_FAILED`: Attestation process failed
- `ASSERTION_FAILED`: Assertion generation failed
- `NETWORK_ERROR`: Network error occurred
- `SERVER_REJECTED`: Server rejected the request
- `INVALID_CONFIGURATION`: Invalid configuration provided
- `DEVICE_NOT_REGISTERED`: Device not registered on server
- `HARDWARE_KEY_ISSUE`: Hardware key issue detected
- `INVALID_SIGN_COUNT`: Invalid sign count (possible replay attack)

## Troubleshooting

### iOS

**Issue: "App Attest is not supported on this device"**
- Ensure you're testing on a physical device (simulator has limited support)
- Verify App Attest capability is enabled in Xcode
- Check that your app is properly code-signed

**Issue: "Device not registered"**
- This is normal for first-time attestation
- The SDK will automatically register the device
- Ensure serverURL is correct and accessible

### Android

**Issue: "Attestation failed"**
- Ensure Play Integrity API is available on the device
- Check that the device has Google Play Services installed
- Verify serverURL is correct and accessible

**Issue: Play Integrity errors**
- Ensure `cloudProjectNumber` is provided in `initialize()`
- Or add `CLOUD_PROJECT_NUMBER` to your app's `BuildConfig`

## License

MIT

## Support

For issues and questions, please contact the VerifyYou team.