@tinfoilsh/passkey-kit 0.1.0 → 0.2.1

package/src/webauthn.ts

@@ -1,258 +1,142 @@
-/**
- * WebAuthn PRF ceremonies: credential creation and assertion with the PRF
- * extension. Pure ceremony logic — persistence of the results is handled
- * by the kit through the hooks on {@link CeremonyContext}.
- */
+import { base64UrlToBytes, bufferSourceToArrayBuffer, bytesToBase64Url } from "./codec.js";
+import { invalidInput, PasskeyKeyError } from "./errors.js";
+import type { PasskeyUser } from "./types.js";
 
-import {
-  base64UrlToBytes,
-  bufferSourceToArrayBuffer,
-  bytesToBase64Url,
-} from "./codec.js";
-import {
-  PasskeyKitError,
-  PasskeyTimeoutError,
-  PrfNotSupportedError,
-} from "./errors.js";
-import type {
-  PasskeyKitErrorMessages,
-  PasskeyKitLogger,
-  PasskeyUser,
-  PrfPasskeyResult,
-} from "./types.js";
+const CHALLENGE_BYTES = 32;
+const MAX_USER_HANDLE_BYTES = 64;
+const PRF_OUTPUT_BYTES = 32;
 
 export interface CeremonyContext {
   rpId: string;
   rpName: string;
-  /** Salt passed to PRF eval.first — the client internally computes
-   *  SHA-256("WebAuthn PRF" || 0x00 || salt). */
-  prfSalt: Uint8Array;
-  webauthnTimeoutMs: number;
-  stuckTimeoutMs: number;
-  errorMessages?: PasskeyKitErrorMessages;
-  logger: PasskeyKitLogger;
-  /** Invoked after every successful PRF ceremony so the kit can cache state. */
-  onPrfResult(result: PrfPasskeyResult, credential: PublicKeyCredential): void;
+  prfInput: Uint8Array;
+  timeoutMs: number;
 }
 
-const MAX_USER_HANDLE_BYTE_COUNT = 64;
-
-async function withStuckTimeout<T>(
-  promise: Promise<T>,
-  ctx: CeremonyContext,
-): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      promise,
-      new Promise<T>((_, reject) => {
-        timer = setTimeout(
-          () => reject(new PasskeyTimeoutError(ctx.errorMessages?.timeout)),
-          ctx.stuckTimeoutMs,
-        );
-      }),
-    ]);
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
-  }
+export interface InternalPrfResult {
+  credentialId: string;
+  prfOutput: Uint8Array;
+  isPlatformAuthenticator: boolean;
 }
 
