@veridex/sdk 1.0.0-beta.8 → 1.0.1

package/dist/passkey.d.mts

@@ -0,0 +1,182 @@
+/**
+ * Veridex Protocol SDK - Passkey Manager
+ *
+ * Chain-agnostic WebAuthn/Passkey credential management
+ */
+interface PasskeyCredential {
+    credentialId: string;
+    publicKeyX: bigint;
+    publicKeyY: bigint;
+    keyHash: string;
+}
+interface WebAuthnSignature {
+    authenticatorData: string;
+    clientDataJSON: string;
+    challengeIndex: number;
+    typeIndex: number;
+    r: bigint;
+    s: bigint;
+}
+interface PasskeyManagerConfig {
+    rpName?: string;
+    rpId?: string;
+    timeout?: number;
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+    authenticatorAttachment?: 'platform' | 'cross-platform';
+    /** Relayer API URL for cross-device credential recovery */
+    relayerUrl?: string;
+}
+/**
+ * The canonical Veridex RP ID for cross-domain passkey sharing.
+ * All Veridex SDK instances should use this RP ID to enable passkey
+ * portability across different applications and domains.
+ *
+ * This works via W3C Related Origin Requests (ROR) - veridex.network
+ * hosts a .well-known/webauthn file that lists allowed origins.
+ */
+declare const VERIDEX_RP_ID = "veridex.network";
+/**
+ * Detects the appropriate RP ID for passkey sharing.
+ *
+ * For production: Returns VERIDEX_RP_ID ('veridex.network') to enable
+ * cross-domain passkey sharing via Related Origin Requests (ROR).
+ *
+ * For local development:
+ * - localhost/127.0.0.1 → returns as-is
+ * - IP addresses → returns as-is
+ *
+ * @param forceLocal - If true, uses local domain detection instead of canonical RP ID
+ */
+declare function detectRpId(forceLocal?: boolean): string;
+/**
+ * Check if the browser supports Related Origin Requests (ROR).
+ * This is a WebAuthn Level 3 feature that allows using passkeys
+ * across different domains listed in the RP's .well-known/webauthn file.
+ *
+ * @returns true if ROR is supported, false otherwise
+ */
+declare function supportsRelatedOrigins(): Promise<boolean>;
+
+/**
+ * Manages WebAuthn passkey credentials for Veridex Protocol
+ */
+declare class PasskeyManager {
+    private config;
+    private credential;
+    constructor(config?: PasskeyManagerConfig);
+    static isSupported(): boolean;
+    static isPlatformAuthenticatorAvailable(): Promise<boolean>;
+    register(username: string, displayName: string): Promise<PasskeyCredential>;
+    sign(challenge: Uint8Array): Promise<WebAuthnSignature>;
+    /**
+     * Authenticate using a discoverable credential (passkey)
+     * This allows sign-in without knowing the credential ID ahead of time.
+     * The authenticator will show all available passkeys for this RP.
+     *
+     * @param challenge - Optional challenge bytes. If not provided, a random challenge is used.
+     * @returns The credential that was used to authenticate, along with the signature
+     */
+    authenticate(challenge?: Uint8Array): Promise<{
+        credential: PasskeyCredential;
+        signature: WebAuthnSignature;
+    }>;
+    /**
+     * Find a credential by ID in the list of stored credentials
+     */
+    private findCredentialById;
+    /**
+     * Get all credentials stored in localStorage
+     */
+    getAllStoredCredentials(key?: string): PasskeyCredential[];
+    private parseStoredCredential;
+    /**
+     * Save a list of credentials to localStorage
+     */
+    saveCredentials(credentials: PasskeyCredential[], key?: string): void;
+    /**
+     * Add a single credential to storage (append or update)
+     */
+    addCredentialToStorage(credential: PasskeyCredential, key?: string): void;
+    /**
+     * Check if there's ANY stored credential for this RP
+     */
+    hasStoredCredential(): boolean;
+    getCredential(): PasskeyCredential | null;
+    setCredential(credential: PasskeyCredential): void;
+    createCredentialFromPublicKey(credentialId: string, publicKeyX: bigint, publicKeyY: bigint): PasskeyCredential;
+    clearCredential(): void;
+    /**
+     * Save the current credential to localStorage (appends to list)
+     */
+    saveToLocalStorage(key?: string): void;
+    loadFromLocalStorage(key?: string): PasskeyCredential | null;
+    removeFromLocalStorage(key?: string): void;
+    /**
+     * Save the current credential to the relayer for cross-device recovery.
+     * This should be called after registration.
+     */
+    saveCredentialToRelayer(): Promise<boolean>;
+    /**
+     * Load a credential from the relayer by credential ID.
+     * Used during discoverable credential authentication when localStorage is empty.
+     */
+    loadCredentialFromRelayer(credentialId: string): Promise<PasskeyCredential | null>;
+    /**
+     * Load a credential from the relayer by keyHash.
+     * Useful when you know the user's keyHash but not their credential ID.
+     */
+    loadCredentialFromRelayerByKeyHash(keyHash: string): Promise<PasskeyCredential | null>;
+    /**
+     * Register a backup passkey for the current identity.
+     *
+     * This creates a new WebAuthn credential on this device/platform that becomes
+     * an additional authorized key for the same Veridex identity. The caller
+     * must submit the returned credential to VeridexHub.addKey() for on-chain registration.
+     *
+     * Use cases:
+     * - "Add this device" flow when signing in on a new machine
+     * - Proactive backup creation on a separate authenticator
+     * - Cross-ecosystem redundancy (iCloud + Google Password Manager)
+     *
+     * @param username - Username for the new credential (typically same as primary)
+     * @param displayName - Display name for the backup (e.g., "MacBook Pro Backup")
+     * @param excludeCredentialIds - Credential IDs to exclude (prevents re-registering same authenticator)
+     * @returns The newly registered backup credential
+     */
+    registerBackupPasskey(username: string, displayName: string, excludeCredentialIds?: string[]): Promise<PasskeyCredential>;
+    /**
+     * Get registration info for backup state from a registration response.
+     *
+     * This extracts the backup eligibility (BE) and backup state (BS) flags
+     * from the authenticator data, which indicate whether the credential
+     * is eligible for cloud sync and whether it is currently synced.
+     *
+     * @param authenticatorData - Hex-encoded authenticator data from registration
+     * @returns Backup flags, or null if not determinable
+     */
+    static parseBackupFlags(authenticatorData: string): {
+        backupEligible: boolean;
+        backupState: boolean;
+    } | null;
+    /**
+     * Get the number of credentials stored locally.
+     */
+    getStoredCredentialCount(): number;
+    /**
+     * Get all credential IDs stored locally (for exclude lists).
+     */
+    getStoredCredentialIds(): string[];
+    private extractPublicKeyFromAttestation;
+    private parseCOSEKey;
+    private tryParseCOSEKeyStrategies;
+    private parseCOSEKeyWithCBORStructure;
+    private tryParseASN1Structure;
+    private find32ByteSequences;
+    private isValidCoordinate;
+    private bytesToBigInt;
+    private bytesToHex;
+    private analyzeCOSEStructure;
+    private parseAuthenticationResponse;
+}
+
+export { type PasskeyCredential, PasskeyManager, type PasskeyManagerConfig, VERIDEX_RP_ID, type WebAuthnSignature, detectRpId, supportsRelatedOrigins };