@idealyst/biometrics 1.2.108

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@idealyst/biometrics",
+  "version": "1.2.108",
+  "description": "Cross-platform biometric authentication and passkeys for React and React Native",
+  "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/biometrics#readme",
+  "readme": "README.md",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/biometrics"
+  },
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "browser": {
+        "types": "./src/index.web.ts",
+        "import": "./src/index.web.ts",
+        "require": "./src/index.web.ts"
+      },
+      "default": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "require": "./src/index.ts"
+      }
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "expo-local-authentication": ">=14.0.0",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "react-native-passkeys": ">=0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-local-authentication": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    },
+    "react-native-passkeys": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "expo-local-authentication": "^16.0.0",
+    "react-native-passkeys": "^0.4.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "biometrics",
+    "fingerprint",
+    "faceid",
+    "touchid",
+    "passkeys",
+    "webauthn",
+    "fido2",
+    "authentication",
+    "cross-platform"
+  ]
+}

package/src/biometrics.native.ts

@@ -0,0 +1,173 @@
+// ============================================================================
+// Native Biometric Authentication
+// Uses expo-local-authentication for fingerprint, FaceID, iris
+// ============================================================================
+
+import type {
+  BiometricType,
+  SecurityLevel,
+  AuthenticateOptions,
+  AuthResult,
+} from './types';
+
+let LocalAuthentication: typeof import('expo-local-authentication') | null =
+  null;
+
+try {
+  LocalAuthentication = require('expo-local-authentication');
+} catch {
+  // expo-local-authentication not installed — all functions degrade gracefully
+}
+
+/**
+ * Check whether any biometric hardware is available and enrolled.
+ */
+export async function isBiometricAvailable(): Promise<boolean> {
+  if (!LocalAuthentication) return false;
+
+  try {
+    const hasHardware = await LocalAuthentication.hasHardwareAsync();
+    if (!hasHardware) return false;
+    const isEnrolled = await LocalAuthentication.isEnrolledAsync();
+    return isEnrolled;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the biometric types available on this device.
+ */
+export async function getBiometricTypes(): Promise<BiometricType[]> {
+  if (!LocalAuthentication) return [];
+
+  try {
+    const types =
+      await LocalAuthentication.supportedAuthenticationTypesAsync();
+    const result: BiometricType[] = [];
+
+    for (const t of types) {
+      switch (t) {
+        case LocalAuthentication.AuthenticationType.FINGERPRINT:
+          result.push('fingerprint');
+          break;
+        case LocalAuthentication.AuthenticationType.FACIAL_RECOGNITION:
+          result.push('facial_recognition');
+          break;
+        case LocalAuthentication.AuthenticationType.IRIS:
+          result.push('iris');
+          break;
+      }
+    }
+
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get the security level of biometric auth on the device.
+ */
+export async function getSecurityLevel(): Promise<SecurityLevel> {
+  if (!LocalAuthentication) return 'none';
+
+  try {
+    const level = await LocalAuthentication.getEnrolledLevelAsync();
+
+    switch (level) {
+      case LocalAuthentication.SecurityLevel.NONE:
+        return 'none';
+      case LocalAuthentication.SecurityLevel.SECRET:
+        return 'device_credential';
+      case LocalAuthentication.SecurityLevel.BIOMETRIC_WEAK:
+        return 'biometric_weak';
+      case LocalAuthentication.SecurityLevel.BIOMETRIC_STRONG:
+        return 'biometric_strong';
+      default:
+        return 'none';
+    }
+  } catch {
+    return 'none';
+  }
+}
+
+/**
+ * Prompt the user for biometric authentication.
+ */
+export async function authenticate(
+  options?: AuthenticateOptions,
+): Promise<AuthResult> {
+  if (!LocalAuthentication) {
+    return {
+      success: false,
+      error: 'not_available',
+      message: 'expo-local-authentication is not installed',
+    };
+  }
+
+  try {
+    const result = await LocalAuthentication.authenticateAsync({
+      promptMessage: options?.promptMessage ?? 'Authenticate',
+      cancelLabel: options?.cancelLabel,
+      fallbackLabel: options?.fallbackLabel,
+      disableDeviceFallback: options?.disableDeviceFallback,
+    });
+
+    if (result.success) {
+      return { success: true };
+    }
+
+    // Map expo error codes to our AuthError type
+    const errorCode = result.error;
+    switch (errorCode) {
+      case 'not_available':
+        return { success: false, error: 'not_available', message: result.warning };
+      case 'not_enrolled':
+        return { success: false, error: 'not_enrolled', message: result.warning };
+      case 'user_cancel':
+        return { success: false, error: 'user_cancel', message: result.warning };
+      case 'lockout':
+        return { success: false, error: 'lockout', message: result.warning };
+      case 'system_cancel':
+        return { success: false, error: 'system_cancel', message: result.warning };
+      case 'passcode_not_set':
+        return {
+          success: false,
+          error: 'passcode_not_set',
+          message: result.warning,
+        };
+      case 'authentication_failed':
+        return {
+          success: false,
+          error: 'authentication_failed',
+          message: result.warning,
+        };
+      default:
+        return {
+          success: false,
+          error: 'unknown',
+          message: result.warning ?? 'Authentication failed',
+        };
+    }
+  } catch (err: unknown) {
+    return {
+      success: false,
+      error: 'unknown',
+      message: err instanceof Error ? err.message : 'Unknown error',
+    };
+  }
+}
+
+/**
+ * Cancel an in-progress authentication (Android only).
+ */
+export async function cancelAuthentication(): Promise<void> {
+  if (!LocalAuthentication) return;
+
+  try {
+    await LocalAuthentication.cancelAuthenticate();
+  } catch {
+    // Ignore — may not be supported or no auth in progress
+  }
+}

package/src/biometrics.web.ts

@@ -0,0 +1,138 @@
+// ============================================================================
+// Web Biometric Authentication
+// Uses WebAuthn's userVerification to check for platform authenticator
+// ============================================================================
+
+import type {
+  BiometricType,
+  SecurityLevel,
+  AuthenticateOptions,
+  AuthResult,
+} from './types';
+
+/**
+ * Check if a user-verifying platform authenticator is available.
+ * This indicates the device has biometric or PIN-based auth (e.g. Windows Hello,
+ * Touch ID in Safari, Android biometric prompt in Chrome).
+ */
+export async function isBiometricAvailable(): Promise<boolean> {
+  if (
+    typeof window === 'undefined' ||
+    typeof PublicKeyCredential === 'undefined'
+  ) {
+    return false;
+  }
+
+  try {
+    return await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * On web, we cannot distinguish between fingerprint, face, etc.
+ * If a platform authenticator is available, we report it generically.
+ */
+export async function getBiometricTypes(): Promise<BiometricType[]> {
+  const available = await isBiometricAvailable();
+  // Web cannot distinguish biometric type — report fingerprint as a generic indicator
+  return available ? ['fingerprint'] : [];
+}
+
+/**
+ * On web, security level is binary: either a platform authenticator exists
+ * (biometric_strong) or it doesn't (none).
+ */
+export async function getSecurityLevel(): Promise<SecurityLevel> {
+  const available = await isBiometricAvailable();
+  return available ? 'biometric_strong' : 'none';
+}
+
+/**
+ * Trigger a WebAuthn user-verification ceremony.
+ *
+ * This creates a throwaway credential with `userVerification: 'required'`
+ * which forces the browser to verify the user via biometrics or device PIN.
+ * The credential itself is not stored — this is purely for local verification.
+ */
+export async function authenticate(
+  options?: AuthenticateOptions,
+): Promise<AuthResult> {
+  if (!(await isBiometricAvailable())) {
+    return {
+      success: false,
+      error: 'not_available',
+      message: 'No platform authenticator available',
+    };
+  }
+
+  try {
+    // Generate a random challenge
+    const challenge = new Uint8Array(32);
+    crypto.getRandomValues(challenge);
+
+    // Generate a random user ID
+    const userId = new Uint8Array(16);
+    crypto.getRandomValues(userId);
+
+    const credential = await navigator.credentials.create({
+      publicKey: {
+        challenge,
+        rp: {
+          name: options?.promptMessage ?? 'Biometric Verification',
+          id: window.location.hostname,
+        },
+        user: {
+          id: userId,
+          name: 'biometric-check',
+          displayName: 'Biometric Verification',
+        },
+        pubKeyCredParams: [
+          { type: 'public-key', alg: -7 }, // ES256
+        ],
+        authenticatorSelection: {
+          authenticatorAttachment: 'platform',
+          userVerification: 'required',
+          residentKey: 'discouraged',
+        },
+        timeout: 60000,
+        attestation: 'none',
+      },
+    });
+
+    return credential ? { success: true } : {
+      success: false,
+      error: 'authentication_failed',
+      message: 'No credential returned',
+    };
+  } catch (err: unknown) {
+    const error = err as DOMException;
+
+    if (error.name === 'NotAllowedError') {
+      return {
+        success: false,
+        error: 'user_cancel',
+        message: error.message || 'User cancelled or not allowed',
+      };
+    }
+
+    if (error.name === 'InvalidStateError') {
+      // Credential already exists for this rp+user — still means auth succeeded
+      return { success: true };
+    }
+
+    return {
+      success: false,
+      error: 'unknown',
+      message: error.message || 'Unknown error during authentication',
+    };
+  }
+}
+
+/**
+ * No-op on web — cancellation is handled by the browser's native UI.
+ */
+export async function cancelAuthentication(): Promise<void> {
+  // Not supported on web; the browser handles dismissal
+}

package/src/index.native.ts

@@ -0,0 +1,13 @@
+export * from './types';
+export {
+  isBiometricAvailable,
+  getBiometricTypes,
+  getSecurityLevel,
+  authenticate,
+  cancelAuthentication,
+} from './biometrics.native';
+export {
+  isPasskeySupported,
+  createPasskey,
+  getPasskey,
+} from './passkeys.native';

package/src/index.ts

@@ -0,0 +1,15 @@
+// Default entry — re-exports types.
+// Platform-specific entry points (index.web.ts, index.native.ts) provide real implementations.
+export * from './types';
+export {
+  isBiometricAvailable,
+  getBiometricTypes,
+  getSecurityLevel,
+  authenticate,
+  cancelAuthentication,
+} from './biometrics.web';
+export {
+  isPasskeySupported,
+  createPasskey,
+  getPasskey,
+} from './passkeys.web';

package/src/index.web.ts

@@ -0,0 +1,13 @@
+export * from './types';
+export {
+  isBiometricAvailable,
+  getBiometricTypes,
+  getSecurityLevel,
+  authenticate,
+  cancelAuthentication,
+} from './biometrics.web';
+export {
+  isPasskeySupported,
+  createPasskey,
+  getPasskey,
+} from './passkeys.web';

package/src/passkeys.native.ts

@@ -0,0 +1,146 @@
+// ============================================================================
+// Native Passkeys (FIDO2 / WebAuthn via react-native-passkeys)
+// ============================================================================
+
+import type {
+  PasskeyCreateOptions,
+  PasskeyCreateResult,
+  PasskeyGetOptions,
+  PasskeyGetResult,
+  PasskeyError,
+} from './types';
+
+let Passkey: {
+  isSupported: () => boolean;
+  create: (request: unknown) => Promise<unknown>;
+  get: (request: unknown) => Promise<unknown>;
+} | null = null;
+
+try {
+  const mod = require('react-native-passkeys');
+  Passkey = mod.Passkey ?? mod.default ?? mod;
+} catch {
+  // react-native-passkeys not installed — functions throw PasskeyError
+}
+
+/**
+ * Check if passkeys are supported on this device.
+ */
+export async function isPasskeySupported(): Promise<boolean> {
+  if (!Passkey) return false;
+
+  try {
+    return Passkey.isSupported();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a new passkey (registration / attestation).
+ *
+ * @throws {PasskeyError} on failure
+ */
+export async function createPasskey(
+  options: PasskeyCreateOptions,
+): Promise<PasskeyCreateResult> {
+  if (!Passkey) {
+    throw {
+      code: 'not_supported',
+      message: 'react-native-passkeys is not installed',
+    } satisfies PasskeyError;
+  }
+
+  try {
+    const result = (await Passkey.create({
+      challenge: options.challenge,
+      rp: options.rp,
+      user: options.user,
+      pubKeyCredParams: options.pubKeyCredParams ?? [
+        { type: 'public-key', alg: -7 },
+        { type: 'public-key', alg: -257 },
+      ],
+      timeout: options.timeout,
+      authenticatorSelection: options.authenticatorSelection ?? {
+        residentKey: 'preferred',
+        userVerification: 'preferred',
+      },
+      excludeCredentials: options.excludeCredentials,
+      attestation: options.attestation ?? 'none',
+    })) as PasskeyCreateResult;
+
+    return result;
+  } catch (err: unknown) {
+    throw mapNativeError(err);
+  }
+}
+
+/**
+ * Get an existing passkey (authentication / assertion).
+ *
+ * @throws {PasskeyError} on failure
+ */
+export async function getPasskey(
+  options: PasskeyGetOptions,
+): Promise<PasskeyGetResult> {
+  if (!Passkey) {
+    throw {
+      code: 'not_supported',
+      message: 'react-native-passkeys is not installed',
+    } satisfies PasskeyError;
+  }
+
+  try {
+    const result = (await Passkey.get({
+      challenge: options.challenge,
+      rpId: options.rpId,
+      allowCredentials: options.allowCredentials,
+      timeout: options.timeout,
+      userVerification: options.userVerification ?? 'preferred',
+    })) as PasskeyGetResult;
+
+    return result;
+  } catch (err: unknown) {
+    throw mapNativeError(err);
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function mapNativeError(err: unknown): PasskeyError {
+  if (
+    err !== null &&
+    typeof err === 'object' &&
+    'code' in err &&
+    'message' in err
+  ) {
+    const e = err as { code: string; message: string };
+
+    // react-native-passkeys error codes
+    if (
+      e.code === 'cancelled' ||
+      e.code === 'UserCancelled' ||
+      e.message.includes('cancel')
+    ) {
+      return { code: 'cancelled', message: e.message };
+    }
+    if (e.code === 'InvalidStateError' || e.code === 'invalid_state') {
+      return { code: 'invalid_state', message: e.message };
+    }
+    if (e.code === 'NotAllowedError' || e.code === 'not_allowed') {
+      return { code: 'not_allowed', message: e.message };
+    }
+    if (e.code === 'NotSupportedError' || e.code === 'not_supported') {
+      return { code: 'not_supported', message: e.message };
+    }
+
+    return { code: 'unknown', message: e.message };
+  }
+
+  return {
+    code: 'unknown',
+    message: err instanceof Error ? err.message : 'Unknown passkey error',
+  };
+}

package/src/passkeys.web.ts

@@ -0,0 +1,203 @@
+// ============================================================================
+// Web Passkeys (WebAuthn / FIDO2)
+// Uses navigator.credentials.create / get with publicKey
+// ============================================================================
+
+import type {
+  PasskeyCreateOptions,
+  PasskeyCreateResult,
+  PasskeyGetOptions,
+  PasskeyGetResult,
+  PasskeyError,
+} from './types';
+import { base64urlToBuffer, bufferToBase64url } from './types';
+
+/**
+ * Check if WebAuthn / passkeys are supported in this browser.
+ */
+export async function isPasskeySupported(): Promise<boolean> {
+  if (
+    typeof window === 'undefined' ||
+    typeof PublicKeyCredential === 'undefined'
+  ) {
+    return false;
+  }
+
+  try {
+    // Check for conditional mediation support (autofill-assisted passkeys)
+    // Falls back to basic PublicKeyCredential check
+    return await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+  } catch {
+    // PublicKeyCredential exists but the check failed — still likely supported
+    return typeof navigator.credentials !== 'undefined';
+  }
+}
+
+/**
+ * Create a new passkey (WebAuthn registration / attestation).
+ *
+ * @throws {PasskeyError} on failure
+ */
+export async function createPasskey(
+  options: PasskeyCreateOptions,
+): Promise<PasskeyCreateResult> {
+  if (typeof PublicKeyCredential === 'undefined') {
+    throw {
+      code: 'not_supported',
+      message: 'WebAuthn is not supported in this browser',
+    } satisfies PasskeyError;
+  }
+
+  const publicKey: PublicKeyCredentialCreationOptions = {
+    challenge: base64urlToBuffer(options.challenge),
+    rp: options.rp,
+    user: {
+      id: base64urlToBuffer(options.user.id),
+      name: options.user.name,
+      displayName: options.user.displayName,
+    },
+    pubKeyCredParams: options.pubKeyCredParams ?? [
+      { type: 'public-key', alg: -7 }, // ES256
+      { type: 'public-key', alg: -257 }, // RS256
+    ],
+    timeout: options.timeout ?? 60000,
+    authenticatorSelection: options.authenticatorSelection ?? {
+      residentKey: 'preferred',
+      userVerification: 'preferred',
+    },
+    excludeCredentials: options.excludeCredentials?.map((cred) => ({
+      type: cred.type,
+      id: base64urlToBuffer(cred.id),
+      transports: cred.transports,
+    })),
+    attestation: options.attestation ?? 'none',
+  };
+
+  let credential: PublicKeyCredential;
+
+  try {
+    const result = await navigator.credentials.create({ publicKey });
+    if (!result) {
+      throw {
+        code: 'unknown',
+        message: 'navigator.credentials.create returned null',
+      } satisfies PasskeyError;
+    }
+    credential = result as PublicKeyCredential;
+  } catch (err: unknown) {
+    throw mapDOMError(err);
+  }
+
+  const response =
+    credential.response as AuthenticatorAttestationResponse;
+
+  return {
+    id: credential.id,
+    rawId: bufferToBase64url(credential.rawId),
+    type: 'public-key',
+    response: {
+      clientDataJSON: bufferToBase64url(response.clientDataJSON),
+      attestationObject: bufferToBase64url(response.attestationObject),
+    },
+  };
+}
+
+/**
+ * Get an existing passkey (WebAuthn authentication / assertion).
+ *
+ * @throws {PasskeyError} on failure
+ */
+export async function getPasskey(
+  options: PasskeyGetOptions,
+): Promise<PasskeyGetResult> {
+  if (typeof PublicKeyCredential === 'undefined') {
+    throw {
+      code: 'not_supported',
+      message: 'WebAuthn is not supported in this browser',
+    } satisfies PasskeyError;
+  }
+
+  const publicKey: PublicKeyCredentialRequestOptions = {
+    challenge: base64urlToBuffer(options.challenge),
+    rpId: options.rpId,
+    allowCredentials: options.allowCredentials?.map((cred) => ({
+      type: cred.type,
+      id: base64urlToBuffer(cred.id),
+      transports: cred.transports,
+    })),
+    timeout: options.timeout ?? 60000,
+    userVerification: options.userVerification ?? 'preferred',
+  };
+
+  let credential: PublicKeyCredential;
+
+  try {
+    const result = await navigator.credentials.get({ publicKey });
+    if (!result) {
+      throw {
+        code: 'unknown',
+        message: 'navigator.credentials.get returned null',
+      } satisfies PasskeyError;
+    }
+    credential = result as PublicKeyCredential;
+  } catch (err: unknown) {
+    throw mapDOMError(err);
+  }
+
+  const response =
+    credential.response as AuthenticatorAssertionResponse;
+
+  return {
+    id: credential.id,
+    rawId: bufferToBase64url(credential.rawId),
+    type: 'public-key',
+    response: {
+      clientDataJSON: bufferToBase64url(response.clientDataJSON),
+      authenticatorData: bufferToBase64url(response.authenticatorData),
+      signature: bufferToBase64url(response.signature),
+      userHandle: response.userHandle
+        ? bufferToBase64url(response.userHandle)
+        : undefined,
+    },
+  };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function mapDOMError(err: unknown): PasskeyError {
+  if (
+    err !== null &&
+    typeof err === 'object' &&
+    'code' in err &&
+    'message' in err
+  ) {
+    // Already a PasskeyError
+    return err as PasskeyError;
+  }
+
+  const error = err as DOMException;
+
+  switch (error.name) {
+    case 'NotAllowedError':
+      return { code: 'cancelled', message: error.message || 'User cancelled' };
+    case 'InvalidStateError':
+      return {
+        code: 'invalid_state',
+        message: error.message || 'Credential already exists',
+      };
+    case 'NotSupportedError':
+      return { code: 'not_supported', message: error.message || 'Not supported' };
+    case 'SecurityError':
+      return {
+        code: 'not_allowed',
+        message: error.message || 'Security error (wrong origin or RP ID)',
+      };
+    default:
+      return {
+        code: 'unknown',
+        message: error.message || 'Unknown error',
+      };
+  }
+}

package/src/types.ts

@@ -0,0 +1,160 @@
+// ============================================================================
+// Biometric Authentication Types
+// ============================================================================
+
+export type BiometricType = 'fingerprint' | 'facial_recognition' | 'iris';
+
+export type SecurityLevel =
+  | 'none'
+  | 'device_credential'
+  | 'biometric_weak'
+  | 'biometric_strong';
+
+export type AuthError =
+  | 'not_available'
+  | 'not_enrolled'
+  | 'user_cancel'
+  | 'lockout'
+  | 'system_cancel'
+  | 'passcode_not_set'
+  | 'authentication_failed'
+  | 'unknown';
+
+export interface AuthenticateOptions {
+  /** Message displayed alongside the biometric prompt. */
+  promptMessage?: string;
+  /** Label for the cancel button. */
+  cancelLabel?: string;
+  /** iOS: label for the passcode fallback button. */
+  fallbackLabel?: string;
+  /** Prevent PIN/passcode fallback after biometric failure. */
+  disableDeviceFallback?: boolean;
+  /** Android: require Class 3 (strong) biometric instead of weak. */
+  requireStrongBiometric?: boolean;
+}
+
+export type AuthResult =
+  | { success: true }
+  | { success: false; error: AuthError; message?: string };
+
+// ============================================================================
+// Passkey Types (WebAuthn / FIDO2)
+// ============================================================================
+
+export interface PublicKeyCredentialParam {
+  type: 'public-key';
+  /** COSE algorithm identifier. -7 = ES256, -257 = RS256. */
+  alg: number;
+}
+
+export interface CredentialDescriptor {
+  type: 'public-key';
+  /** Credential ID as base64url string. */
+  id: string;
+  transports?: Array<'usb' | 'ble' | 'nfc' | 'internal' | 'hybrid'>;
+}
+
+export interface PasskeyCreateOptions {
+  /** Base64url-encoded challenge from server. */
+  challenge: string;
+  /** Relying party information. */
+  rp: {
+    id: string;
+    name: string;
+  };
+  /** User information. */
+  user: {
+    /** Base64url-encoded user ID. */
+    id: string;
+    name: string;
+    displayName: string;
+  };
+  /** Supported public key credential parameters. Defaults to ES256 + RS256. */
+  pubKeyCredParams?: PublicKeyCredentialParam[];
+  /** Timeout in milliseconds. */
+  timeout?: number;
+  /** Authenticator selection criteria. */
+  authenticatorSelection?: {
+    authenticatorAttachment?: 'platform' | 'cross-platform';
+    residentKey?: 'required' | 'preferred' | 'discouraged';
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+  };
+  /** Credentials to exclude (prevent re-registration). */
+  excludeCredentials?: CredentialDescriptor[];
+  /** Attestation conveyance preference. */
+  attestation?: 'none' | 'indirect' | 'direct' | 'enterprise';
+}
+
+export interface PasskeyCreateResult {
+  /** Credential ID as base64url string. */
+  id: string;
+  /** Raw credential ID as base64url string. */
+  rawId: string;
+  type: 'public-key';
+  response: {
+    /** Base64url-encoded client data JSON. */
+    clientDataJSON: string;
+    /** Base64url-encoded attestation object. */
+    attestationObject: string;
+  };
+}
+
+export interface PasskeyGetOptions {
+  /** Base64url-encoded challenge from server. */
+  challenge: string;
+  /** Relying party ID. */
+  rpId?: string;
+  /** Allowed credentials. If empty, discoverable credentials are used. */
+  allowCredentials?: CredentialDescriptor[];
+  /** Timeout in milliseconds. */
+  timeout?: number;
+  /** User verification requirement. */
+  userVerification?: 'required' | 'preferred' | 'discouraged';
+}
+
+export interface PasskeyGetResult {
+  /** Credential ID as base64url string. */
+  id: string;
+  /** Raw credential ID as base64url string. */
+  rawId: string;
+  type: 'public-key';
+  response: {
+    /** Base64url-encoded client data JSON. */
+    clientDataJSON: string;
+    /** Base64url-encoded authenticator data. */
+    authenticatorData: string;
+    /** Base64url-encoded signature. */
+    signature: string;
+    /** Base64url-encoded user handle (may be absent). */
+    userHandle?: string;
+  };
+}
+
+export interface PasskeyError {
+  code: 'not_supported' | 'cancelled' | 'invalid_state' | 'not_allowed' | 'unknown';
+  message: string;
+}
+
+// ============================================================================
+// Base64url Helpers (shared)
+// ============================================================================
+
+export function base64urlToBuffer(base64url: string): ArrayBuffer {
+  const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = '='.repeat((4 - (base64.length % 4)) % 4);
+  const binary = atob(base64 + padding);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+export function bufferToBase64url(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}