-/**
- * Create a new PRF-capable passkey for the given user.
- *
- * Returns the credential ID and PRF output, or null if the user cancels.
- * Throws {@link PrfNotSupportedError} when the authenticator cannot supply
- * PRF output and {@link PasskeyTimeoutError} when the provider hangs.
- */
-export async function createPrfPasskey(
-  ctx: CeremonyContext,
-  user: PasskeyUser,
-): Promise<PrfPasskeyResult | null> {
-  const userIdBytes = new TextEncoder().encode(user.id);
-  if (userIdBytes.byteLength > MAX_USER_HANDLE_BYTE_COUNT) {
-    throw new PasskeyKitError(
-      `passkey-kit: user id must be at most ${MAX_USER_HANDLE_BYTE_COUNT} UTF-8 bytes`,
-    );
-  }
-
-  try {
-    const credential = (await withStuckTimeout(
-      navigator.credentials.create({
-        publicKey: {
-          challenge: crypto.getRandomValues(new Uint8Array(32)),
-          rp: { id: ctx.rpId, name: ctx.rpName },
-          user: {
-            id: userIdBytes,
-            name: user.name,
-            displayName: user.displayName || user.name,
-          },
-          pubKeyCredParams: [
-            { type: "public-key", alg: -7 }, // ES256
-            { type: "public-key", alg: -257 }, // RS256 (broader compat)
-          ],
-          authenticatorSelection: {
-            residentKey: "preferred",
-            userVerification: "required",
-          },
-          timeout: ctx.webauthnTimeoutMs,
-          extensions: {
-            prf: { eval: { first: ctx.prfSalt as BufferSource } },
-          },
-        },
-      }),
-      ctx,
-    )) as PublicKeyCredential | null;
-
-    if (!credential) {
-      return null;
-    }
+interface PrfExtensionResults {
+  prf?: {
+    enabled?: boolean;
+    results?: { first?: BufferSource };
+  };
+}
 
-    const extensionResults = credential.getClientExtensionResults();
-    const prfResults = extensionResults.prf;
+function extensionResults(credential: PublicKeyCredential): PrfExtensionResults {
+  return credential.getClientExtensionResults() as PrfExtensionResults;
+}
 
-    if (!prfResults?.enabled) {
-      ctx.logger.info?.("Authenticator does not support PRF", {
-        action: "createPrfPasskey",
-      });
-      throw new PrfNotSupportedError(ctx.errorMessages?.prfNotSupported);
-    }
+function credentialId(credential: PublicKeyCredential): string {
+  const rawId = new Uint8Array(credential.rawId);
+  if (rawId.length === 0) throw invalidInput("credential ID must not be empty");
+  return bytesToBase64Url(rawId);
+}
 
-    const credentialId = bytesToBase64Url(new Uint8Array(credential.rawId));
+function resultFromCredential(credential: PublicKeyCredential): InternalPrfResult {
+  const first = extensionResults(credential).prf?.results?.first;
+  if (!first) {
+    throw new PasskeyKeyError("unsupported", "the authenticator returned no PRF output");
+  }
+  const prfOutput = new Uint8Array(bufferSourceToArrayBuffer(first));
+  if (prfOutput.length !== PRF_OUTPUT_BYTES) {
+    throw invalidInput(`PRF output must be ${PRF_OUTPUT_BYTES} bytes`);
+  }
+  return {
+    credentialId: credentialId(credential),
+    prfOutput,
+    isPlatformAuthenticator: credential.authenticatorAttachment === "platform",
+  };
+}
 
-    // Some authenticators return PRF results during creation, others don't.
-    // "Not all authenticators support evaluating the PRFs during credential
-    // creation so outputs may, or may not, be provided."
-    // — https://w3c.github.io/webauthn/#prf-extension (eval description)
-    if (prfResults.results?.first) {
-      const result: PrfPasskeyResult = {
-        credentialId,
-        prfOutput: bufferSourceToArrayBuffer(prfResults.results.first),
-      };
-      ctx.onPrfResult(result, credential);
-      return result;
-    }
+export async function createPrfCredential(
+  context: CeremonyContext,
+  user: PasskeyUser,
+  signal: AbortSignal,
+): Promise<InternalPrfResult> {
+  if (!(user?.id instanceof Uint8Array) || user.id.length === 0) {
+    throw invalidInput("user.id must be a non-empty Uint8Array");
+  }
+  if (user.id.length > MAX_USER_HANDLE_BYTES) {
+    throw invalidInput(`user.id must be at most ${MAX_USER_HANDLE_BYTES} bytes`);
+  }
+  if (typeof user.name !== "string" || user.name.length === 0) {
+    throw invalidInput("user.name must be a non-empty string");
+  }
+  if (user.displayName !== undefined && (typeof user.displayName !== "string" || !user.displayName)) {
+    throw invalidInput("user.displayName must be a non-empty string");
+  }
 
-    // PRF enabled but no results during create — do an immediate get()
-    ctx.logger.info?.(
-      "PRF enabled but no results during creation, doing immediate auth",
-      { action: "createPrfPasskey" },
+  const credential = (await navigator.credentials.create({
+    signal,
+    publicKey: {
+      challenge: crypto.getRandomValues(new Uint8Array(CHALLENGE_BYTES)),
+      rp: { id: context.rpId, name: context.rpName },
+      user: {
+        id: user.id.slice(),
+        name: user.name,
+        displayName: user.displayName ?? user.name,
+      },
+      pubKeyCredParams: [
+        { type: "public-key", alg: -7 },
+        { type: "public-key", alg: -257 },
+      ],
+      authenticatorSelection: {
+        authenticatorAttachment: "platform",
+        residentKey: "preferred",
+        userVerification: "required",
+      },
+      timeout: context.timeoutMs,
+      extensions: {
+        prf: { eval: { first: context.prfInput.slice() } },
+      } as AuthenticationExtensionsClientInputs,
+    },
+  })) as PublicKeyCredential | null;
+
+  if (!credential) {
+    throw new PasskeyKeyError(
+      "cancelled",
+      "credential creation was cancelled or no eligible credential was available",
     );
-    // Pass throwOnCancel so a user-cancelled assertion surfaces as a
-    // DOMException we can handle below — otherwise a `null` return would
-    // be indistinguishable from "provider returned no PRF output" and we'd
-    // show the misleading "PRF not supported" error for a plain cancel.
-    const postCreateAuth = await authenticatePrfPasskey(ctx, [credentialId], {
-      throwOnCancel: true,
-    });
-    if (!postCreateAuth) {
-      // The provider claimed PRF support during creation but didn't deliver
-      // a PRF output on the immediately-following assertion. Treat this as
-      // a lack of real PRF support rather than a silent failure.
-      throw new PrfNotSupportedError(ctx.errorMessages?.prfNotSupported);
-    }
-    return postCreateAuth;
-  } catch (error) {
-    if (error instanceof PrfNotSupportedError) throw error;
-    if (error instanceof PasskeyTimeoutError) throw error;
-
-    // DOMException with name "NotAllowedError" means the user cancelled
-    if (error instanceof DOMException && error.name === "NotAllowedError") {
-      ctx.logger.info?.("User cancelled passkey creation", {
-        action: "createPrfPasskey",
-      });
-      return null;
-    }
-
-    ctx.logger.error?.("Failed to create PRF passkey", error, {
-      action: "createPrfPasskey",
-    });
-    throw error;
   }
+  const extension = extensionResults(credential).prf;
+  if (!extension?.enabled) {
+    throw new PasskeyKeyError("unsupported", "the authenticator does not support PRF");
+  }
+  if (extension.results?.first) return resultFromCredential(credential);
+
+  return evaluatePrfCredential(context, [credentialId(credential)], signal);
 }
 
-/**
- * Authenticate with an existing PRF passkey to derive the PRF output.
- *
- * @param credentialIds - base64url-encoded credential IDs to allow. Pass all
- *   known PRF credential IDs so the browser can select the right one.
- * @returns The matched credential ID and PRF output, or null on failure/cancel.
- */
-export async function authenticatePrfPasskey(
-  ctx: CeremonyContext,
+export async function evaluatePrfCredential(
+  context: CeremonyContext,
   credentialIds: string[],
-  options: { throwOnCancel?: boolean } = {},
-): Promise<PrfPasskeyResult | null> {
-  const { throwOnCancel = false } = options;
-  const allowCredentials: PublicKeyCredentialDescriptor[] = credentialIds.map(
-    (id) => ({
-      id: base64UrlToBytes(id) as BufferSource,
-      type: "public-key",
-    }),
-  );
-
-  try {
-    const assertion = (await withStuckTimeout(
-      navigator.credentials.get({
-        publicKey: {
-          challenge: crypto.getRandomValues(new Uint8Array(32)),
-          rpId: ctx.rpId,
-          allowCredentials,
-          userVerification: "required",
-          timeout: ctx.webauthnTimeoutMs,
-          extensions: {
-            prf: { eval: { first: ctx.prfSalt as BufferSource } },
-          },
-        },
-      }),
-      ctx,
-    )) as PublicKeyCredential | null;
-
-    if (!assertion) {
-      ctx.logger.info?.("passkey assertion returned no credential", {
-        action: "authenticatePrfPasskey",
-        allowedCredentials: credentialIds.length,
-      });
-      return null;
-    }
-
-    const extensionResults = assertion.getClientExtensionResults();
-    const prfOutput = extensionResults.prf?.results?.first;
-
-    if (!prfOutput) {
-      ctx.logger.error?.("PRF output missing from assertion", undefined, {
-        action: "authenticatePrfPasskey",
-      });
-      throw new PrfNotSupportedError(ctx.errorMessages?.prfNotSupported);
-    }
-
-    const result: PrfPasskeyResult = {
-      credentialId: bytesToBase64Url(new Uint8Array(assertion.rawId)),
-      prfOutput: bufferSourceToArrayBuffer(prfOutput),
-    };
-    ctx.onPrfResult(result, assertion);
-    return result;
-  } catch (error) {
-    if (error instanceof PasskeyTimeoutError) throw error;
-
-    if (error instanceof DOMException && error.name === "NotAllowedError") {
-      // NotAllowedError covers both a user cancel and the case where the
-      // provider has no usable credential for any of the allowed ids
-      // (e.g. the passkey was created in a different browser/profile and
-      // never persisted on this device).
-      ctx.logger.info?.(
-        "passkey authentication not allowed (cancelled or no usable credential)",
-        {
-          action: "authenticatePrfPasskey",
-          allowedCredentials: credentialIds.length,
-        },
-      );
-      if (throwOnCancel) throw error;
-      return null;
-    }
-
-    ctx.logger.error?.("Failed to authenticate with PRF passkey", error, {
-      action: "authenticatePrfPasskey",
-    });
-    throw error;
+  signal: AbortSignal,
+): Promise<InternalPrfResult> {
+  const assertion = (await navigator.credentials.get({
+    signal,
+    publicKey: {
+      challenge: crypto.getRandomValues(new Uint8Array(CHALLENGE_BYTES)),
+      rpId: context.rpId,
+      allowCredentials: credentialIds.map((credentialId) => ({
+        type: "public-key",
+        id: base64UrlToBytes(credentialId) as BufferSource,
+      })),
+      userVerification: "required",
+      timeout: context.timeoutMs,
+      extensions: {
+        prf: { eval: { first: context.prfInput.slice() } },
+      } as AuthenticationExtensionsClientInputs,
+    },
+  })) as PublicKeyCredential | null;
+  if (!assertion) {
+    throw new PasskeyKeyError(
+      "cancelled",
+      "credential evaluation was cancelled or no eligible credential was available",
+    );
   }
+  return resultFromCredential(assertion);
 }

package/src/wrapped-key-record-codec.ts

@@ -0,0 +1,93 @@
+import { bytesToBase64Url } from "./codec.js";
+import {
+  copyAndValidateProfile,
+  decodeCanonicalBase64Url,
+  PROFILE_KEYS,
+  validateWrappedKey,
+} from "./crypto.js";
+import { invalidInput } from "./errors.js";
+import type { WrappedKey, WrappedKeyRecord } from "./types.js";
+
+const RECORD_FIELDS = [
+  "version",
+  "profile",
+  "credentialId",
+  "kekIvHex",
+  "wrappedKeyHex",
+] as const;
+function hasExactFields(value: unknown, fields: readonly string[]): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const keys = Object.keys(value).sort();
+  const expected = [...fields].sort();
+  return keys.length === expected.length && keys.every((key, index) => key === expected[index]);
+}
+
+export function encodeWrappedKeyRecord(wrappedKey: WrappedKey): string {
+  if (!wrappedKey || typeof wrappedKey !== "object") {
+    throw invalidInput("wrapped key is required");
+  }
+  const profile = copyAndValidateProfile(wrappedKey.profile);
+  validateWrappedKey(wrappedKey, profile);
+  const record: WrappedKeyRecord = {
+    version: 1,
+    profile: {
+      version: 1,
+      relyingPartyId: profile.relyingPartyId,
+      prfSalt: bytesToBase64Url(profile.prfSalt),
+      hkdfInfo: bytesToBase64Url(profile.hkdfInfo),
+    },
+    credentialId: wrappedKey.credentialId,
+    kekIvHex: wrappedKey.kekIvHex,
+    wrappedKeyHex: wrappedKey.wrappedKeyHex,
+  };
+  return JSON.stringify(record);
+}
+
+export function decodeWrappedKeyRecord(json: string): WrappedKey {
+  if (typeof json !== "string") throw invalidInput("wrapped key JSON must be a string");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw invalidInput("wrapped key JSON is malformed");
+  }
+  if (!hasExactFields(parsed, RECORD_FIELDS)) {
+    throw invalidInput("wrapped key record has unexpected fields");
+  }
+  if (parsed.version !== 1) throw invalidInput("wrapped key record version must be 1");
+  if (!hasExactFields(parsed.profile, PROFILE_KEYS)) {
+    throw invalidInput("wrapped key profile record has unexpected fields");
+  }
+  if (parsed.profile.version !== 1) {
+    throw invalidInput("wrapped key profile version must be 1");
+  }
+  if (typeof parsed.profile.relyingPartyId !== "string") {
+    throw invalidInput("profile.relyingPartyId must be a string");
+  }
+  if (typeof parsed.credentialId !== "string") {
+    throw invalidInput("credentialId must be a string");
+  }
+  if (typeof parsed.kekIvHex !== "string") {
+    throw invalidInput("kekIvHex must be a string");
+  }
+  if (typeof parsed.wrappedKeyHex !== "string") {
+    throw invalidInput("wrappedKeyHex must be a string");
+  }
+  const wrappedKey: WrappedKey = {
+    profile: {
+      version: 1,
+      relyingPartyId: parsed.profile.relyingPartyId,
+      prfSalt: decodeCanonicalBase64Url(parsed.profile.prfSalt, "profile.prfSalt"),
+      hkdfInfo: decodeCanonicalBase64Url(parsed.profile.hkdfInfo, "profile.hkdfInfo"),
+    },
+    credentialId: parsed.credentialId,
+    kekIvHex: parsed.kekIvHex,
+    wrappedKeyHex: parsed.wrappedKeyHex,
+  };
+  const profile = copyAndValidateProfile(wrappedKey.profile);
+  validateWrappedKey(wrappedKey, profile);
+  return {
+    ...wrappedKey,
+    profile,
+  };
+}

package/dist/protocol.d.ts

@@ -1,13 +0,0 @@
-/**
- * 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 declare const TINFOIL_PRF_SALT_INPUT_V1 = "tinfoil-chat-key-encryption";
-/** HKDF info string for domain separation when deriving the KEK. */
-export declare const TINFOIL_HKDF_INFO_V1 = "tinfoil-chat-kek-v1";
-/** HKDF info string for deriving a stable public CEK identifier. */
-export declare const TINFOIL_KEY_ID_INFO_V1 = "tinfoil-key-id-v1";
-//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,mDAAmD;AACnD,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAE1D,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,sBAAsB,CAAC"}

package/dist/protocol.js

@@ -1,13 +0,0 @@
-/**
- * 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";
-//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,mDAAmD;AACnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEvE,oEAAoE;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC"}

package/src/protocol.ts

@@ -1,15 +0,0 @@
-/**
- * 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";