@dwk/webauthn 0.1.0-beta.0

package/dist/verify.js

@@ -0,0 +1,277 @@
+/**
+ * The WebAuthn ceremony verification core: parsing `clientDataJSON` and
+ * authenticator data, then verifying a registration (attestation) and an
+ * authentication (assertion) per the
+ * [W3C WebAuthn Level 3](https://www.w3.org/TR/webauthn-3/) verification
+ * procedures (§7.1 and §7.2).
+ *
+ * These functions are **pure** and runtime-agnostic — plain-data in, result
+ * out, Web Crypto the only I/O — so they unit-test in isolation and never read
+ * Cloudflare bindings. The relying party state (single-use challenges, stored
+ * credential records, the signature counter) lives in the Durable Object, which
+ * supplies the expected values to these functions and persists what they return.
+ *
+ * Attestation scope: the relying party requests `attestation: "none"`, so the
+ * accepted attestation statement formats are `none` and `packed` *self*
+ * attestation (no `x5c`). Verifying a full attestation-certificate chain (basic
+ * / AttCA attestation) is intentionally out of scope — it proves authenticator
+ * provenance, which a personal-site relying party does not need. A format
+ * carrying `x5c` is rejected rather than silently trusted.
+ */
+import { decodeFirst, CborError } from "./cbor";
+import { coseToKey, cryptoParamsForCoseAlg, derToRawEcdsaSignature, CoseError, } from "./cose";
+import { bytesEqual, bytesToBase64url, bytesToUtf8, normalizeBase64url, sha256, } from "./encoding";
+/** Parse `clientDataJSON` bytes, or `null` if it is not a valid client-data object. */
+export function parseClientData(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bytesToUtf8(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const obj = parsed;
+    if (typeof obj.type !== "string" ||
+        typeof obj.challenge !== "string" ||
+        typeof obj.origin !== "string") {
+        return null;
+    }
+    return {
+        type: obj.type,
+        challenge: obj.challenge,
+        origin: obj.origin,
+        ...(typeof obj.crossOrigin === "boolean"
+            ? { crossOrigin: obj.crossOrigin }
+            : {}),
+    };
+}
+/**
+ * Parse authenticator data. The fixed header is 37 bytes (32 rpIdHash + 1 flags
+ * + 4 signCount); when the AT flag is set, attested credential data follows
+ * (16 aaguid + 2 credentialIdLength + L credentialId + the COSE public key).
+ * Returns `null` on any structural problem.
+ */
+export function parseAuthenticatorData(bytes) {
+    if (bytes.length < 37)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const rpIdHash = bytes.subarray(0, 32);
+    const flagsByte = bytes[32];
+    const flags = {
+        up: (flagsByte & 0x01) !== 0,
+        uv: (flagsByte & 0x04) !== 0,
+        at: (flagsByte & 0x40) !== 0,
+        ed: (flagsByte & 0x80) !== 0,
+    };
+    const signCount = view.getUint32(33);
+    if (!flags.at) {
+        return { rpIdHash, flags, signCount };
+    }
+    // Attested credential data follows the fixed header.
+    if (bytes.length < 55)
+        return null;
+    const aaguid = bytes.subarray(37, 53);
+    const credentialIdLength = view.getUint16(53);
+    const idStart = 55;
+    const idEnd = idStart + credentialIdLength;
+    if (idEnd > bytes.length)
+        return null;
+    const credentialId = bytes.subarray(idStart, idEnd);
+    let decoded;
+    try {
+        decoded = decodeFirst(bytes, idEnd);
+    }
+    catch (error) {
+        if (error instanceof CborError)
+            return null;
+        throw error;
+    }
+    if (!(decoded.value instanceof Map))
+        return null;
+    return {
+        rpIdHash,
+        flags,
+        signCount,
+        attestedCredentialData: {
+            aaguid,
+            credentialId,
+            credentialPublicKey: decoded.value,
+        },
+    };
+}
+function reject(reason) {
+    return { verified: false, reason };
+}
+/** Shared `clientDataJSON` checks for both ceremonies. */
+function checkClientData(clientDataJSON, expectedType, expectedChallenge, expectedOrigins) {
+    const clientData = parseClientData(clientDataJSON);
+    if (clientData === null)
+        return "client_data_malformed";
+    if (clientData.type !== expectedType)
+        return "client_data_type";
+    if (normalizeBase64url(clientData.challenge) !==
+        normalizeBase64url(expectedChallenge)) {
+        return "challenge_mismatch";
+    }
+    if (!expectedOrigins.includes(clientData.origin))
+        return "origin_mismatch";
+    return clientData;
+}
+/** Verify a registration (attestation) ceremony (WebAuthn §7.1). */
+export async function verifyRegistration(input) {
+    const clientData = checkClientData(input.clientDataJSON, "webauthn.create", input.expectedChallenge, input.expectedOrigins);
+    if (typeof clientData === "string")
+        return reject(clientData);
+    // Decode the attestation object: { fmt, attStmt, authData }.
+    let attestation;
+    try {
+        attestation = decodeFirst(input.attestationObject).value;
+    }
+    catch (error) {
+        if (error instanceof CborError)
+            return reject("attestation_malformed");
+        throw error;
+    }
+    if (!(attestation instanceof Map))
+        return reject("attestation_malformed");
+    const fmt = attestation.get("fmt");
+    const authDataBytes = attestation.get("authData");
+    const attStmt = attestation.get("attStmt");
+    if (typeof fmt !== "string" || !(authDataBytes instanceof Uint8Array)) {
+        return reject("attestation_malformed");
+    }
+    const authData = parseAuthenticatorData(authDataBytes);
+    if (authData === null)
+        return reject("auth_data_malformed");
+    const rpCheck = await checkRpAndFlags(authData, input);
+    if (rpCheck !== null)
+        return reject(rpCheck);
+    if (!authData.attestedCredentialData)
+        return reject("no_credential_data");
+    // Resolve the credential public key from its COSE_Key.
+    let coseKey;
+    try {
+        coseKey = coseToKey(authData.attestedCredentialData.credentialPublicKey);
+    }
+    catch (error) {
+        if (error instanceof CoseError)
+            return reject("credential_key_unsupported");
+        throw error;
+    }
+    if (cryptoParamsForCoseAlg(coseKey.alg) === null) {
+        return reject("credential_key_unsupported");
+    }
+    // Verify the attestation statement (none / packed self-attestation only).
+    const attResult = await verifyAttestationStatement(fmt, attStmt, authDataBytes, input.clientDataJSON, coseKey.alg, coseKey.jwk);
+    if (attResult !== null)
+        return reject(attResult);
+    return {
+        verified: true,
+        credential: {
+            id: bytesToBase64url(authData.attestedCredentialData.credentialId),
+            publicKeyJwk: coseKey.jwk,
+            alg: coseKey.alg,
+            counter: authData.signCount,
+            aaguid: bytesToBase64url(authData.attestedCredentialData.aaguid),
+        },
+    };
+}
+/**
+ * Verify the supported attestation statement formats. Returns `null` on success
+ * or a failure reason. `none` carries no statement. `packed` *self*-attestation
+ * signs `authData ‖ SHA-256(clientDataJSON)` with the credential's own private
+ * key, so it verifies against the just-extracted credential public key; a
+ * `packed` statement carrying `x5c` (full chain) is unsupported.
+ */
+async function verifyAttestationStatement(fmt, attStmt, authDataBytes, clientDataJSON, credentialAlg, credentialJwk) {
+    if (fmt === "none")
+        return null;
+    if (fmt !== "packed")
+        return "attestation_format_unsupported";
+    if (!(attStmt instanceof Map))
+        return "attestation_malformed";
+    // Full attestation-certificate chains are out of scope.
+    if (attStmt.has("x5c"))
+        return "attestation_format_unsupported";
+    const alg = attStmt.get("alg");
+    const sig = attStmt.get("sig");
+    if (typeof alg !== "number" || !(sig instanceof Uint8Array)) {
+        return "attestation_malformed";
+    }
+    // Self attestation MUST use the credential key's algorithm.
+    if (alg !== credentialAlg)
+        return "attestation_format_unsupported";
+    const clientDataHash = await sha256(clientDataJSON);
+    const signedData = concat(authDataBytes, clientDataHash);
+    const ok = await verifySignature(credentialJwk, alg, sig, signedData);
+    return ok ? null : "signature_invalid";
+}
+/** Verify an authentication (assertion) ceremony (WebAuthn §7.2). */
+export async function verifyAuthentication(input) {
+    const clientData = checkClientData(input.clientDataJSON, "webauthn.get", input.expectedChallenge, input.expectedOrigins);
+    if (typeof clientData === "string")
+        return reject(clientData);
+    const authData = parseAuthenticatorData(input.authenticatorData);
+    if (authData === null)
+        return reject("auth_data_malformed");
+    const rpCheck = await checkRpAndFlags(authData, input);
+    if (rpCheck !== null)
+        return reject(rpCheck);
+    // Signature is over authenticatorData ‖ SHA-256(clientDataJSON).
+    const clientDataHash = await sha256(input.clientDataJSON);
+    const signedData = concat(input.authenticatorData, clientDataHash);
+    const ok = await verifySignature(input.credentialPublicKeyJwk, input.credentialAlg, input.signature, signedData);
+    if (!ok)
+        return reject("signature_invalid");
+    // Cloned-authenticator detection (WebAuthn §7.2 step 21): when either counter
+    // is non-zero the new value MUST be strictly greater than the stored one.
+    if ((authData.signCount !== 0 || input.storedCounter !== 0) &&
+        authData.signCount <= input.storedCounter) {
+        return reject("counter_regression");
+    }
+    return { verified: true, newCounter: authData.signCount };
+}
+/** Verify the rpIdHash and the User Present / User Verified flags. */
+async function checkRpAndFlags(authData, input) {
+    const expectedHash = await sha256(new TextEncoder().encode(input.expectedRpId));
+    if (!bytesEqual(authData.rpIdHash, expectedHash))
+        return "rp_id_mismatch";
+    if (!authData.flags.up)
+        return "user_not_present";
+    if (input.requireUserVerification && !authData.flags.uv) {
+        return "user_not_verified";
+    }
+    return null;
+}
+/** Import a JWK for the COSE alg and verify a signature, normalizing EC DER. */
+async function verifySignature(jwk, alg, signature, signedData) {
+    const params = cryptoParamsForCoseAlg(alg);
+    if (params === null)
+        return false;
+    let rawSignature = signature;
+    if (params.ec) {
+        try {
+            rawSignature = derToRawEcdsaSignature(signature, params.ecSignatureBytes);
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        const key = await crypto.subtle.importKey("jwk", jwk, params.importParams, false, ["verify"]);
+        return await crypto.subtle.verify(params.verifyParams, key, rawSignature, signedData);
+    }
+    catch {
+        return false;
+    }
+}
+/** Concatenate two byte arrays into one. */
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dwk/webauthn",
+  "version": "0.1.0-beta.0",
+  "description": "WebAuthn / passkeys relying party: registration + authentication ceremonies over a per-RP Durable Object for challenge state and credential records.",
+  "keywords": [
+    "webauthn",
+    "passkeys",
+    "fido2",
+    "relying-party",
+    "attestation",
+    "assertion",
+    "cloudflare-workers",
+    "durable-objects"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/webauthn#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/webauthn"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test-harness.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/log": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/cbor.ts

@@ -0,0 +1,168 @@
+/**
+ * A minimal CBOR (RFC 8949) decoder — only the subset WebAuthn needs.
+ *
+ * Two WebAuthn structures are CBOR: the attestation object (a string-keyed map
+ * wrapping `fmt` / `attStmt` / `authData`) and the credential public key (a
+ * COSE_Key, an integer-keyed map). Decoding those needs unsigned and negative
+ * integers, byte and text strings, arrays, and maps — nothing else. We
+ * deliberately do **not** pull a general CBOR library: the script-size budget is
+ * tight (see `spec/non-functional-requirements.md`) and a focused decoder is
+ * easy to audit.
+ *
+ * Maps decode to `Map` so integer COSE labels survive as keys (a plain object
+ * would coerce them to strings and collide negative/positive labels by string
+ * form). The decoder reports how many bytes it consumed so a caller can locate
+ * the bytes that follow a variable-length structure (the COSE key embedded in
+ * authenticator data is followed by optional extension bytes).
+ */
+
+/** A decoded CBOR value (the subset this decoder produces). */
+export type CborValue =
+  | number
+  | bigint
+  | string
+  | Uint8Array
+  | CborValue[]
+  | Map<CborValue, CborValue>;
+
+/** A decoded value together with the number of input bytes it consumed. */
+export interface CborDecoded {
+  readonly value: CborValue;
+  readonly length: number;
+}
+
+/** Thrown when the input is not valid CBOR (or uses an unsupported feature). */
+export class CborError extends Error {}
+
+/**
+ * Decode the first CBOR data item starting at `start`. Returns the value and
+ * the number of bytes consumed; trailing bytes are ignored (the caller decides
+ * whether they are allowed).
+ */
+export function decodeFirst(bytes: Uint8Array, start = 0): CborDecoded {
+  const reader = new Reader(bytes, start);
+  const value = reader.readItem();
+  return { value, length: reader.offset - start };
+}
+
+class Reader {
+  offset: number;
+  readonly #bytes: Uint8Array;
+  readonly #view: DataView;
+
+  constructor(bytes: Uint8Array, start: number) {
+    this.#bytes = bytes;
+    this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    this.offset = start;
+  }
+
+  readItem(): CborValue {
+    const initial = this.#byte();
+    const major = initial >> 5;
+    const info = initial & 0x1f;
+
+    switch (major) {
+      case 0: // unsigned integer
+        return this.#argument(info);
+      case 1: {
+        // negative integer: encodes -(n + 1)
+        const n = this.#argument(info);
+        return typeof n === "bigint" ? -(n + 1n) : -(n + 1);
+      }
+      case 2: // byte string
+        return this.#bytesOfLength(this.#lengthArgument(info));
+      case 3: // text string
+        return new TextDecoder().decode(
+          this.#bytesOfLength(this.#lengthArgument(info)),
+        );
+      case 4: {
+        // array
+        const len = this.#lengthArgument(info);
+        const items: CborValue[] = [];
+        for (let i = 0; i < len; i++) items.push(this.readItem());
+        return items;
+      }
+      case 5: {
+        // map
+        const len = this.#lengthArgument(info);
+        const map = new Map<CborValue, CborValue>();
+        for (let i = 0; i < len; i++) {
+          const key = this.readItem();
+          map.set(key, this.readItem());
+        }
+        return map;
+      }
+      default:
+        // Tags (6) and simple/float (7) are not used by the WebAuthn subset.
+        throw new CborError(`unsupported CBOR major type ${major}`);
+    }
+  }
+
+  /** Read the integer argument that follows the initial byte. */
+  #argument(info: number): number | bigint {
+    if (info < 24) return info;
+    switch (info) {
+      case 24:
+        return this.#byte();
+      case 25: {
+        this.#need(2);
+        const v = this.#view.getUint16(this.offset);
+        this.offset += 2;
+        return v;
+      }
+      case 26: {
+        this.#need(4);
+        const v = this.#view.getUint32(this.offset);
+        this.offset += 4;
+        return v;
+      }
+      case 27: {
+        this.#need(8);
+        const v = this.#view.getBigUint64(this.offset);
+        this.offset += 8;
+        // Collapse to a number when it fits, so callers compare with `===`.
+        return v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v;
+      }
+      default:
+        // 28-30 are reserved; 31 (indefinite length) is unsupported here.
+        throw new CborError(`unsupported CBOR additional info ${info}`);
+    }
+  }
+
+  /** Like {@link #argument} but as a JS number bounded for use as a length. */
+  #lengthArgument(info: number): number {
+    const value = this.#argument(info);
+    if (typeof value === "bigint" || value > this.#bytes.length) {
+      throw new CborError("CBOR length out of range");
+    }
+    return value;
+  }
+
+  #byte(): number {
+    if (this.offset >= this.#bytes.length) {
+      throw new CborError("unexpected end of CBOR input");
+    }
+    return this.#bytes[this.offset++]!;
+  }
+
+  /**
+   * Assert `n` more bytes are available before a multi-byte read. Without this,
+   * a truncated argument would let `DataView` throw a native `RangeError` that
+   * escapes the `CborError` contract callers rely on.
+   */
+  #need(n: number): void {
+    if (this.offset + n > this.#bytes.length) {
+      throw new CborError("unexpected end of CBOR input");
+    }
+  }
+
+  #bytesOfLength(length: number): Uint8Array {
+    const end = this.offset + length;
+    if (end > this.#bytes.length) {
+      throw new CborError("unexpected end of CBOR input");
+    }
+    const slice = this.#bytes.subarray(this.offset, end);
+    this.offset = end;
+    return slice;
+  }
+}

