@tinfoilsh/passkey-kit 0.1.0

package/src/kit.ts

@@ -0,0 +1,333 @@
+/**
+ * The main SDK entry point. `createPasskeyKit(config)` binds relying-party
+ * configuration, protocol constants, and local persistence into a single
+ * object exposing both high-level flows (enroll / unlock / rewrap) and the
+ * lower-level ceremony + crypto building blocks.
+ */
+
+import { base64ToBytes, bytesToBase64 } from "./codec.js";
+import {
+  deriveKeyEncryptionKey as deriveKekFromPrf,
+  unwrapCek,
+  wrapCek,
+} from "./crypto.js";
+import { TINFOIL_HKDF_INFO_V1, TINFOIL_PRF_SALT_INPUT_V1 } from "./protocol.js";
+import { browserLocalStorageAdapter, type StorageAdapter } from "./storage.js";
+import { detectPrfSupport } from "./support.js";
+import type {
+  EnrollResult,
+  PasskeyKitConfig,
+  PasskeyKitStorageKeys,
+  PasskeyUser,
+  PrfPasskeyResult,
+  UnlockResult,
+  WrappedCek,
+} from "./types.js";
+import {
+  authenticatePrfPasskey,
+  createPrfPasskey,
+  type CeremonyContext,
+} from "./webauthn.js";
+
+const DEFAULT_STORAGE_KEYS: PasskeyKitStorageKeys = {
+  prfResult: "tinfoil-secret-passkey-prf-output",
+  localCredentialId: "tinfoil-local-passkey-credential-id",
+};
+
+const DEFAULT_WEBAUTHN_TIMEOUT_MS = 30_000;
+
+// Internal hard timeout to guard against providers (e.g. some
+// password-manager browser extensions) that never resolve the
+// credentials.create/get promise. Kept tight so users aren't left staring
+// at an indefinite spinner; the WebAuthn flow itself should complete well
+// within this window once the provider actually prompts.
+const DEFAULT_STUCK_TIMEOUT_MS = 60_000;
+
+interface PrfCacheEntry {
+  credentialId: string;
+  prfOutput: string; // base64-encoded
+}
+
+export interface PasskeyKit {
+  /** Optimistic device/browser PRF support check (cached per kit). */
+  isPrfSupported(): Promise<boolean>;
+  resetPrfSupportCache(): void;
+
+  /**
+   * Create a new PRF-capable passkey. Returns null when the user cancels;
+   * throws PrfNotSupportedError / PasskeyTimeoutError otherwise on failure.
+   */
+  createPasskey(user: PasskeyUser): Promise<PrfPasskeyResult | null>;
+  /**
+   * Prompt for an assertion against any of the given credential ids and
+   * return the matched credential's PRF output. Null on cancel/failure.
+   */
+  authenticate(
+    credentialIds: string[],
+    options?: { throwOnCancel?: boolean },
+  ): Promise<PrfPasskeyResult | null>;
+  /** Derive the AES-256-GCM KEK from a PRF output (HKDF-SHA-256). */
+  deriveKek(prfOutput: ArrayBuffer | Uint8Array): Promise<CryptoKey>;
+
+  /** Create a passkey and wrap the given CEK under it in one flow. */
+  enroll(opts: {
+    user: PasskeyUser;
+    cek: Uint8Array;
+  }): Promise<EnrollResult | null>;
+  /** Authenticate against the given wrapped CEKs and unwrap the matching one. */
+  unlock(wrappedCeks: WrappedCek[]): Promise<UnlockResult | null>;
+  /**
+   * Unwrap the wrapped CEK matching the cached PRF output without a
+   * biometric prompt. Returns null when nothing is cached, no wrapped CEK
+   * matches the cached credential, or the cached output fails to unwrap;
+   * fall back to `unlock()` in that case.
+   */
+  unlockWithCachedPrf(wrappedCeks: WrappedCek[]): Promise<UnlockResult | null>;
+  /**
+   * Re-wrap a CEK using the cached PRF output (no biometric prompt).
+   * Returns null when nothing is cached.
+   */
+  rewrapWithCachedPrf(cek: Uint8Array): Promise<WrappedCek | null>;
+  /** Wrap a CEK under the KEK of an explicit PRF result. */
+  wrapWithPrfResult(
+    prfResult: PrfPasskeyResult,
+    cek: Uint8Array,
+  ): Promise<WrappedCek>;
+  /** Unwrap a CEK with the KEK of an explicit PRF result. */
+  unwrapWithPrfResult(
+    prfResult: PrfPasskeyResult,
+    wrapped: Pick<WrappedCek, "kekIvHex" | "wrappedKeyHex">,
+  ): Promise<Uint8Array>;
+
+  /**
+   * Cached PRF result from local storage, if any. The PRF output is
+   * deterministic for a given passkey, so it can be reused to avoid
+   * re-prompting biometrics on key updates.
+   */
+  getCachedPrfResult(): PrfPasskeyResult | null;
+  clearCachedPrfResult(): void;
+  /** Credential id owned by this device (platform attachment), if known. */
+  getLocalCredentialId(): string | null;
+  setLocalCredentialId(credentialId: string): void;
+  /** Clear all device-local state (e.g. on sign-out). */
+  clearLocalState(): void;
+}
+
+export function createPasskeyKit(config: PasskeyKitConfig): PasskeyKit {
+  const logger = config.logger ?? {};
+  const storage: StorageAdapter | null =
+    config.storage === undefined ? browserLocalStorageAdapter : config.storage;
+  const storageKeys: PasskeyKitStorageKeys = {
+    ...DEFAULT_STORAGE_KEYS,
+    ...config.storageKeys,
+  };
+  // Byte inputs are snapshotted so later caller-side buffer reuse cannot
+  // silently change the PRF domain or KEK derivation between ceremonies.
+  const prfSalt =
+    typeof config.prfSaltInput === "string" || config.prfSaltInput === undefined
+      ? new TextEncoder().encode(
+          config.prfSaltInput ?? TINFOIL_PRF_SALT_INPUT_V1,
+        )
+      : config.prfSaltInput.slice();
+  const hkdfInfo =
+    config.hkdfInfo === undefined
+      ? TINFOIL_HKDF_INFO_V1
+      : typeof config.hkdfInfo === "string"
+        ? config.hkdfInfo
+        : config.hkdfInfo.slice();
+
+  let prfSupportCache: boolean | null = null;
+
+  function cachePrfResult(result: PrfPasskeyResult): void {
+    if (!storage) return;
+    const entry: PrfCacheEntry = {
+      credentialId: result.credentialId,
+      prfOutput: bytesToBase64(new Uint8Array(result.prfOutput)),
+    };
+    try {
+      storage.setItem(storageKeys.prfResult, JSON.stringify(entry));
+    } catch {
+      // best-effort
+    }
+  }
+
+  function getCachedPrfResult(): PrfPasskeyResult | null {
+    if (!storage) return null;
+    try {
+      const raw = storage.getItem(storageKeys.prfResult);
+      if (!raw) return null;
+      const entry = JSON.parse(raw) as PrfCacheEntry;
+      return {
+        credentialId: entry.credentialId,
+        prfOutput: base64ToBytes(entry.prfOutput).buffer as ArrayBuffer,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  function setLocalCredentialId(credentialId: string): void {
+    storage?.setItem(storageKeys.localCredentialId, credentialId);
+  }
+
+  // Cross-device hybrid (QR-paired phone, etc.) reports
+  // `authenticatorAttachment === 'cross-platform'` on the resulting
+  // credential. Caching the cred id in that case would make this
+  // device look like it has its own passkey when in reality the user
+  // just borrowed another device's passkey for a one-shot unlock.
+  // Per WebAuthn L3 §5.2.1, we only treat `authenticatorAttachment`
+  // of `'platform'` as "this device truly owns this credential".
+  function onPrfResult(
+    result: PrfPasskeyResult,
+    credential: PublicKeyCredential,
+  ): void {
+    cachePrfResult(result);
+    if (credential.authenticatorAttachment === "platform") {
+      try {
+        setLocalCredentialId(result.credentialId);
+      } catch {
+        // best-effort: a throwing custom adapter must not discard the
+        // ceremony result
+      }
+    }
+  }
+
+  const ceremonyContext: CeremonyContext = {
+    rpId: config.rpId,
+    rpName: config.rpName,
+    prfSalt,
+    webauthnTimeoutMs: config.webauthnTimeoutMs ?? DEFAULT_WEBAUTHN_TIMEOUT_MS,
+    stuckTimeoutMs: config.stuckTimeoutMs ?? DEFAULT_STUCK_TIMEOUT_MS,
+    errorMessages: config.errorMessages,
+    logger,
+    onPrfResult,
+  };
+
+  const deriveKek = (prfOutput: ArrayBuffer | Uint8Array) =>
+    deriveKekFromPrf(prfOutput, hkdfInfo);
+
+  async function wrapWithPrfResult(
+    prfResult: PrfPasskeyResult,
+    cek: Uint8Array,
+  ): Promise<WrappedCek> {
+    const kek = await deriveKek(prfResult.prfOutput);
+    return wrapCek({ credentialId: prfResult.credentialId, kek, cek });
+  }
+
+  return {
+    async isPrfSupported(): Promise<boolean> {
+      if (prfSupportCache !== null) return prfSupportCache;
+      prfSupportCache = await detectPrfSupport();
+      return prfSupportCache;
+    },
+
+    resetPrfSupportCache(): void {
+      prfSupportCache = null;
+    },
+
+    createPasskey(user: PasskeyUser): Promise<PrfPasskeyResult | null> {
+      return createPrfPasskey(ceremonyContext, user);
+    },
+
+    async authenticate(
+      credentialIds: string[],
+      options: { throwOnCancel?: boolean } = {},
+    ): Promise<PrfPasskeyResult | null> {
+      // An empty allowCredentials list would start a discoverable-passkey
+      // ceremony against ANY credential, breaking the "only the supplied
+      // ids" contract.
+      if (credentialIds.length === 0) return null;
+      return authenticatePrfPasskey(ceremonyContext, credentialIds, options);
+    },
+
+    deriveKek,
+
+    async enroll(opts: {
+      user: PasskeyUser;
+      cek: Uint8Array;
+    }): Promise<EnrollResult | null> {
+      const prfResult = await createPrfPasskey(ceremonyContext, opts.user);
+      if (!prfResult) return null;
+      const wrappedCek = await wrapWithPrfResult(prfResult, opts.cek);
+      return { credentialId: prfResult.credentialId, wrappedCek, prfResult };
+    },
+
+    async unlock(wrappedCeks: WrappedCek[]): Promise<UnlockResult | null> {
+      if (wrappedCeks.length === 0) return null;
+      const prfResult = await authenticatePrfPasskey(
+        ceremonyContext,
+        wrappedCeks.map((w) => w.credentialId),
+      );
+      if (!prfResult) return null;
+      const match = wrappedCeks.find(
+        (w) => w.credentialId === prfResult.credentialId,
+      );
+      if (!match) {
+        logger.error?.(
+          "assertion matched a credential with no wrapped CEK",
+          undefined,
+          { action: "unlock", credentialId: prfResult.credentialId },
+        );
+        return null;
+      }
+      const kek = await deriveKek(prfResult.prfOutput);
+      const cek = await unwrapCek(kek, match);
+      return { credentialId: prfResult.credentialId, cek };
+    },
+
+    async unlockWithCachedPrf(
+      wrappedCeks: WrappedCek[],
+    ): Promise<UnlockResult | null> {
+      const cached = getCachedPrfResult();
+      if (!cached) return null;
+      const match = wrappedCeks.find(
+        (w) => w.credentialId === cached.credentialId,
+      );
+      if (!match) return null;
+      try {
+        const kek = await deriveKek(cached.prfOutput);
+        const cek = await unwrapCek(kek, match);
+        return { credentialId: cached.credentialId, cek };
+      } catch (error) {
+        logger.error?.("failed to unwrap CEK with cached PRF output", error, {
+          action: "unlockWithCachedPrf",
+          credentialId: cached.credentialId,
+        });
+        return null;
+      }
+    },
+
+    async rewrapWithCachedPrf(cek: Uint8Array): Promise<WrappedCek | null> {
+      const cached = getCachedPrfResult();
+      if (!cached) return null;
+      return wrapWithPrfResult(cached, cek);
+    },
+
+    wrapWithPrfResult,
+
+    async unwrapWithPrfResult(
+      prfResult: PrfPasskeyResult,
+      wrapped: Pick<WrappedCek, "kekIvHex" | "wrappedKeyHex">,
+    ): Promise<Uint8Array> {
+      const kek = await deriveKek(prfResult.prfOutput);
+      return unwrapCek(kek, wrapped);
+    },
+
+    getCachedPrfResult,
+
+    clearCachedPrfResult(): void {
+      storage?.removeItem(storageKeys.prfResult);
+    },
+
+    getLocalCredentialId(): string | null {
+      return storage?.getItem(storageKeys.localCredentialId) ?? null;
+    },
+
+    setLocalCredentialId,
+
+    clearLocalState(): void {
+      storage?.removeItem(storageKeys.prfResult);
+      storage?.removeItem(storageKeys.localCredentialId);
+    },
+  };
+}

package/src/protocol.ts

@@ -0,0 +1,15 @@
+/**
+ * Tinfoil v1 protocol constants. Every client wrapping the same CEK must
+ * use identical values: the PRF salt input and HKDF info string both feed
+ * the KEK derivation, so changing either changes every derived KEK.
+ * Override both to establish a new protocol domain.
+ */
+
+/** Input to the WebAuthn PRF `eval.first` salt. */
+export const TINFOIL_PRF_SALT_INPUT_V1 = "tinfoil-chat-key-encryption";
+
+/** HKDF info string for domain separation when deriving the KEK. */
+export const TINFOIL_HKDF_INFO_V1 = "tinfoil-chat-kek-v1";
+
+/** HKDF info string for deriving a stable public CEK identifier. */
+export const TINFOIL_KEY_ID_INFO_V1 = "tinfoil-key-id-v1";

package/src/storage.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+
+export interface StorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+
+/**
+ * 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
+    }
+  },
+}
+
+/** In-memory adapter for tests and non-browser environments. */
+export function createMemoryStorageAdapter(): StorageAdapter {
+  const store = new Map<string, string>()
+  return {
+    getItem: (key) => store.get(key) ?? null,
+    setItem: (key, value) => {
+      store.set(key, value)
+    },
+    removeItem: (key) => {
+      store.delete(key)
+    },
+  }
+}

package/src/support.ts

@@ -0,0 +1,61 @@
+/**
+ * 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
+  }
+
+  if (!window.PublicKeyCredential) {
+    return false
+  }
+
+  // Check that a platform authenticator is available (Face ID, Touch ID, Windows Hello, etc.)
+  try {
+    const available =
+      await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
+    if (!available) {
+      return false
+    }
+  } catch {
+    return false
+  }
+
+  // If getClientCapabilities is available, use it for a more precise check.
+  // This API is newer and may not be present in all browsers.
+  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.
+      }
+    }
+  } catch {
+    // getClientCapabilities not available or threw — fall through
+  }
+
+  // Optimistic: platform authenticator is available, WebAuthn is supported.
+  // Actual PRF support will be confirmed during credential creation.
+  return true
+}

package/src/types.ts

@@ -0,0 +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. */
+export interface PasskeyUser {
+  /** Stable opaque user id (becomes the WebAuthn user handle). */
+  id: string;
+  /** Account identifier shown in passkey pickers (usually an email). */
+  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. */
+  credentialId: string;
+  /** Raw 32-byte PRF output; treat as secret key material. */
+  prfOutput: ArrayBuffer;
+}
+
+/** 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. */
+  credentialId: string;
+  /** 12-byte AES-GCM IV, hex-encoded. */
+  kekIvHex: string;
+  /** Wrapped CEK ciphertext (including GCM tag), hex-encoded. */
+  wrappedKeyHex: string;
+}
+
+/** Result of the high-level enroll flow: create passkey + wrap CEK. */
+export interface EnrollResult {
+  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 {
+  credentialId: string;
+  /** The recovered raw 32-byte CEK. */
+  cek: Uint8Array;
+}