@dwk/webauthn 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# `@dwk/webauthn`
+
+> WebAuthn / passkeys relying party: registration + authentication ceremonies
+> over a per-relying-party Durable Object for challenge state and credential
+> records.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/webauthn.md) for the full
+requirements.
+
+> **Status: exploratory, lowest priority.** This package is filed for
+> completeness. A WebAuthn relying party is a clean technical fit for Workers —
+> ceremonies plus a credential store, with challenge state mapping neatly onto a
+> short-TTL Durable Object — but it is a step *away* from the "implement open
+> *web-presence* standards" thesis and *toward* generic authentication. Prefer
+> [`@dwk/indieauth`](../indieauth) as a site's primary identity mechanism; reach
+> for this only if you specifically need passkeys. Tracked in
+> [#64](https://github.com/davidwkeith/workers/issues/64).
+
+## What it provides
+
+A single factory, `createWebAuthn(config)`, returning a `fetch`-style handler
+that exposes the four ceremony endpoints (mountable under any path prefix):
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /register/options` | Issue `PublicKeyCredentialCreationOptions` + a fresh challenge |
+| `POST /register/verify` | Verify the attestation and store the credential |
+| `POST /authenticate/options` | Issue `PublicKeyCredentialRequestOptions` + a fresh challenge |
+| `POST /authenticate/verify` | Verify the assertion and advance the signature counter |
+
+It also exports the `WebAuthnObject` Durable Object class (bind it as a
+namespace), and the pure verification primitives (`verifyRegistration`,
+`verifyAuthentication`, `parseClientData`, `parseAuthenticatorData`) for callers
+who want to drive the ceremonies themselves.
+
+## Architecture
+
+A stateless front door routes each ceremony step to a per-relying-party Durable
+Object keyed by `rpId`. The Durable Object is the consistency authority: it mints
+and **single-use-consumes** short-TTL challenges and reads/writes credential
+records (public key, signature counter, transports) in its SQLite, all strongly
+consistent. **Challenge and credential state never live in KV** — a stale
+challenge or counter is a security bug (see
+[non-functional requirements](../../spec/non-functional-requirements.md)).
+
+Verification runs entirely on **Web Crypto**: a minimal CBOR decoder reads the
+attestation object and COSE public key, which is imported as a JWK and used to
+verify attestation/assertion signatures (ECDSA signatures are unwrapped from
+ASN.1 DER to the raw form Web Crypto expects). The only runtime dependency is
+[`@dwk/log`](../log).
+
+### 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 statement carrying `x5c` is rejected
+rather than silently trusted.
+
+## Usage
+
+```ts
+import { createWebAuthn, WebAuthnObject } from "@dwk/webauthn";
+
+// Bind a Durable Object namespace `WEBAUTHN` to the WebAuthnObject class.
+export { WebAuthnObject };
+
+const webauthn = createWebAuthn({
+  rpId: "example.com",
+  rpName: "Example",
+  origin: "https://example.com", // or an array of accepted origins
+  // optional:
+  // algorithms: [-7, -257],     // COSE alg ids (ES256, RS256) — the default
+  // challengeTtlSeconds: 300,
+  // userVerification: "preferred",
+});
+
+export default {
+  fetch(request, env, ctx) {
+    return webauthn(request, env, ctx); // mount under any prefix you like
+  },
+};
+```
+
+The browser glue is standard: pass the `/register/options` (or
+`/authenticate/options`) JSON to `navigator.credentials.create()` /
+`.get()` after base64url-decoding the binary fields, then base64url-encode the
+credential response and POST it to the matching `verify` endpoint.
+
+## Configuration
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `rpId` | — (required) | Relying party id (effective domain). |
+| `rpName` | — (required) | Human-readable name for the authenticator UI. |
+| `origin` | — (required) | Accepted client origin(s); matched exactly. |
+| `algorithms` | `[-7, -257]` | Accepted COSE algorithms, most-preferred first. |
+| `challengeTtlSeconds` | `300` | Challenge lifetime. |
+| `timeoutMs` | `60000` | Ceremony timeout advertised to the client. |
+| `userVerification` | `"preferred"` | `"required"` also rejects assertions whose UV flag is unset. |
+| `logger` / `metrics` | no-op | Injectable `@dwk/log` seams for ceremony outcomes. |
+
+Per the [composition contract](../../spec/composition-contract.md), the package
+never reads the global environment: all config is passed into the factory, and a
+missing `WEBAUTHN` Durable Object binding fails loudly at startup.
+
+## License
+
+ISC

package/dist/cbor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare 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 declare function decodeFirst(bytes: Uint8Array, start?: number): CborDecoded;
+//# sourceMappingURL=cbor.d.ts.map

package/dist/cbor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbor.d.ts","sourceRoot":"","sources":["../src/cbor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,MAAM,GACN,UAAU,GACV,SAAS,EAAE,GACX,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAE9B,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,gFAAgF;AAChF,qBAAa,SAAU,SAAQ,KAAK;CAAG;AAEvC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,SAAI,GAAG,WAAW,CAIrE"}

package/dist/cbor.js

@@ -0,0 +1,144 @@
+/**
+ * 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).
+ */
+/** 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, start = 0) {
+    const reader = new Reader(bytes, start);
+    const value = reader.readItem();
+    return { value, length: reader.offset - start };
+}
+class Reader {
+    offset;
+    #bytes;
+    #view;
+    constructor(bytes, start) {
+        this.#bytes = bytes;
+        this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        this.offset = start;
+    }
+    readItem() {
+        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 = [];
+                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();
+                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) {
+        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) {
+        const value = this.#argument(info);
+        if (typeof value === "bigint" || value > this.#bytes.length) {
+            throw new CborError("CBOR length out of range");
+        }
+        return value;
+    }
+    #byte() {
+        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) {
+        if (this.offset + n > this.#bytes.length) {
+            throw new CborError("unexpected end of CBOR input");
+        }
+    }
+    #bytesOfLength(length) {
+        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;
+    }
+}
+//# sourceMappingURL=cbor.js.map

package/dist/cbor.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { type Logger, type Metrics } from "@dwk/log";
+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 declare const INTERNAL_HEADERS: {
+    /** Which ceremony step to run (see {@link WebAuthnOperation}). */
+    readonly op: "x-webauthn-op";
+    /** JSON-encoded {@link ForwardedConfig}. */
+    readonly config: "x-webauthn-config";
+    /** Current time (epoch ms) from the injected clock, for TTL decisions. */
+    readonly now: "x-webauthn-now";
+    /** DO→front-door: the ceremony outcome event name, logged then stripped. */
+    readonly event: "x-webauthn-event";
+    /** DO→front-door: a stable failure reason when the ceremony was rejected. */
+    readonly reason: "x-webauthn-reason";
+};
+/** The four ceremony steps the handler routes. */
+export type WebAuthnOperation = "register/options" | "register/verify" | "authenticate/options" | "authenticate/verify";
+/** Apply defaults and derive values from raw {@link WebAuthnConfig}. */
+export declare function resolveConfig(config: WebAuthnConfig): ResolvedConfig;
+/** Project the resolved config to the serializable subset forwarded to the DO. */
+export declare function forwardedConfig(config: ResolvedConfig): ForwardedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA2B,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAG9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE3C,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,CAAC;CAC3D;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAE5C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;IAExD,mFAAmF;IACnF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAE5B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,qDAAqD;AACrD,MAAM,MAAM,2BAA2B,GACnC,UAAU,GACV,WAAW,GACX,aAAa,CAAC;AAElB,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,2BAA2B,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,2BAA2B,CAAC;CACxD;AAED,gFAAgF;AAChF,eAAO,MAAM,gBAAgB;IAC3B,kEAAkE;;IAElE,4CAA4C;;IAE5C,0EAA0E;;IAE1E,4EAA4E;;IAE5E,6EAA6E;;CAErE,CAAC;AAEX,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,iBAAiB,GACjB,sBAAsB,GACtB,qBAAqB,CAAC;AAK1B,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA+BpE;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAUvE"}

package/dist/config.js

@@ -0,0 +1,70 @@
+/**
+ * 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 } from "@dwk/log";
+import { DEFAULT_COSE_ALGORITHMS } from "./cose";
+/** 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",
+};
+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) {
+    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) {
+    return {
+        rpId: config.rpId,
+        rpName: config.rpName,
+        origins: config.origins,
+        algorithms: config.algorithms,
+        challengeTtlSeconds: config.challengeTtlSeconds,
+        timeoutMs: config.timeoutMs,
+        userVerification: config.userVerification,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAA6B,MAAM,UAAU,CAAC;AAE9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AA+FjD,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,kEAAkE;IAClE,EAAE,EAAE,eAAe;IACnB,4CAA4C;IAC5C,MAAM,EAAE,mBAAmB;IAC3B,0EAA0E;IAC1E,GAAG,EAAE,gBAAgB;IACrB,4EAA4E;IAC5E,KAAK,EAAE,kBAAkB;IACzB,6EAA6E;IAC7E,MAAM,EAAE,mBAAmB;CACnB,CAAC;AASX,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAC1C,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,MAAsB;IAClD,IAAI,CAAC,MAAM,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAE3E,MAAM,OAAO,GACX,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,UAAU,GACd,MAAM,CAAC,UAAU,KAAK,SAAS;QAC7B,CAAC,CAAC,CAAC,GAAG,uBAAuB,CAAC;QAC9B,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO;QACP,UAAU;QACV,mBAAmB,EACjB,MAAM,CAAC,mBAAmB,IAAI,6BAA6B;QAC7D,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,kBAAkB;QACjD,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,WAAW;QACxD,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,UAAU;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,WAAW;KACvC,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,MAAsB;IACpD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;KAC1C,CAAC;AACJ,CAAC"}

package/dist/cose.d.ts

@@ -0,0 +1,73 @@
+/**
+ * COSE_Key (RFC 9052) → JWK conversion and the Web Crypto parameters for the
+ * COSE signature algorithms a WebAuthn relying party accepts.
+ *
+ * Authenticators hand the relying party a credential public key as a COSE_Key
+ * (an integer-keyed CBOR map) and sign assertions with a COSE algorithm
+ * identifier. This module narrows that to the algorithms we support — the same
+ * asymmetric set as `@dwk/dpop` (ES256/ES384, RS256/PS256) — and produces a JWK
+ * plus the `importKey`/`verify` parameter objects, so verification stays on Web
+ * Crypto with no external dependency.
+ *
+ * Web Crypto's ECDSA `verify` expects a raw `r‖s` signature, but WebAuthn EC
+ * assertions are ASN.1 DER `SEQUENCE { r, s }`; {@link derToRawEcdsaSignature}
+ * bridges that gap.
+ */
+/** COSE algorithm identifiers (the asymmetric subset we accept). */
+export declare const COSE_ALG_ES256 = -7;
+export declare const COSE_ALG_ES384 = -35;
+export declare const COSE_ALG_ES512 = -36;
+export declare const COSE_ALG_RS256 = -257;
+export declare const COSE_ALG_PS256 = -37;
+/** Default `pubKeyCredParams`, most-preferred first: ES256 then RS256. */
+export declare const DEFAULT_COSE_ALGORITHMS: readonly number[];
+/** A credential public key extracted from a COSE_Key. */
+export interface CoseKey {
+    /** The public key as a JWK ready for `crypto.subtle.importKey`. */
+    readonly jwk: JsonWebKey;
+    /** The COSE signature algorithm identifier the key declared. */
+    readonly alg: number;
+}
+/** Thrown when a COSE_Key is malformed or uses an unsupported algorithm. */
+export declare class CoseError extends Error {
+}
+/** Convert a decoded COSE_Key map to a JWK plus its declared algorithm. */
+export declare function coseToKey(map: Map<unknown, unknown>): CoseKey;
+interface ImportAlg {
+    name: string;
+    namedCurve?: string;
+    hash?: string;
+}
+interface VerifyAlg {
+    name: string;
+    hash?: string;
+    saltLength?: number;
+}
+/** Web Crypto parameters for one COSE algorithm. */
+export interface CryptoParams {
+    readonly importParams: ImportAlg;
+    readonly verifyParams: VerifyAlg;
+    /** EC algorithms carry a DER-encoded signature that needs unwrapping. */
+    readonly ec: boolean;
+    /** Raw `r‖s` length (one coordinate × 2) for EC; unused for RSA. */
+    readonly ecSignatureBytes: number;
+}
+/**
+ * Resolve the `importKey`/`verify` parameters for a COSE algorithm, or `null`
+ * when it is outside the accepted set. The set mirrors `@dwk/dpop`: ES256/ES384
+ * (ECDSA), RS256 (RSASSA-PKCS1-v1_5), PS256 (RSA-PSS).
+ */
+export declare function cryptoParamsForCoseAlg(alg: number): CryptoParams | null;
+/**
+ * Convert an ASN.1 DER `SEQUENCE { INTEGER r, INTEGER s }` ECDSA signature to
+ * the fixed-length raw `r‖s` form Web Crypto's ECDSA `verify` expects. DER
+ * integers are big-endian, minimally encoded, and may carry a leading `0x00`
+ * sign byte; each is left-padded (or its sign byte trimmed) to `size/2` bytes.
+ *
+ * @param der - the DER-encoded signature
+ * @param size - the raw signature length (64 for P-256, 96 for P-384)
+ * @throws CoseError if the DER structure is malformed
+ */
+export declare function derToRawEcdsaSignature(der: Uint8Array, size: number): Uint8Array;
+export {};
+//# sourceMappingURL=cose.d.ts.map

package/dist/cose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cose.d.ts","sourceRoot":"","sources":["../src/cose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAsBH,oEAAoE;AACpE,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAGpD,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,4EAA4E;AAC5E,qBAAa,SAAU,SAAQ,KAAK;CAAG;AA4BvC,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,OAAO,CAwC7D;AAED,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AACD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAiCvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,MAAM,GACX,UAAU,CAkCZ"}