@coinbase/cdp-app-attest 0.0.98 → 0.0.99

package/dist/types/index.d.ts

@@ -1,43 +1,228 @@
+/**
+ * Android integrity data returned from createAssertion() method.
+ *
+ * Contains a Play Integrity token that proves app and device integrity.
+ * Unlike iOS assertions, these are fresh tokens generated per request.
+ */
 declare interface AndroidIntegrityData {
+    /**
+     * Base64-encoded Play Integrity Standard API token.
+     * This is a fresh token generated per request, not a cryptographic assertion.
+     * The backend validates it with Google's servers.
+     */
     integrityToken: string;
 }
 
+/**
+ * Result from the createAssertion() method.
+ *
+ * Contains platform-specific proof of authenticity to include in API requests.
+ * Either ios or android field will be populated, never both.
+ */
 export declare interface AssertionResult {
+    /** iOS assertion data (only present on iOS) */
     ios?: IOSAssertionData;
+    /**
+     * Android integrity token (only present on Android).
+     * This is a fresh Play Integrity token, not an assertion.
+     */
     android?: AndroidIntegrityData;
 }
 
+/**
+ * Attest the app instance with a server-provided challenge (iOS only).
+ *
+ * iOS: Generates a device key, attests it with Apple, and returns attestation data
+ * to be exchanged with your backend for key registration.
+ *
+ * Android: Not used. Android uses Play Integrity Standard API tokens sent
+ * directly in request headers (via createAssertion).
+ *
+ * This method handles key management internally:
+ * - Generates a new key on first use (iOS)
+ * - Caches the key for subsequent assertions (iOS)
+ *
+ * @param challenge - Server-provided challenge (base64-encoded)
+ * @returns Promise resolving to attestation result (iOS only)
+ * @throws Error if attestation fails or device doesn't support attestation
+ */
 export declare function attest(challenge: string): Promise<AttestationResult>;
 
+/**
+ * Result from the attest() method.
+ *
+ * Contains platform-specific attestation data to be exchanged with backend.
+ * iOS only - Android does not use attestation exchange.
+ */
 export declare interface AttestationResult {
+    /**
+     * iOS attestation data (only present on iOS).
+     * Android does not use the attestation exchange flow.
+     */
     ios?: IOSAttestationData;
 }
 
+/**
+ * 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)
+ * - You need to re-attest after attestation public key expiry
+ * - 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:
+ * - Swift's internal keyId (used for generating assertions)
+ * - SDK's registration confirmation flag (indicating backend has the public key)
+ *
+ * @returns Promise that resolves when attestation state is cleared
+ * @throws Error if the native module doesn't support clearing
+ *
+ * @example
+ * ```typescript
+ * // Handle "key not found" error from backend
+ * try {
+ *   const assertion = await createAssertion(clientData);
+ * } catch (error) {
+ *   if (error.message.includes('key not found')) {
+ *     await clearAttestation();
+ *     // Re-attest with new key
+ *     const attestation = await attest(challenge);
+ *     await registerAttestation(projectId, attestation);
+ *     await confirmRegistration(attestation.ios.keyId);
+ *   }
+ * }
+ * ```
+ */
 export declare function clearAttestation(): Promise<void>;
 
+/**
+ * Mark attestation as successfully registered with backend (iOS only).
+ *
+ * Only call this AFTER the backend successfully responds to the attestation
+ * registration request. Do NOT call before sending to backend or while waiting
+ * for response.
+ *
+ * This flag indicates that the device's public key is registered server-side
+ * and assertions can be validated.
+ *
+ * @param keyId - The key ID that was registered with the backend
+ * @returns Promise that resolves when the registration is marked as confirmed
+ *
+ * @example
+ * ```typescript
+ * const attestation = await attest(challenge);
+ * await registerAttestation(projectId, attestation); // Wait for backend success
+ * await confirmRegistration(attestation.ios.keyId);  // Only after backend responds
+ * ```
+ */
 export declare function confirmRegistration(keyId: string): Promise<void>;
 