package/src/config.ts

@@ -0,0 +1,179 @@
+/**
+ * Configuration, the declared Cloudflare `Env` fragment, and config resolution
+ * for `@dwk/webauthn`.
+ *
+ * Per the composition contract the package never reads the global environment
+ * directly: the relying party id, expected origins, accepted algorithms, and
+ * TTLs are all passed into {@link createWebAuthn}, so the handler can be
+ * instantiated multiple times and unit-tested in isolation. The only runtime
+ * coupling is the per-relying-party Durable Object namespace, and a missing
+ * binding fails loudly at startup.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+
+import { DEFAULT_COSE_ALGORITHMS } from "./cose";
+import type { WebAuthnObject } from "./rp";
+
+/** Cloudflare bindings required by the WebAuthn handler and Durable Object. */
+export interface WebAuthnEnv {
+  /**
+   * Durable Object namespace for the per-relying-party class
+   * ({@link WebAuthnObject}). It owns short-TTL challenge state and the
+   * credential records — both strongly consistent, never KV (staleness in
+   * either is a security bug).
+   */
+  readonly WEBAUTHN: DurableObjectNamespace<WebAuthnObject>;
+}
+
+/** Configuration passed to {@link createWebAuthn}. */
+export interface WebAuthnConfig {
+  /**
+   * The relying party id: the effective domain credentials are scoped to, e.g.
+   * `example.com`. MUST be a registrable suffix of every accepted origin's
+   * host. The authenticator hashes this into `rpIdHash`.
+   */
+  readonly rpId: string;
+
+  /** Human-readable relying party name shown in the authenticator UI. */
+  readonly rpName: string;
+
+  /**
+   * Acceptable client origin(s), e.g. `https://example.com`. The browser puts
+   * the ceremony origin in `clientDataJSON`; it must match one of these exactly.
+   */
+  readonly origin: string | readonly string[];
+
+  /**
+   * Accepted COSE signature algorithm identifiers, most-preferred first, offered
+   * as `pubKeyCredParams`. Defaults to `[-7, -257]` (ES256, RS256).
+   */
+  readonly algorithms?: readonly number[];
+
+  /** Challenge lifetime in seconds. Defaults to 300 (5 minutes). */
+  readonly challengeTtlSeconds?: number;
+
+  /** Ceremony timeout in milliseconds advertised to the client. Defaults to 60000. */
+  readonly timeoutMs?: number;
+
+  /**
+   * User-verification requirement for both ceremonies. `"required"` additionally
+   * makes the verifier reject an assertion whose UV flag is unset. Defaults to
+   * `"preferred"`.
+   */
+  readonly userVerification?: UserVerificationRequirement;
+
+  /** Injectable clock (epoch ms) for deterministic tests. Defaults to `Date.now`. */
+  readonly now?: () => number;
+
+  /** Logger for ceremony outcomes; defaults to a no-op. */
+  readonly logger?: Logger;
+
+  /** Metrics sink for ceremony outcomes; defaults to a no-op. */
+  readonly metrics?: Metrics;
+}
+
+/** WebAuthn user-verification requirement values. */
+export type UserVerificationRequirement =
+  | "required"
+  | "preferred"
+  | "discouraged";
+
+/** Fully-resolved configuration with defaults applied. */
+export interface ResolvedConfig {
+  readonly rpId: string;
+  readonly rpName: string;
+  readonly origins: readonly string[];
+  readonly algorithms: readonly number[];
+  readonly challengeTtlSeconds: number;
+  readonly timeoutMs: number;
+  readonly userVerification: UserVerificationRequirement;
+  readonly now: () => number;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/**
+ * The serializable subset of resolved config the front door forwards to the
+ * Durable Object (which cannot receive the injected logger/metrics/clock).
+ */
+export interface ForwardedConfig {
+  readonly rpId: string;
+  readonly rpName: string;
+  readonly origins: readonly string[];
+  readonly algorithms: readonly number[];
+  readonly challengeTtlSeconds: number;
+  readonly timeoutMs: number;
+  readonly userVerification: UserVerificationRequirement;
+}
+
+/** Internal headers the trusted front door uses to drive the Durable Object. */
+export const INTERNAL_HEADERS = {
+  /** Which ceremony step to run (see {@link WebAuthnOperation}). */
+  op: "x-webauthn-op",
+  /** JSON-encoded {@link ForwardedConfig}. */
+  config: "x-webauthn-config",
+  /** Current time (epoch ms) from the injected clock, for TTL decisions. */
+  now: "x-webauthn-now",
+  /** DO→front-door: the ceremony outcome event name, logged then stripped. */
+  event: "x-webauthn-event",
+  /** DO→front-door: a stable failure reason when the ceremony was rejected. */
+  reason: "x-webauthn-reason",
+} as const;
+
+/** The four ceremony steps the handler routes. */
+export type WebAuthnOperation =
+  | "register/options"
+  | "register/verify"
+  | "authenticate/options"
+  | "authenticate/verify";
+
+const DEFAULT_CHALLENGE_TTL_SECONDS = 300;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/** Apply defaults and derive values from raw {@link WebAuthnConfig}. */
+export function resolveConfig(config: WebAuthnConfig): ResolvedConfig {
+  if (!config.rpId) throw new Error("@dwk/webauthn: `rpId` is required");
+  if (!config.rpName) throw new Error("@dwk/webauthn: `rpName` is required");
+
+  const origins =
+    typeof config.origin === "string" ? [config.origin] : [...config.origin];
+  if (origins.length === 0) {
+    throw new Error("@dwk/webauthn: at least one `origin` is required");
+  }
+
+  const algorithms =
+    config.algorithms === undefined
+      ? [...DEFAULT_COSE_ALGORITHMS]
+      : [...config.algorithms];
+  if (algorithms.length === 0) {
+    throw new Error("@dwk/webauthn: at least one algorithm is required");
+  }
+
+  return {
+    rpId: config.rpId,
+    rpName: config.rpName,
+    origins,
+    algorithms,
+    challengeTtlSeconds:
+      config.challengeTtlSeconds ?? DEFAULT_CHALLENGE_TTL_SECONDS,
+    timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    userVerification: config.userVerification ?? "preferred",
+    now: config.now ?? (() => Date.now()),
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}
+
+/** Project the resolved config to the serializable subset forwarded to the DO. */
+export function forwardedConfig(config: ResolvedConfig): ForwardedConfig {
+  return {
+    rpId: config.rpId,
+    rpName: config.rpName,
+    origins: config.origins,
+    algorithms: config.algorithms,
+    challengeTtlSeconds: config.challengeTtlSeconds,
+    timeoutMs: config.timeoutMs,
+    userVerification: config.userVerification,
+  };
+}