@coinbase/cdp-app-attest 0.0.94 → 0.0.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cdp-app-attest",
-  "version": "0.0.94",
+  "version": "0.0.95",
   "type": "module",
   "description": "CDP native module for iOS App Attest and Android Play Integrity",
   "files": [

package/README.md

@@ -1,678 +0,0 @@
-# @coinbase/cdp-app-attest
-
-CDP native module for iOS App Attest, providing device attestation capabilities to verify that requests come from legitimate instances of your app running on genuine Apple devices.
-
-## Features
-
-- ✅ **Simplified API** - Automatic key management, no manual key ID tracking
-- ✅ **Secure** - Keys stored in iOS Keychain, private keys in Secure Enclave
-- ✅ **iOS 14+** - Uses Apple's DCAppAttestService
-- ✅ Assertion-based security for sensitive operations
-
-## Platform Support
-
-- **iOS**: iOS 14.0+ on physical devices (uses DCAppAttestService)
-  - ⚠️ Not supported on iOS Simulator
-  - ⚠️ Not supported in Expo Go (requires custom dev build)
-- **Android**: Play Integrity support is planned but not available in this release
-
-## Installation
-
-```bash
-npx expo install @coinbase/cdp-app-attest
-```
-
-## Setup
-
-### iOS Configuration
-
-1. Open your project in Xcode:
-   ```bash
-   open ios/YourApp.xcworkspace
-   ```
-
-2. Add the App Attest capability:
-   - Select your app target
-   - Go to **Signing & Capabilities**
-   - Click **+ Capability**
-   - Add **App Attest**
-
-That's it! No additional configuration needed.
-
-## Understanding Attestation vs Assertion
-
-iOS App Attest uses two different operations:
-
-### **Attestation** (One-Time Registration)
-- **What:** Generates a cryptographic key and proves it's in your device's Secure Enclave
-- **When:** Once per app installation (before making sensitive requests)
-- **Signed by:** Apple
-- **Flow:**
-  1. Generate server challenge
-  2. Call `attest(challenge)` - creates key + attestation object
-  3. Send attestation to backend `/attestation/register` endpoint
-  4. Backend verifies with Apple and stores your device's public key
-- **Result:** Your device's public key is registered with the backend
-
-### **Assertion** (Per-Request Proof)
-- **What:** Cryptographically signed proof that a request comes from your attested device
-- **When:** Every sensitive API request (sign transactions, export keys, etc.)
-- **Signed by:** Your device's Secure Enclave using the private key
-- **Flow:**
-  1. Call `createAssertion(clientData)` - signs request data
-  2. Add assertion to request headers: `X-App-Attestation-Assertion` + `X-App-Attestation-Key-ID`
-  3. Backend validates signature using stored public key
-- **Result:** Backend confirms request is from genuine, attested device
-
-**Think of it like:**
-- **Attestation** = Getting a passport (register your identity once)
-- **Assertion** = Signing documents with your passport (prove it's you for each transaction)
-
-## Usage
-
-### Basic Example
-
-```typescript
-import * as AppAttest from '@coinbase/cdp-app-attest';
-
-// 1. Check if device supports attestation
-const supported = await AppAttest.isSupported();
-console.log('Attestation supported:', supported);
-
-if (supported) {
-  // ONE-TIME: Attest the app installation
-  // Get a challenge from your server (32+ bytes, base64-encoded)
-  const challenge = await yourBackend.getChallenge();
-
-  // Attest with the challenge (generates key automatically)
-  const result = await AppAttest.attest(challenge);
-  // Result: { ios: { keyId: "...", attestation: "...", bundleId: "..." } }
-
-  // Send attestation to backend for verification and public key storage
-  await yourBackend.exchangeAttestation({
-    challenge: challenge,
-    ...result.ios  // Send iOS attestation data
-  });
-  console.log('Device attested and public key registered!');
-
-  // ONGOING: Generate assertions for sensitive operations
-  const clientData = btoa('POST||/v2/wallets/sign-transaction');
-  const assertion = await AppAttest.createAssertion(clientData);
-  // Result: { ios: { assertion: "...", keyId: "..." } }
-
-  // Include assertion in request headers
-  await fetch('https://api.example.com/v2/wallets/sign-transaction', {
-    method: 'POST',
-    headers: {
-      'X-App-Attestation-Assertion': assertion.ios.assertion,
-      'X-App-Attestation-Key-ID': assertion.ios.keyId,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ /* transaction data */ }),
-  });
-}
-```
-
-### Complete Attestation Flow
-
-```typescript
-import * as AppAttest from '@coinbase/cdp-app-attest';
-
-async function setupAttestation() {
-  // Check support
-  const supported = await AppAttest.isSupported();
-  if (!supported) {
-    console.log('App Attest not supported on this device');
-    return false;
-  }
-
-  try {
-    // ONE-TIME: Attest the app instance
-    // This generates a key (stored in Keychain) and creates an attestation
-    // object signed by Apple that proves this is a legitimate installation
-    const challenge = await yourBackend.getChallenge();
-    const result = await AppAttest.attest(challenge);
-
-    // result: { ios: { keyId: "...", attestation: "...", bundleId: "..." } }
-
-    // Send to backend for verification and public key storage
-    await yourBackend.exchangeAttestation({
-      challenge: challenge,
-      keyId: result.ios.keyId,
-      attestation: result.ios.attestation,
-      bundleId: result.ios.bundleId,
-    });
-
-    console.log('✅ Device attested and public key registered!');
-    return true;
-  } catch (error) {
-    console.error('❌ Attestation failed:', error);
-    return false;
-  }
-}
-
-async function makeAttestedRequest(method: string, path: string, body: any) {
-  try {
-    // ONGOING: Generate assertion for each sensitive request
-    // Client data should match backend expectation (e.g., "METHOD||PATH")
-    const clientData = btoa(`${method}||${path}`);
-    const result = await AppAttest.createAssertion(clientData);
-
-    // result: { ios: { assertion: "...", keyId: "..." } }
-
-    // Include assertion in request headers
-    const response = await fetch(`https://api.example.com${path}`, {
-      method: method,
-      headers: {
-        'X-App-Attestation-Assertion': result.ios.assertion,
-        'X-App-Attestation-Key-ID': result.ios.keyId,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(body),
-    });
-
-    if (!response.ok) {
-      throw new Error(`Request failed: ${response.status}`);
-    }
-
-    return await response.json();
-  } catch (error) {
-    console.error('❌ Attested request failed:', error);
-    throw error;
-  }
-}
-```
-
-## When to Re-Attest
-
-You need to re-attest when:
-
-- **App is installed for the first time** - No key exists yet
-- **Backend reports "key not found"** - Stored public key expired or was lost
-- **App is reinstalled** - Keys are automatically cleared
-- **Key is manually cleared** - After calling `clearAttestation()` for testing/debugging
-
-You do **NOT** need to re-attest:
-
-- **On every app launch** - Key persists in Keychain across launches
-- **After app updates** - Key survives app updates
-- **After device restart** - Key is stored in Keychain (persistent storage)
-- **For every request** - Use `createAssertion()` for ongoing requests
-
-## API Reference
-
-### `isSupported(): Promise<boolean>`
-
-Check if device attestation is supported on this device.
-
-**Returns:** `Promise<boolean>` - `true` if App Attest is available
-
-**Example:**
-```typescript
-const supported = await AppAttest.isSupported();
-if (!supported) {
-  // Fallback to non-attested flow
-}
-```
-
----
-
-### `attest(challenge: string): Promise<AttestationResult>`
-
-Attest the app instance with a server-provided challenge.
-
-This method automatically:
-- Generates a new cryptographic key on first use (stored in iOS Keychain)
-- Reuses the cached key on subsequent calls
-- Creates an attestation object signed by Apple
-
-**⚠️ Important:** Each key can only be attested **once**. Subsequent calls with the same key will fail. After successful attestation, use `createAssertion()` for ongoing requests.
-
-**Parameters:**
-- `challenge` (string) - Base64-encoded challenge from your server (minimum 32 bytes)
-
-**Returns:** `Promise<AttestationResult>`
-```typescript
-interface AttestationResult {
-  ios: {
-    keyId: string;          // Key identifier (UUID)
-    attestation: string;    // Base64-encoded attestation object
-    bundleId: string;       // Bundle identifier (e.g., "com.example.app")
-  };
-}
-```
-
-**Response Format:**
-```typescript
-{
-  ios: {
-    keyId: "abc123def456...",
-    attestation: "b2F1dGhEYXRh...",
-    bundleId: "com.example.app"
-  }
-}
-```
-
-**Throws:**
-- `Error` if device doesn't support App Attest
-- `Error` if key was already attested (error code 2)
-- `Error` if challenge is invalid
-
-**Example:**
-```typescript
-try {
-  const challenge = await getServerChallenge();
-  const result = await AppAttest.attest(challenge);
-
-  // Send to backend for verification and public key storage
-  await sendToBackend({
-    challenge: challenge,
-    keyId: result.ios.keyId,
-    attestation: result.ios.attestation,
-    bundleId: result.ios.bundleId,
-  });
-} catch (error) {
-  console.error('Attestation failed:', error);
-}
-```
-
----
-
-### `createAssertion(clientData: string): Promise<AssertionResult>`
-
-Generate a cryptographic assertion for an API request.
-
-Must call `attest()` at least once before using this method to ensure a key has been generated and attested.
-
-**Parameters:**
-- `clientData` (string) - Base64-encoded data to sign (typically request payload hash)
-
-**Returns:** `Promise<AssertionResult>`
-```typescript
-interface AssertionResult {
-  ios: {
-    assertion: string;  // Base64-encoded assertion
-    keyId: string;      // Key identifier (same as from attest())
-  };
-}
-```
-
-**Response Format:**
-```typescript
-{
-  ios: {
-    assertion: "YXNzZXJ0aW9u...",
-    keyId: "abc123def456..."
-  }
-}
-```
-
-**Throws:**
-- `Error` if no attested key exists (call `attest()` first)
-- `Error` if device doesn't support App Attest
-
-**Example:**
-```typescript
-// Generate assertion for sensitive request
-const clientData = btoa('POST||/v2/wallets/sign-transaction');
-const result = await AppAttest.createAssertion(clientData);
-
-// Include assertion in request headers
-await fetch('https://api.example.com/v2/wallets/sign-transaction', {
-  method: 'POST',
-  headers: {
-    'X-App-Attestation-Assertion': result.ios.assertion,
-    'X-App-Attestation-Key-ID': result.ios.keyId,
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({ /* transaction data */ }),
-});
-```
-
----
-
-### `confirmRegistration(keyId: string): Promise<void>`
-
-Mark attestation as successfully registered with your backend.
-
-Call this only after your backend confirms the attestation exchange succeeded.
-This stores a local flag so your app can avoid re-attesting unnecessarily.
-
-**Parameters:**
-- `keyId` (string) - The key ID that was registered with the backend
-
-**Returns:** `Promise<void>`
-
-**Example:**
-```typescript
-const attestation = await AppAttest.attest(challenge);
-await backend.exchangeAttestation(attestation.ios);
-await AppAttest.confirmRegistration(attestation.ios.keyId);
-```
-
----
-
-### `getRegisteredKeyId(): Promise<string | null>`
-
-Check whether this device's attestation has been confirmed as registered
-with your backend.
-
-Returns the stored key ID if registration was confirmed, otherwise `null`.
-
-**Returns:** `Promise<string | null>`
-
-**Example:**
-```typescript
-const registeredKeyId = await AppAttest.getRegisteredKeyId();
-if (registeredKeyId) {
-  console.log('Already registered:', registeredKeyId);
-} else {
-  // Perform attestation flow
-}
-```
-
----
-
-### `clearAttestation(): Promise<void>`
-
-Clears all attestation state, allowing re-attestation with a new key.
-
-**When to use:**
-- Backend returns "Attestation key not found" (public key expired or lost)
-- Backend's stored public key has expired
-- Testing/debugging scenarios
-
-**Important:** After clearing attestation, you MUST call `attest()` again to generate a new key and perform fresh attestation. Until then, `createAssertion()` will fail.
-
-This clears both:
-- Swift's internal keyId (used for generating assertions)
-- SDK's registration confirmation flag (indicates backend has the public key)
-
-**Returns:** `Promise<void>`
-
-**Throws:**
-- `Error` if the native module doesn't support clearing
-
-**Example:**
-```typescript
-// Handle "key not found" error from backend
-try {
-  const assertion = await AppAttest.createAssertion(clientData);
-  await api.sendTransaction({ assertion });
-} catch (error) {
-  if (error.message.includes('Attestation key not found')) {
-    console.log('Public key not found on backend - re-attesting');
-
-    // Clear the old key
-    await AppAttest.clearAttestation();
-
-    // Re-attest with new key
-    const challenge = await getServerChallenge();
-    const attestation = await AppAttest.attest(challenge);
-    await sendToBackend({ challenge, ...attestation });
-
-    // Retry the original operation
-    const newAssertion = await AppAttest.createAssertion(clientData);
-    await api.sendTransaction({ assertion: newAssertion });
-  }
-}
-
-// Explicit re-attestation flow
-async function forceReAttestation() {
-  console.log('Clearing existing key and re-attesting...');
-
-  // 1. Clear the old key
-  await AppAttest.clearAttestation();
-
-  // 2. Get new challenge
-  const challenge = await getServerChallenge();
-
-  // 3. Attest (generates new key)
-  const attestation = await AppAttest.attest(challenge);
-
-  // 4. Exchange with backend
-  await sendToBackend({ challenge, ...attestation });
-
-  console.log('Re-attestation complete!');
-}
-```
-
-## Key Management
-
-### Understanding the Key Architecture
-
-App Attest uses a cryptographic key pair with three components:
-
-| Component | Location | Purpose | Who Accesses |
-|-----------|----------|---------|--------------|
-| **Key ID** | iOS Keychain (in app) | Identifier to reference the key | Your app |
-| **Private Key** | Secure Enclave (hardware) | Signs attestations/assertions | iOS only (never extractable) |
-| **Public Key** | Backend server | Verifies signatures | Backend |
-
-**Important:** The private key never leaves the device and can't be extracted, even by your app. iOS uses it internally to create signatures.
-
-### Automatic Key Storage
-
-Keys are automatically managed:
-- ✅ Generated on first `attest()` call
-- ✅ Key ID stored in iOS Keychain (secure, persistent)
-- ✅ Private key stored in Secure Enclave (hardware-backed, never extractable)
-- ✅ Key ID reused for subsequent `createAssertion()` calls
-- ✅ Persisted across app launches and updates
-- ❌ **Not** persisted across app reinstallation (by design)
-
-### What Each Component Needs
-
-**Your App (SDK):**
-- Stores: Key ID only (in iOS Keychain)
-- Never has access to: Private key (locked in Secure Enclave)
-- Uses: Key ID to call `createAssertion()`
-
-**Backend:**
-- Stores: Public key (extracted from attestation object)
-- Never has access to: Private key
-- Uses: Public key to verify assertion signatures
-
-**iOS Secure Enclave:**
-- Stores: Private key (hardware-backed, never extractable)
-- Used by: iOS internally to sign attestations and assertions
-- Never exposed to: The app or the backend
-
-### Key Lifecycle
-
-```
-App Install
-    ↓
-First attest() call → Generates key pair
-    ↓
-    ├─ Key ID → Stored in Keychain (accessible to app)
-    ├─ Private Key → Stored in Secure Enclave (never extractable)
-    └─ Public Key → Sent to backend in attestation (verified & stored)
-    ↓
-createAssertion() calls → iOS uses private key to sign (app provides Key ID)
-    ↓
-App Update → Key survives ✅
-    ↓
-App Reinstall → Key is lost ❌ (start over)
-```
-
-## Error Handling
-
-### Common Errors
-
-**Error Code 2 (DCAppAttestErrorInvalidKey)**
-```typescript
-// Key was already attested
-try {
-  await AppAttest.attest(challenge);
-} catch (error) {
-  if (error.message.includes('error 2')) {
-    // Option 1: Use createAssertion() for ongoing requests
-    console.log('Key already attested, use assertions for ongoing requests');
-    const assertion = await AppAttest.createAssertion(clientData);
-
-    // Option 2: If you need to re-attest (e.g., backend lost public key),
-    // clear the key first
-    await AppAttest.clearAttestation();
-    const newAttestation = await AppAttest.attest(newChallenge);
-  }
-}
-```
-
-**Not Supported**
-```typescript
-const supported = await AppAttest.isSupported();
-if (!supported) {
-  // Device doesn't support App Attest
-  // - iOS version < 14.0
-  // - Running on simulator
-  // - Running in Expo Go
-}
-```
-
-**No Key Found**
-```typescript
-try {
-  await AppAttest.createAssertion(data);
-} catch (error) {
-  if (error.message.includes('No attestation key found')) {
-    // Need to call attest() first
-    await AppAttest.attest(challenge);
-  }
-}
-```
-
-## Testing
-
-### Development Builds
-
-App Attest works in development builds but uses Apple's **development environment**. Be aware:
-- ✅ Works on physical devices
-- ❌ Does NOT work on simulators
-- ⚠️ TestFlight uses a different environment than production
-- ⚠️ Development attestations can't be verified in production
-
-### Resetting Keys for Testing
-
-For testing, you may need to reset keys between test runs. Use the public `clearAttestation()` method:
-
-```typescript
-import * as AppAttest from '@coinbase/cdp-app-attest';
-
-// Clear the key to allow re-attestation
-await AppAttest.clearAttestation();
-console.log('Key cleared - can attest again');
-
-// Now you can attest with a new key
-const challenge = await getServerChallenge();
-const attestation = await AppAttest.attest(challenge);
-```
-
-**Note:** `clearAttestation()` is now part of the public API and can be used in production for legitimate re-attestation scenarios (e.g., when backend's public key expires).
-
-## Architecture Details
-
-### Key Storage: Keychain vs UserDefaults
-
-**What we store:** Key ID only (a UUID-like identifier string)
-
-**Where we store it:** iOS Keychain
-
-**Why Keychain instead of UserDefaults?**
-- ✅ Best practice for persistent identifiers
-- ✅ More secure by default
-- ✅ Survives app updates (but not reinstalls, by design)
-- ✅ Professional implementation standard
-
-**Could we use UserDefaults?** Yes! Apple's documentation says to store the Key ID in "persistent storage, for example by writing it to a file." Both Keychain and UserDefaults qualify as persistent storage.
-
-**Is the Key ID a secret?** No. It's just an identifier. Even if exposed, an attacker can't use it without the physical device's Secure Enclave containing the private key.
-
-### What The Backend Must Store
-
-During attestation verification, the backend **must** extract and store:
-
-1. **Public Key** - From the attestation's credCert (x5c certificate)
-2. **Counter** - Starts at 0, increments with each assertion (prevents replay attacks)
-3. **Project/App Association** - Link this key to your app/project
-
-Without storing the public key and counter, the backend can't verify assertions later!
-
-```javascript
-// Backend stores per attested key:
-{
-  projectId: "project123",
-  keyId: "abc123def456...",        // From iOS attestation
-  publicKey: "MFkwEwYHKoZI...",    // Extracted from attestation credCert
-  counter: 5,                      // Updated with each assertion to prevent replay
-  createdAt: "2026-02-05T10:30:00Z",
-  expiresAt: "2026-05-05T10:30:00Z"
-}
-```
-
-**Counter validation is critical:**
-- Each assertion includes a counter value
-- Backend MUST verify: `assertion.counter > stored.counter`
-- Backend MUST update stored counter after successful validation
-- Without this, attackers can replay old assertions
-
-## Backend Verification
-
-The backend must verify both attestations and assertions. See Apple's documentation:
-- [Validating Apps That Connect to Your Server](https://developer.apple.com/documentation/devicecheck/validating-apps-that-connect-to-your-server)
-- [Assessing Fraud Risk](https://developer.apple.com/documentation/devicecheck/assessing-fraud-risk)
-
-## Important Notes
-
-### Device Requirements
-- ✅ Physical iOS device (iPhone, iPad)
-- ✅ iOS 14.0 or later
-- ❌ iOS Simulator (not supported by Apple)
-- ❌ Expo Go (requires custom dev build)
-
-### Production Considerations
-- Keys are tied to the app installation
-- Each key can only be attested **once**
-- Keys don't survive app reinstallation
-- TestFlight uses different attestation environment
-- Key generation is automatic (handled by the SDK when calling `attest()`)
-
-### Security Best Practices
-- Always verify attestations on your backend
-- Use unique, one-time challenges
-- Challenges should be at least 32 bytes
-- Store attested key IDs server-side
-- Monitor backend logs for suspicious patterns (same user attesting multiple times)
-
-## Troubleshooting
-
-**"App Attest is not supported on this device"**
-- Check iOS version (requires 14.0+)
-- Ensure using physical device (not simulator)
-- Verify App Attest capability is enabled in Xcode
-
-**"Failed to attest key: error 2"**
-- Key was already attested
-- Use `createAssertion()` for ongoing requests
-- To re-attest: call `clearAttestation()` first, then `attest()` with a new challenge
-
-**"No attestation key found"**
-- Call `attest()` before `createAssertion()`
-- Key may have been lost (app reinstall)
-- Start attestation flow from beginning
-
-**"Attestation key not found" (from backend)**
-- Backend's public key expired or was lost
-- Clear the key: `await AppAttest.clearAttestation()`
-- Re-attest: `await AppAttest.attest(newChallenge)`
-- Send new attestation to backend for verification
-
-## Related Documentation
-
-- [Apple's App Attest Guide](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity)
-- [Expo Modules Documentation](https://docs.expo.dev/modules/)
-- [@coinbase/cdp-core Integration Guide](../core/README.md)
-
-## License
-
-Apache-2.0