@tinfoilsh/passkey-kit 0.1.0 → 0.2.1

package/src/storage.ts

@@ -1,69 +1,135 @@
-/**
- * Pluggable local persistence for the SDK's device-side state: the cached
- * PRF output and the credential id this device owns. Adapters are
- * synchronous by design (mirroring the Web Storage API) so callers can
- * read cached state without awaiting.
- *
- * SECURITY: the PRF output cached through an adapter is raw key material —
- * anyone who can read it can re-derive the KEK and unwrap the CEK. The
- * default `localStorage` adapter stores it in plaintext, which is only as
- * strong as the origin's script-injection defenses (an XSS attacker could
- * equally just run the ceremony or exfiltrate decrypted data). Hosts with
- * stricter requirements should supply their own adapter with at-rest
- * protection, or pass `storage: null` to disable caching and re-prompt
- * biometrics instead.
- */
+import { base64ToBytes, bytesToBase64 } from "./codec.js";
+import type { PasskeyKeyProfile } from "./types.js";
 
-export interface StorageAdapter {
-  getItem(key: string): string | null
-  setItem(key: string, value: string): void
-  removeItem(key: string): void
+export interface CachedPRFResult {
+  profile: PasskeyKeyProfile;
+  credentialId: string;
+  prfOutput: Uint8Array;
 }
 
-/**
- * Default adapter backed by `window.localStorage`. Every operation is
- * best-effort: quota errors, privacy-mode failures, blocked-storage
- * contexts (e.g. sandboxed frames, where even touching `localStorage`
- * throws), and SSR (no window) all degrade to no-ops so storage problems
- * never interrupt a passkey ceremony.
- */
-export const browserLocalStorageAdapter: StorageAdapter = {
-  getItem(key: string): string | null {
-    try {
-      if (typeof localStorage === 'undefined') return null
-      return localStorage.getItem(key)
-    } catch {
-      return null
-    }
-  },
-  setItem(key: string, value: string): void {
-    try {
-      if (typeof localStorage === 'undefined') return
-      localStorage.setItem(key, value)
-    } catch {
-      // best-effort
-    }
-  },
-  removeItem(key: string): void {
-    try {
-      if (typeof localStorage === 'undefined') return
-      localStorage.removeItem(key)
-    } catch {
-      // best-effort
-    }
-  },
+export interface PasskeyKeyStorage {
+  loadCachedPRFResult(): CachedPRFResult | null;
+  saveCachedPRFResult(result: CachedPRFResult): void;
+  loadLocalCredentialId(): string | null;
+  saveLocalCredentialId(credentialId: string): void;
+  clear(): void;
 }
 
-/** In-memory adapter for tests and non-browser environments. */
-export function createMemoryStorageAdapter(): StorageAdapter {
-  const store = new Map<string, string>()
+function copyProfile(profile: PasskeyKeyProfile): PasskeyKeyProfile {
   return {
-    getItem: (key) => store.get(key) ?? null,
-    setItem: (key, value) => {
-      store.set(key, value)
+    ...profile,
+    prfSalt: profile.prfSalt.slice(),
+    hkdfInfo: profile.hkdfInfo.slice(),
+  };
+}
+
+function copyCachedResult(result: CachedPRFResult): CachedPRFResult {
+  return {
+    profile: copyProfile(result.profile),
+    credentialId: result.credentialId,
+    prfOutput: result.prfOutput.slice(),
+  };
+}
+
+export function createMemoryPasskeyKeyStorage(): PasskeyKeyStorage {
+  let cached: CachedPRFResult | null = null;
+  let localCredentialId: string | null = null;
+  return {
+    loadCachedPRFResult() {
+      return cached ? copyCachedResult(cached) : null;
+    },
+    saveCachedPRFResult(result) {
+      cached = copyCachedResult(result);
+    },
+    loadLocalCredentialId() {
+      return localCredentialId;
+    },
+    saveLocalCredentialId(credentialId) {
+      localCredentialId = credentialId;
+    },
+    clear() {
+      cached = null;
+      localCredentialId = null;
+    },
+  };
+}
+
+interface SerializedCachedPRFResult {
+  profile: Omit<PasskeyKeyProfile, "prfSalt" | "hkdfInfo"> & {
+    prfSaltBase64: string;
+    hkdfInfoBase64: string;
+  };
+  credentialId: string;
+  prfOutputBase64: string;
+}
+
+/** Stores raw PRF output unencrypted in localStorage under an explicit namespace. */
+export function createInsecureBrowserLocalStoragePasskeyKeyStorage(
+  namespace: string,
+): PasskeyKeyStorage {
+  const prefix = `passkey-key/${encodeURIComponent(namespace)}`;
+  const cachedKey = `${prefix}/cached-prf`;
+  const localCredentialKey = `${prefix}/local-credential`;
+  return {
+    loadCachedPRFResult() {
+      try {
+        if (typeof localStorage === "undefined") return null;
+        const value = localStorage.getItem(cachedKey);
+        if (!value) return null;
+        const stored = JSON.parse(value) as SerializedCachedPRFResult;
+        return {
+          profile: {
+            version: stored.profile.version,
+            relyingPartyId: stored.profile.relyingPartyId,
+            prfSalt: base64ToBytes(stored.profile.prfSaltBase64),
+            hkdfInfo: base64ToBytes(stored.profile.hkdfInfoBase64),
+          },
+          credentialId: stored.credentialId,
+          prfOutput: base64ToBytes(stored.prfOutputBase64),
+        };
+      } catch {
+        return null;
+      }
+    },
+    saveCachedPRFResult(result) {
+      try {
+        if (typeof localStorage === "undefined") return;
+        const serialized: SerializedCachedPRFResult = {
+          profile: {
+            version: result.profile.version,
+            relyingPartyId: result.profile.relyingPartyId,
+            prfSaltBase64: bytesToBase64(result.profile.prfSalt),
+            hkdfInfoBase64: bytesToBase64(result.profile.hkdfInfo),
+          },
+          credentialId: result.credentialId,
+          prfOutputBase64: bytesToBase64(result.prfOutput),
+        };
+        localStorage.setItem(cachedKey, JSON.stringify(serialized));
+      } catch {}
+    },
+    loadLocalCredentialId() {
+      try {
+        if (typeof localStorage === "undefined") return null;
+        return localStorage.getItem(localCredentialKey);
+      } catch {
+        return null;
+      }
+    },
+    saveLocalCredentialId(credentialId) {
+      try {
+        if (typeof localStorage === "undefined") return;
+        localStorage.setItem(localCredentialKey, credentialId);
+      } catch {}
     },
-    removeItem: (key) => {
-      store.delete(key)
+    clear() {
+      try {
+        if (typeof localStorage === "undefined") return;
+        localStorage.removeItem(cachedKey);
+      } catch {}
+      try {
+        if (typeof localStorage === "undefined") return;
+        localStorage.removeItem(localCredentialKey);
+      } catch {}
     },
-  }
+  };
 }

package/src/support.ts

@@ -1,61 +1,47 @@
-/**
- * PRF support detection.
- *
- * Checks whether the current browser/platform supports the WebAuthn PRF
- * extension. This is an optimistic check — actual PRF support is only
- * confirmed when a credential is created with prf.enabled: true in the
- * response. If creation fails, callers should fall back to a manual flow.
- *
- * Detection strategy:
- * 1. Check window.PublicKeyCredential exists (basic WebAuthn support)
- * 2. Check isUserVerifyingPlatformAuthenticatorAvailable() (biometric/PIN authenticator present)
- * 3. Optionally check getClientCapabilities() for explicit PRF support signal (new API, not universal)
- */
-export async function detectPrfSupport(): Promise<boolean> {
-  if (typeof window === 'undefined') {
-    return false
-  }
+import type { PasskeyCapability } from "./types.js";
 
-  if (!window.PublicKeyCredential) {
-    return false
-  }
+function hasWebAuthn(operation: "enroll" | "recover"): boolean {
+  return (
+    typeof navigator !== "undefined" &&
+    !!navigator.credentials &&
+    typeof navigator.credentials[operation === "enroll" ? "create" : "get"] ===
+      "function" &&
+    typeof PublicKeyCredential !== "undefined"
+  );
+}
 
-  // Check that a platform authenticator is available (Face ID, Touch ID, Windows Hello, etc.)
+async function prfCapability(): Promise<PasskeyCapability> {
+  const credentialClass = PublicKeyCredential as typeof PublicKeyCredential & {
+    getClientCapabilities?: () => Promise<Record<string, boolean>>;
+  };
+  if (typeof credentialClass.getClientCapabilities !== "function") return "unknown";
   try {
-    const available =
-      await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
-    if (!available) {
-      return false
-    }
+    const capabilities = await credentialClass.getClientCapabilities();
+    const reported = capabilities["extension:prf"];
+    if (reported === true) return "supported";
+    if (reported === false) return "unsupported";
   } catch {
-    return false
+    return "unknown";
   }
+  return "unknown";
+}
 
-  // If getClientCapabilities is available, use it for a more precise check.
-  // This API is newer and may not be present in all browsers.
+export async function capability(
+  operation: "enroll" | "recover",
+): Promise<PasskeyCapability> {
+  if (!hasWebAuthn(operation)) return "unsupported";
+  if (operation === "recover") return prfCapability();
+  if (
+    typeof PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable !== "function"
+  ) {
+    return "unknown";
+  }
   try {
-    if (typeof PublicKeyCredential.getClientCapabilities === 'function') {
-      const caps = await PublicKeyCredential.getClientCapabilities()
-      if (caps && typeof caps === 'object') {
-        // The shape of this API varies across browser versions.
-        // Chrome returns a map-like object; check for extension-prf or prf key.
-        const hasPrf =
-          (caps as Record<string, boolean>)['extension-prf'] === true ||
-          (caps as Record<string, boolean>)['prf'] === true
-        if (hasPrf) {
-          return true
-        }
-        // If getClientCapabilities is available but doesn't report PRF,
-        // that's a strong negative signal on platforms that implement it.
-        // However, since this API is still evolving, we don't treat absence
-        // as definitive — fall through to the optimistic path.
-      }
+    if (!(await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable())) {
+      return "unsupported";
     }
   } catch {
-    // getClientCapabilities not available or threw — fall through
+    return "unknown";
   }
-
-  // Optimistic: platform authenticator is available, WebAuthn is supported.
-  // Actual PRF support will be confirmed during credential creation.
-  return true
+  return prfCapability();
 }

package/src/types.ts

@@ -1,113 +1,113 @@
-import type { StorageAdapter } from "./storage.js";
-
-/** Structured logging hooks; the SDK never writes to the console itself. */
-export interface PasskeyKitLogger {
-  info?(message: string, metadata?: Record<string, unknown>): void;
-  error?(
-    message: string,
-    error?: unknown,
-    metadata?: Record<string, unknown>,
-  ): void;
-}
-
-export interface PasskeyKitStorageKeys {
-  /** Key under which the cached PRF result is persisted. */
-  prfResult: string;
-  /** Key under which this device's own credential id is persisted. */
-  localCredentialId: string;
-}
-
-/**
- * Overrides for the messages on errors the SDK throws. Useful for branding
- * or localization; the error classes themselves stay the same, so
- * `instanceof` checks are unaffected.
- */
-export interface PasskeyKitErrorMessages {
-  /** Message used for `PrfNotSupportedError`. */
-  prfNotSupported?: string;
-  /** Message used for `PasskeyTimeoutError`. */
-  timeout?: string;
-}
-
-export interface PasskeyKitConfig {
-  /** WebAuthn relying party id (e.g. `example.com`, or `localhost` in dev). */
-  rpId: string;
-  /** Human-readable relying party name shown in passkey prompts. */
-  rpName: string;
-  /**
-   * Input to the PRF `eval.first` salt. Must stay stable across all clients
-   * of the same protocol: changing it changes every derived KEK.
-   * Defaults to the Tinfoil v1 protocol constant.
-   */
-  prfSaltInput?: string | Uint8Array;
-  /**
-   * HKDF info string used for domain separation when deriving the KEK from
-   * the PRF output. Defaults to the Tinfoil v1 protocol constant.
-   */
-  hkdfInfo?: string | Uint8Array;
-  /**
-   * Local persistence for the PRF cache and this device's credential id.
-   * Defaults to a best-effort `localStorage` adapter; pass `null` to
-   * disable local persistence entirely.
-   */
-  storage?: StorageAdapter | null;
-  storageKeys?: Partial<PasskeyKitStorageKeys>;
-  /** Timeout passed to the WebAuthn API (some browsers ignore this). */
-  webauthnTimeoutMs?: number;
-  /**
-   * Hard client-side timeout guarding against providers that never resolve
-   * the WebAuthn promise. When exceeded, `PasskeyTimeoutError` is thrown.
-   */
-  stuckTimeoutMs?: number;
-  /** Custom messages for the errors the SDK throws. */
-  errorMessages?: PasskeyKitErrorMessages;
-  logger?: PasskeyKitLogger;
-}
-
-/** Identity attached to a newly created passkey. */
+import type { PasskeyKeyStorage } from "./storage.js";
+
+export interface PasskeyKeyProfile {
+  version: 1;
+  relyingPartyId: string;
+  prfSalt: Uint8Array;
+  hkdfInfo: Uint8Array;
+}
+
+export interface WrappedKey {
+  profile: PasskeyKeyProfile;
+  credentialId: string;
+  kekIvHex: string;
+  wrappedKeyHex: string;
+}
+
 export interface PasskeyUser {
-  /** Stable opaque user id (becomes the WebAuthn user handle). */
-  id: string;
-  /** Account identifier shown in passkey pickers (usually an email). */
+  id: Uint8Array;
   name: string;
-  /** Friendly display name; falls back to `name` when omitted. */
   displayName?: string;
 }
 
-/** Result of a successful PRF ceremony (create or authenticate). */
-export interface PrfPasskeyResult {
-  /** base64url-encoded credential id. */
+export type PasskeyCapability = "supported" | "unsupported" | "unknown";
+export type PasskeyInteraction = "interactive" | "immediatelyAvailable";
+
+export interface CreateAndWrapKeyInput {
+  user: PasskeyUser;
+  key: Uint8Array;
+  signal?: AbortSignal;
+}
+
+export interface CreatedWrappedKey {
+  credentialId: string;
+  wrappedKey: WrappedKey;
+}
+
+export interface RecoverKeyInput {
+  wrappedKeys: WrappedKey[];
+  preferredCredentialId?: string;
+  signal?: AbortSignal;
+  interaction?: PasskeyInteraction;
+}
+
+export interface EvaluateCredentialInput {
+  credentialIds: string[];
+  preferredCredentialId?: string;
+  signal?: AbortSignal;
+  interaction?: PasskeyInteraction;
+}
+
+export interface PRFResult {
+  output: Uint8Array;
+}
+
+export interface EvaluatedCredential {
   credentialId: string;
-  /** Raw 32-byte PRF output; treat as secret key material. */
-  prfOutput: ArrayBuffer;
+  prfResult: PRFResult;
 }
 
-/** A CEK wrapped under a passkey-derived KEK with AES-256-GCM. */
-export interface WrappedCek {
-  /** base64url-encoded credential id whose PRF output wraps this CEK. */
+export interface WrapKeyWithPRFResultInput {
+  keyMaterial: Uint8Array;
   credentialId: string;
-  /** 12-byte AES-GCM IV, hex-encoded. */
-  kekIvHex: string;
-  /** Wrapped CEK ciphertext (including GCM tag), hex-encoded. */
-  wrappedKeyHex: string;
+  prfResult: PRFResult;
 }
 
-/** Result of the high-level enroll flow: create passkey + wrap CEK. */
-export interface EnrollResult {
+export interface UnwrapKeyWithPRFResultInput {
+  wrappedKey: WrappedKey;
+  prfResult: PRFResult;
+}
+
+export interface RecoveredKey {
   credentialId: string;
-  /** Ciphertext safe to persist server-side. */
-  wrappedCek: WrappedCek;
-  /**
-   * Device-local secret state (PRF output). Already persisted through the
-   * storage adapter when one is configured; returned so hosts with custom
-   * persistence can store it themselves.
-   */
-  prfResult: PrfPasskeyResult;
-}
-
-/** Result of the high-level unlock flow: authenticate + unwrap CEK. */
-export interface UnlockResult {
+  key: Uint8Array;
+}
+
+export interface RewrapKeyInput {
+  key: Uint8Array;
+}
+
+export interface PasskeyKeyManagerConfig {
+  profile: PasskeyKeyProfile;
+  relyingPartyName: string;
+  timeoutMs?: number;
+  storage?: PasskeyKeyStorage;
+}
+
+export interface PasskeyKeyManager {
+  capability(input: {
+    operation: "enroll" | "recover";
+  }): Promise<PasskeyCapability>;
+  createAndWrapKey(input: CreateAndWrapKeyInput): Promise<CreatedWrappedKey>;
+  recoverKey(input: RecoverKeyInput): Promise<RecoveredKey>;
+  evaluateCredential(input: EvaluateCredentialInput): Promise<EvaluatedCredential>;
+  wrapKeyWithPRFResult(input: WrapKeyWithPRFResultInput): Promise<WrappedKey>;
+  unwrapKeyWithPRFResult(input: UnwrapKeyWithPRFResultInput): Promise<Uint8Array>;
+  recoverKeyFromCache(input: RecoverKeyInput): Promise<RecoveredKey | null>;
+  rewrapKeyFromCache(input: RewrapKeyInput): Promise<WrappedKey | null>;
+  clearLocalState(): void;
+  cancelActiveCeremony(): void;
+}
+
+export interface WrappedKeyRecord {
+  version: 1;
+  profile: {
+    version: 1;
+    relyingPartyId: string;
+    prfSalt: string;
+    hkdfInfo: string;
+  };
   credentialId: string;
-  /** The recovered raw 32-byte CEK. */
-  cek: Uint8Array;
+  kekIvHex: string;
+  wrappedKeyHex: string;
 }