@dwk/webauthn 0.1.0-beta.0

package/src/cose.ts

@@ -0,0 +1,238 @@
+/**
+ * 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.
+ */
+
+import { bytesToBase64url } from "./encoding";
+
+/** COSE_Key map labels (RFC 9052 §7, RFC 9053). */
+const COSE_KTY = 1;
+const COSE_ALG = 3;
+const COSE_EC_CRV = -1;
+const COSE_EC_X = -2;
+const COSE_EC_Y = -3;
+const COSE_RSA_N = -1;
+const COSE_RSA_E = -2;
+
+/** COSE key types we accept. */
+const KTY_EC2 = 2;
+const KTY_RSA = 3;
+
+/** COSE elliptic curves (RFC 9053 §7.1). */
+const CRV_P256 = 1;
+const CRV_P384 = 2;
+const CRV_P521 = 3;
+
+/** COSE algorithm identifiers (the asymmetric subset we accept). */
+export const COSE_ALG_ES256 = -7;
+export const COSE_ALG_ES384 = -35;
+export const COSE_ALG_ES512 = -36;
+export const COSE_ALG_RS256 = -257;
+export const COSE_ALG_PS256 = -37;
+
+/** Default `pubKeyCredParams`, most-preferred first: ES256 then RS256. */
+export const DEFAULT_COSE_ALGORITHMS: readonly number[] = [
+  COSE_ALG_ES256,
+  COSE_ALG_RS256,
+];
+
+/** 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 class CoseError extends Error {}
+
+function intValue(map: Map<unknown, unknown>, label: number): number | null {
+  const v = map.get(label);
+  return typeof v === "number" ? v : null;
+}
+
+function bytesValue(
+  map: Map<unknown, unknown>,
+  label: number,
+): Uint8Array | null {
+  const v = map.get(label);
+  return v instanceof Uint8Array ? v : null;
+}
+
+function ecCurveName(crv: number): string | null {
+  switch (crv) {
+    case CRV_P256:
+      return "P-256";
+    case CRV_P384:
+      return "P-384";
+    case CRV_P521:
+      return "P-521";
+    default:
+      return null;
+  }
+}
+
+/** Convert a decoded COSE_Key map to a JWK plus its declared algorithm. */
+export function coseToKey(map: Map<unknown, unknown>): CoseKey {
+  const kty = intValue(map, COSE_KTY);
+  const alg = intValue(map, COSE_ALG);
+  if (kty === null || alg === null) {
+    throw new CoseError("COSE_Key missing kty/alg");
+  }
+
+  if (kty === KTY_EC2) {
+    const crv = intValue(map, COSE_EC_CRV);
+    const x = bytesValue(map, COSE_EC_X);
+    const y = bytesValue(map, COSE_EC_Y);
+    if (crv === null || x === null || y === null) {
+      throw new CoseError("COSE EC2 key missing crv/x/y");
+    }
+    const curve = ecCurveName(crv);
+    if (curve === null) throw new CoseError(`unsupported COSE curve ${crv}`);
+    return {
+      jwk: {
+        kty: "EC",
+        crv: curve,
+        x: bytesToBase64url(x),
+        y: bytesToBase64url(y),
+      },
+      alg,
+    };
+  }
+
+  if (kty === KTY_RSA) {
+    const n = bytesValue(map, COSE_RSA_N);
+    const e = bytesValue(map, COSE_RSA_E);
+    if (n === null || e === null) {
+      throw new CoseError("COSE RSA key missing n/e");
+    }
+    return {
+      jwk: { kty: "RSA", n: bytesToBase64url(n), e: bytesToBase64url(e) },
+      alg,
+    };
+  }
+
+  throw new CoseError(`unsupported COSE kty ${kty}`);
+}
+
+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 function cryptoParamsForCoseAlg(alg: number): CryptoParams | null {
+  switch (alg) {
+    case COSE_ALG_ES256:
+      return {
+        importParams: { name: "ECDSA", namedCurve: "P-256" },
+        verifyParams: { name: "ECDSA", hash: "SHA-256" },
+        ec: true,
+        ecSignatureBytes: 64,
+      };
+    case COSE_ALG_ES384:
+      return {
+        importParams: { name: "ECDSA", namedCurve: "P-384" },
+        verifyParams: { name: "ECDSA", hash: "SHA-384" },
+        ec: true,
+        ecSignatureBytes: 96,
+      };
+    case COSE_ALG_RS256:
+      return {
+        importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+        verifyParams: { name: "RSASSA-PKCS1-v1_5" },
+        ec: false,
+        ecSignatureBytes: 0,
+      };
+    case COSE_ALG_PS256:
+      return {
+        importParams: { name: "RSA-PSS", hash: "SHA-256" },
+        verifyParams: { name: "RSA-PSS", saltLength: 32 },
+        ec: false,
+        ecSignatureBytes: 0,
+      };
+    default:
+      return 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 function derToRawEcdsaSignature(
+  der: Uint8Array,
+  size: number,
+): Uint8Array {
+  let offset = 0;
+  const next = (): number => {
+    if (offset >= der.length) throw new CoseError("malformed DER signature");
+    return der[offset++]!;
+  };
+
+  if (next() !== 0x30) throw new CoseError("DER signature not a SEQUENCE");
+  // SEQUENCE length (short form is sufficient for ECDSA signatures).
+  next();
+
+  const readInteger = (): Uint8Array => {
+    if (next() !== 0x02) throw new CoseError("DER signature missing INTEGER");
+    const len = next();
+    const end = offset + len;
+    if (end > der.length) throw new CoseError("malformed DER signature");
+    let value = der.subarray(offset, end);
+    offset = end;
+    // Drop a leading sign byte and any over-long left padding.
+    while (value.length > 1 && value[0] === 0x00) value = value.subarray(1);
+    return value;
+  };
+
+  const r = readInteger();
+  const s = readInteger();
+  const half = size / 2;
+  if (r.length > half || s.length > half) {
+    throw new CoseError("DER signature integer too large");
+  }
+
+  const raw = new Uint8Array(size);
+  raw.set(r, half - r.length);
+  raw.set(s, size - s.length);
+  return raw;
+}

package/src/encoding.ts

@@ -0,0 +1,68 @@
+/**
+ * Byte / base64url encoding helpers shared across the WebAuthn ceremonies.
+ *
+ * WebAuthn transports binary fields (challenges, credential ids, signatures,
+ * attestation objects) as base64url over JSON, so every ceremony boundary needs
+ * the same encode/decode pair. These are pure and runtime-agnostic — Web APIs
+ * (`atob`/`btoa`/`TextEncoder`) only.
+ */
+
+/** Decode a base64url (or padded base64) string to raw bytes. */
+export function base64urlToBytes(input: string): Uint8Array {
+  const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded =
+    b64.length % 4 === 0 ? b64 : b64 + "=".repeat(4 - (b64.length % 4));
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/** Encode raw bytes as an unpadded base64url string. */
+export function bytesToBase64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/**
+ * Strip any base64 padding and normalize base64 to base64url so two encodings
+ * of the same bytes compare equal. WebAuthn clients emit the challenge in
+ * `clientDataJSON` as unpadded base64url; this lets a comparison tolerate a
+ * padded or `+`/`/`-alphabet copy without a full decode/re-encode round trip.
+ */
+export function normalizeBase64url(input: string): string {
+  return input.replace(/-/g, "+").replace(/_/g, "/").replace(/=+$/, "");
+}
+
+/** Whether two byte arrays are equal (length + contents). Not constant-time. */
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/** SHA-256 digest of the input bytes as a fresh `Uint8Array`. */
+export async function sha256(input: Uint8Array): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest("SHA-256", input as BufferSource);
+  return new Uint8Array(digest);
+}
+
+/** UTF-8 encode a string to bytes. */
+export function utf8ToBytes(input: string): Uint8Array {
+  return new TextEncoder().encode(input);
+}
+
+/** UTF-8 decode bytes to a string. */
+export function bytesToUtf8(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}

package/src/handler.ts

@@ -0,0 +1,135 @@
+/**
+ * The stateless WebAuthn relying-party front door.
+ *
+ * It routes the four ceremony steps — `/register/options`, `/register/verify`,
+ * `/authenticate/options`, `/authenticate/verify` — to the per-relying-party
+ * Durable Object, which owns all challenge and credential state. The handler is
+ * mountable under any path prefix because it identifies the step by the *tail*
+ * of the request path, and it injects the trusted clock and forwarded config the
+ * DO needs (the DO cannot hold the injected logger/metrics/clock itself). It
+ * emits each ceremony outcome on the wired logger and metrics seams.
+ */
+
+import { type LogFields } from "@dwk/log";
+
+import {
+  INTERNAL_HEADERS,
+  forwardedConfig,
+  resolveConfig,
+  type ResolvedConfig,
+  type WebAuthnConfig,
+  type WebAuthnEnv,
+  type WebAuthnOperation,
+} from "./config";
+
+/** A `fetch`-compatible Worker handler. */
+export type WebAuthnHandler = (
+  request: Request,
+  env: WebAuthnEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+
+/** Map a request path tail to a ceremony operation, or `null` if unmatched. */
+function operationForPath(pathname: string): WebAuthnOperation | null {
+  if (pathname.endsWith("/register/options")) return "register/options";
+  if (pathname.endsWith("/register/verify")) return "register/verify";
+  if (pathname.endsWith("/authenticate/options")) return "authenticate/options";
+  if (pathname.endsWith("/authenticate/verify")) return "authenticate/verify";
+  return null;
+}
+
+/** Fail loudly if a required Cloudflare binding is missing (no silent degradation). */
+function assertBindings(env: WebAuthnEnv): void {
+  if (!env.WEBAUTHN) {
+    throw new Error(
+      "@dwk/webauthn: missing required Durable Object binding `WEBAUTHN`",
+    );
+  }
+}
+
+/** Emit a structured event on both the logger and the metrics seam. */
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+/**
+ * Translate the Durable Object's outcome headers into a structured event on the
+ * injected seams, then strip those internal headers before the response reaches
+ * the client. A rejection (any non-2xx) logs at `warn` with its stable reason;
+ * a success logs at `info`.
+ */
+function logOutcome(config: ResolvedConfig, response: Response): Response {
+  const event = response.headers.get(INTERNAL_HEADERS.event);
+  if (event) {
+    const reason = response.headers.get(INTERNAL_HEADERS.reason);
+    if (response.ok) {
+      emit(config, "info", event);
+    } else {
+      emit(config, "warn", event, reason ? { reason } : undefined);
+    }
+  }
+
+  const headers = new Headers(response.headers);
+  headers.delete(INTERNAL_HEADERS.event);
+  headers.delete(INTERNAL_HEADERS.reason);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+/** Build the internal DO request: forwarded config, trusted clock, op, body. */
+function internalRequest(
+  request: Request,
+  config: ResolvedConfig,
+  op: WebAuthnOperation,
+): Request {
+  const headers = new Headers({
+    "content-type": "application/json",
+    [INTERNAL_HEADERS.op]: op,
+    [INTERNAL_HEADERS.config]: JSON.stringify(forwardedConfig(config)),
+    [INTERNAL_HEADERS.now]: String(config.now()),
+  });
+  return new Request(request.url, {
+    method: "POST",
+    headers,
+    body: request.body,
+  });
+}
+
+/**
+ * Create the stateless WebAuthn relying-party handler. All four ceremony steps
+ * are `POST`; anything else is `405`. Unmatched paths are `404`.
+ */
+export function createWebAuthn(config: WebAuthnConfig): WebAuthnHandler {
+  const resolved = resolveConfig(config);
+
+  return async (request, env, _ctx) => {
+    assertBindings(env);
+
+    const op = operationForPath(new URL(request.url).pathname);
+    if (op === null) {
+      return new Response("Not Found", { status: 404 });
+    }
+    if (request.method.toUpperCase() !== "POST") {
+      return new Response("Method Not Allowed", {
+        status: 405,
+        headers: { allow: "POST" },
+      });
+    }
+
+    // One Durable Object per relying party, keyed by the rpId (no sharding).
+    const id = env.WEBAUTHN.idFromName(resolved.rpId);
+    const response = await env.WEBAUTHN.get(id).fetch(
+      internalRequest(request, resolved, op),
+    );
+    return logOutcome(resolved, response);
+  };
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * `@dwk/webauthn` — a WebAuthn / passkeys relying party.
+ *
+ * A stateless Worker front door over a per-relying-party Durable Object that is
+ * the consistency authority for short-TTL challenge state and credential
+ * records. It runs the four ceremony steps — registration (attestation) and
+ * authentication (assertion) options + verification — entirely on Web Crypto,
+ * with no external dependency beyond `@dwk/log`.
+ *
+ * The package is **not** protocol-agnostic: it is the WebAuthn endpoint. It is
+ * filed for completeness as an **exploratory, lowest-priority** package — a clean
+ * Workers fit, but a step toward generic authentication rather than the
+ * web-presence standards this cohort centers on.
+ *
+ * Attestation is verified for the `none` and `packed` self-attestation formats
+ * (the relying party requests `attestation: "none"`); full attestation-chain
+ * verification is intentionally out of scope.
+ *
+ * @see spec/packages/webauthn.md
+ * @packageDocumentation
+ */
+
+export { createWebAuthn, type WebAuthnHandler } from "./handler";
+export { WebAuthnObject } from "./rp";
+
+export {
+  type WebAuthnConfig,
+  type WebAuthnEnv,
+  type UserVerificationRequirement,
+} from "./config";
+
+export {
+  DEFAULT_COSE_ALGORITHMS,
+  COSE_ALG_ES256,
+  COSE_ALG_ES384,
+  COSE_ALG_RS256,
+  COSE_ALG_PS256,
+} from "./cose";
+
+export {
+  verifyRegistration,
+  verifyAuthentication,
+  parseClientData,
+  parseAuthenticatorData,
+  type RegistrationVerifyInput,
+  type RegistrationVerifyResult,
+  type AuthenticationVerifyInput,
+  type AuthenticationVerifyResult,
+  type VerifiedCredential,
+  type VerifyFailureReason,
+} from "./verify";
+
+export { WebAuthnLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";

package/src/log.ts

@@ -0,0 +1,25 @@
+/**
+ * The structured-logging vocabulary for `@dwk/webauthn`.
+ *
+ * The Durable Object cannot hold the injected logger/metrics (they do not cross
+ * the isolate boundary), so it names its ceremony outcome in a response header
+ * ({@link INTERNAL_HEADERS.event}) and the front door emits it on the wired
+ * seams. Event names are stable and dotted; callers attach only reason codes and
+ * non-sensitive facts — never challenges, signatures, or public keys.
+ */
+
+/** Stable, dotted event names emitted on the logger and metrics seams. */
+export enum WebAuthnLogEvent {
+  /** Registration options issued (a fresh challenge was minted). */
+  RegisterOptions = "webauthn.register.options",
+  /** A registration ceremony verified and a credential was stored. */
+  RegisterVerified = "webauthn.register.verified",
+  /** A registration ceremony was rejected. */
+  RegisterRejected = "webauthn.register.rejected",
+  /** Authentication options issued. */
+  AuthenticateOptions = "webauthn.authenticate.options",
+  /** An authentication ceremony verified. */
+  AuthenticateVerified = "webauthn.authenticate.verified",
+  /** An authentication ceremony was rejected. */
+  AuthenticateRejected = "webauthn.authenticate.rejected",
+}