+/**
+ * Generate proof of authenticity for an API request.
+ *
+ * iOS: Creates a cryptographic assertion signed with the device's private key.
+ * Must call attest() at least once before using this method to ensure a key
+ * has been generated and cached.
+ *
+ * Android: Generates a fresh Play Integrity Standard API token (not an assertion).
+ * No prior attestation needed - tokens are generated on-demand per request.
+ *
+ * @param clientData - Client data to include (base64-encoded)
+ * @returns Promise resolving to platform-specific proof (assertion or integrity token)
+ * @throws Error if generation fails (iOS: no cached key; Android: Play Services unavailable)
+ */
 export declare function createAssertion(clientData: string): Promise<AssertionResult>;
 
+/**
+ * Check if attestation is registered with backend (iOS only).
+ *
+ * Returns the key ID if attestation was successfully registered with backend.
+ * Returns null if:
+ * - Attestation hasn't been performed yet
+ * - Attestation failed to register with backend
+ * - Key was cleared via clearKey()
+ *
+ * **Note:** This checks the SDK's registration confirmation flag, not Swift's
+ * internal keyId. Swift may have generated a key (for createAssertion) but
+ * backend registration may not have completed successfully.
+ *
+ * @returns Promise resolving to the registered key ID, or null if not confirmed
+ *
+ * @example
+ * ```typescript
+ * const keyId = await getRegisteredKeyId();
+ * if (keyId) {
+ *   console.log('Already registered with backend');
+ * } else {
+ *   // Need to perform attestation
+ * }
+ * ```
+ */
 export declare function getRegisteredKeyId(): Promise<string | null>;
 
+/**
+ * Initialize the attestation module.
+ *
+ * iOS: Optional (no initialization needed)
+ * Android: Required (must provide cloudProjectNumber)
+ *
+ * @param config - Platform-specific configuration
+ * @returns Promise that resolves when initialization is complete
+ * @throws Error if required configuration is missing (Android)
+ */
 export declare function initialize(config?: InitializeConfig): Promise<void>;
 
+/**
+ * Configuration options for initializing the attestation module.
+ *
+ * iOS: No configuration needed (can be omitted).
+ * Android: Must provide cloudProjectNumber from Google Cloud Console.
+ */
 export declare interface InitializeConfig {
+    /** Cloud project number (Android only, required for Play Integrity API) */
     cloudProjectNumber?: string;
 }
 
+/**
+ * iOS assertion data returned from createAssertion() method.
+ *
+ * Contains a cryptographic signature proving the request originates
+ * from a genuine attested device. Include these in request headers.
+ */
 declare interface IOSAssertionData {
+    /** Base64-encoded assertion */
     assertion: string;
+    /** Key identifier used for the assertion */
     keyId: string;
 }
 
+/**
+ * iOS attestation data returned from the attest() method.
+ *
+ * This data should be sent to your backend's attestation exchange endpoint
+ * to register the device's public key.
+ */
 declare interface IOSAttestationData {
+    /** Key identifier */
     keyId: string;
+    /** Base64-encoded attestation object */
     attestation: string;
+    /** Bundle identifier */
     bundleId: string;
 }
 
+/**
+ * Check if device attestation is supported on this device.
+ *
+ * iOS: Returns true if iOS 14+ and DCAppAttestService is available
+ * Android: Returns true if Google Play Services is available
+ *
+ * @returns Promise resolving to true if attestation is supported
+ */
 export declare function isSupported(): Promise<boolean>;
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cdp-app-attest",
-  "version": "0.0.98",
+  "version": "0.0.99",
   "type": "module",
   "description": "CDP native module for iOS App Attest and Android Play Integrity",
   "files": [
@@ -44,7 +44,7 @@
     "react": "*",
     "react-native": "*",
     "react-native-device-info": "^10.3.0",
-    "@coinbase/cdp-core": "^0.0.98"
+    "@coinbase/cdp-core": "^0.0.99"
   },
   "devDependencies": {
     "@size-limit/preset-small-lib": "^11.2.0",