suaveplan/openspec/archive/2026-05-11-enterprise-webauthn/proposal.md

# `@suaveplan/webauthn` — WebAuthn Level 3 client + parser + verifier

**Package**: `@suaveplan/webauthn` (NEW)
**Status**: PROPOSED
**Type**: new-package (greenfield migration into genesis)
**Date**: 2026-05-10
**Path**: `packages/vault/webauthn/`

## Why

The Vaulted plugin requires passkey-as-master-key-unlock to land. Today the genesis monorepo has no WebAuthn surface: there is no way to register a passkey at vault-creation time, no way to use a passkey as the second factor (or sole factor) for `Vault.unlock`, and no way to materialise a per-credential symmetric secret (PRF extension output) from an authenticator. Without `@suaveplan/webauthn` the Vaulted unlock FSM cannot be wired and `@suaveplan/vault` ships incomplete against its own enterprise plan.

The package is also a first-class building block for non-Vault consumers. Any genesis app that wants modern phishing-resistant login (FIDO2 passkeys, platform authenticators, security keys, conditional UI / autofill) imports `@suaveplan/webauthn` directly — no Vault dependency — and gets the full registration, authentication, and attestation-verification surface. The browser-tier registration / authentication entry points and the universal-tier parsing / verification subpaths are designed so that server-side relying-party verifiers can import `@suaveplan/webauthn/verifier` without dragging DOM types.

This change has a hard dependency on `@suaveplan/cbor` (concurrent `enterprise-cbor` change). COSE_Key parsing per RFC 9052 §7 and the CTAP 2.1 §6.5 attestation-object envelope are both CBOR-encoded; without the COSE / CTAP CBOR profile the package cannot decode authenticator-data credential public keys or attestation statements. The cbor change must land before the webauthn implementation tasks unblock — captured in `tasks.md` as an explicit blocking gate on task 2.1.

## What changes

### New package: `@suaveplan/webauthn`

Browser-tier package at `packages/vault/webauthn/`. The DOM-bound `register` / `authenticate` entry points sit on the package root; the framework-agnostic parsing and verification surface lives under `./parser` and `./verifier` subpaths so server consumers can import them without a `window` reference.

#### Registration ("create")

- ADDED: `register(opts: WebAuthnRegisterOptions): Promise<RegisterResult>` — builds a `PublicKeyCredentialCreationOptions` per W3C WebAuthn L3 §5.1.3, calls `navigator.credentials.create({ publicKey })` through the injectable `WebAuthnAdapter`, and parses the returned `AuthenticatorAttestationResponse` into a typed `RegisterResult` (`{ credentialId, publicKey: CoseKey, attestationObject, clientDataJSON, transports[], authenticatorData: ParsedAuthData, attestationStatement: ParsedAttestationStmt, extensions }`).
- ADDED: `WebAuthnRegisterOptions` — strict Zod-validated input shape covering `rp`, `user`, `challenge`, `pubKeyCredParams`, `timeout`, `excludeCredentials`, `authenticatorSelection`, `attestation`, `extensions`, `signal: AbortSignal`, `expectedOrigin`, `expectedRpIdHash`.
- ADDED: client-data validator — `type === "webauthn.create"`, `origin === expectedOrigin`, and `challenge` constant-time-equals the caller-supplied challenge. All comparisons use `constantTimeEqual` from `@suaveplan/crypto-utils`. Mismatches throw `WEBAUTHN.CHALLENGE_MISMATCH` / `WEBAUTHN.ORIGIN_MISMATCH`.
- ADDED: `parseAuthenticatorData(bytes: Uint8Array): ParsedAuthData` (under `./parser`) — splits the 37-byte fixed prefix (`rpIdHash[32]` + `flags[1]` + `signCount[4]`) from optional `aaguid[16]` + `credentialIdLength[2]` + `credentialId[L]` + `credentialPublicKey: COSE_Key (CBOR)` + optional `extensions: CBOR` per W3C L3 §6.1.
- ADDED: flag-byte decoder — yields `{ userPresent, userVerified, backupEligible, backupState, attestedCredentialData, extensionsPresent }` per W3C L3 §6.1 (UP / UV / BE / BS / AT / ED bits).

#### Authentication ("get")

- ADDED: `authenticate(opts: WebAuthnAuthenticateOptions): Promise<AuthenticateResult>` — builds a `PublicKeyCredentialRequestOptions` per W3C L3 §5.1.4, calls `navigator.credentials.get`, and parses the returned `AuthenticatorAssertionResponse` into a typed `AuthenticateResult` (`{ credentialId, signature, authenticatorData: ParsedAuthData, clientDataJSON, userHandle? }`).
- ADDED: `WebAuthnAuthenticateOptions` — Zod-validated input shape covering `challenge`, `rpId`, `allowCredentials`, `timeout`, `userVerification`, `mediation: "silent" | "optional" | "conditional" | "required"`, `extensions`, `signal: AbortSignal`, `expectedOrigin`, `expectedRpIdHash`.
- ADDED: assertion client-data validator — same structural rules as registration, type pinned to `"webauthn.get"`.
- ADDED: `verifyAssertion(result, storedPublicKey, expectedChallenge, expectedOrigin, expectedRpIdHash, signCounter): VerifyResult` — verifies the signature over `authData || sha256(clientDataJSON)` using `@suaveplan/crypto-curve` per the COSE_Key `alg` label (ES256 / ES384 / ES512 / EdDSA / RS256), and surfaces a discriminated-union result so callers can branch on `ok: true | false` plus `code` on failure.
- ADDED: sign-counter regression detection per W3C L3 §6.1.1 — if `result.authenticatorData.signCount` ≤ stored counter (and either side is non-zero), `verifyAssertion` returns `{ ok: false, code: "WEBAUTHN.SIGN_COUNTER_REGRESSION" }`. The caller decides whether to revoke the credential.

#### Attestation verification (`./verifier` subpath)

- ADDED: `verifyAttestation(result, expectedRpIdHash, attestationFormatRegistry): AttestationVerifyResult` — dispatches on `fmt` to a per-format verifier; returns `{ trusted: boolean, attestationType: "basic" | "self" | "attCA" | "anonCA" | "none", trustPath: X509[] }` per W3C L3 §6.5.4 / §8.
- ADDED: per-format verifiers under `./attestation/<fmt>` subpaths covering every IANA-registered format expected by the enterprise plan: `packed` (W3C L3 §8.2), `fido-u2f` (§8.6), `tpm` (§8.3), `android-key` (§8.4), `android-safetynet` (§8.5), `apple` (§8.8), `none` (§8.7).
- ADDED: pluggable attestation registry — `registerAttestationFormat(name, verifier)` and `defaultAttestationRegistry()` so genesis apps can register additional IANA-listed formats (e.g. `apple-appattest`) without forking.

#### Conditional UI

- ADDED: `authenticate({ mediation: "conditional", ... })` passthrough — caller is responsible for placing `autocomplete="username webauthn"` on the input.
- ADDED: `isConditionalMediationAvailable(): Promise<boolean>` — wraps `PublicKeyCredential.isConditionalMediationAvailable?.()`, returns `false` when the static method is missing.

#### PRF extension (W3C L3 §10.1.4)

- ADDED: `register({ extensions: { prf: { eval: { first: Uint8Array, second?: Uint8Array } } } })` — surfaces `result.extensions.prf.results.first` (~32 bytes) usable as a vault-key wrap key.
- ADDED: `authenticate({ extensions: { prf: { eval: ... } | { evalByCredential: { ... } } } })` — same on the authentication side. Authenticators that lack PRF report `result.extensions.prf.enabled === false`; consumers MUST check before assuming a secret is present.

#### largeBlob extension (W3C L3 §10.1.3)

- ADDED: `register({ extensions: { largeBlob: { support: "required" | "preferred" } } })` — surfaces `result.extensions.largeBlob.supported` so the caller knows whether the credential can carry blob data.
- ADDED: `authenticate({ extensions: { largeBlob: { read: true } | { write: Uint8Array } } })` — surfaces `result.extensions.largeBlob.blob` (Uint8Array) on read or `result.extensions.largeBlob.written` (boolean) on write.

#### Adapter abstraction

- ADDED: `WebAuthnAdapter` interface — declares `create(options): Promise<PublicKeyCredential>`, `get(options): Promise<PublicKeyCredential>`, `isSupported(): boolean`, `isConditionalMediationAvailable(): Promise<boolean>`. Production wires `globalThis.navigator.credentials`; tests wire a deterministic stub that emits known good / bad responses (no real authenticator on CI).
- ADDED: `defaultWebAuthnAdapter()` — returns the production adapter when `globalThis.navigator?.credentials?.create` exists, throws `WEBAUTHN.NOT_SUPPORTED` otherwise.

#### Errors / observability / boundaries

- ADDED: `WebAuthnError` registry via `defineCodes("WEBAUTHN", [...])` covering `NOT_SUPPORTED`, `USER_CANCELLED`, `INVALID_STATE`, `SECURITY_ERROR`, `NOT_ALLOWED`, `MALFORMED_RESPONSE`, `CHALLENGE_MISMATCH`, `ORIGIN_MISMATCH`, `RPID_HASH_MISMATCH`, `SIGN_COUNTER_REGRESSION`, `SIGNATURE_INVALID`, `ATTESTATION_FORMAT_UNSUPPORTED`, `UV_NOT_PERFORMED`, `UP_NOT_PERFORMED`, `ABORTED`, `TIMEOUT`. Every code is thrown by at least one production path.
- ADDED: DOMException-name mapping at the boundary — `NotAllowedError` → `WEBAUTHN.USER_CANCELLED`, `InvalidStateError` → `WEBAUTHN.INVALID_STATE`, `SecurityError` → `WEBAUTHN.SECURITY_ERROR`, `AbortError` → `WEBAUTHN.ABORTED`, `NotSupportedError` → `WEBAUTHN.NOT_SUPPORTED`. Raw `DOMException` instances never leak to callers.
- ADDED: Zod schemas at every public surface — `WebAuthnRegisterOptionsSchema`, `WebAuthnAuthenticateOptionsSchema`, `RegisterResultSchema`, `AuthenticateResultSchema`, `ParsedAuthDataSchema`, `ParsedAttestationStmtSchema`, `CoseKeySchema`. Mismatches throw `WEBAUTHN.MALFORMED_RESPONSE`.
- ADDED: `AbortSignal` threaded into `register` and `authenticate` and forwarded into `navigator.credentials.{create,get}` so caller-side cancellation fires the native `AbortController` path.
- ADDED: constant-time compare on every challenge and `rpIdHash` comparison via `constantTimeEqual`.
- ADDED: OTel surface — `webauthn.register_duration_ms{outcome}` histogram, `webauthn.authenticate_duration_ms{outcome}` histogram, `webauthn.outcome_total{op,outcome}` counter, `webauthn.attestation_format_total{fmt}` counter, `webauthn.errors_total{code}` counter.

#### Test-vector bundle

- ADDED: `src/__fixtures__/` — captured `AuthenticatorAttestationResponse` and `AuthenticatorAssertionResponse` byte strings sourced offline from a Yubikey 5 (packed + fido-u2f), Windows Hello (tpm), macOS Touch ID (apple), Chrome Software Authenticator (none), Android Pixel platform authenticator (android-key + android-safetynet). Every attestation format covered in the spec has at least one good vector and one corruption (signature flipped, rpIdHash zeroed, signCount frozen) for negative tests.

#### Mitata benchmarks

- ADDED: `src/__benchmarks__/parse_authdata.bench.ts` — packed auth-data parse throughput.
- ADDED: `src/__benchmarks__/verify_assertion_es256.bench.ts` — ES256 assertion verify against a stored COSE_Key.
- ADDED: `src/__benchmarks__/verify_attestation_packed.bench.ts` and `verify_attestation_tpm.bench.ts` — per-format verifier throughput.

#### React hook (consumer-side)

- ADDED: `usePasskeyAutofill({ rpId, challenge })` — exported from a `@suaveplan/react-auth` consumer hook in a follow-up; the underlying `authenticate({ mediation: "conditional" })` surface is in scope of this change so the hook has a stable target.

### Subpath exports

- `.` — root barrel; browser-tier (re-exports `register`, `authenticate`, `isConditionalMediationAvailable`, `defaultWebAuthnAdapter`, every type, every error code).
- `./adapter` — `WebAuthnAdapter` interface + `defaultWebAuthnAdapter`.
- `./parser` — universal-tier; `parseAuthenticatorData`, `parseAttestationObject`, `parseClientDataJSON`, every parser type, every parser-side Zod schema.
- `./verifier` — universal-tier; `verifyAssertion`, `verifyAttestation`, `defaultAttestationRegistry`, `registerAttestationFormat`.
- `./attestation/packed`, `./attestation/fido-u2f`, `./attestation/tpm`, `./attestation/android-key`, `./attestation/android-safetynet`, `./attestation/apple`, `./attestation/none` — per-format verifier subpaths.
- `./extensions/prf`, `./extensions/large-blob` — extension passthrough + result parsing.
- `./errors` — error code registry + `WebAuthnError`.

### Dependencies

- `@suaveplan/cbor workspace:^` — **HARD BLOCKER**, gates this change. COSE_Key (RFC 9052 §7) and CTAP 2.1 §6.5 attestation-object envelope decoding both consume CBOR. Implementation tasks cannot start until `enterprise-cbor` archives.
- `@suaveplan/crypto-curve workspace:^` — ES256 / ES384 / ES512 / EdDSA / RS256 signature verify.
- `@suaveplan/crypto-hash workspace:^` — SHA-256 of `clientDataJSON`, SHA-256 for `rpIdHash` compare.
- `@suaveplan/crypto-utils workspace:^` — base64url encode/decode (challenges, credential IDs), `constantTimeEqual`.
- `@suaveplan/error workspace:^` — `defineCodes`, `SuaveplanError` base.
- `@suaveplan/types workspace:^` — `Clock`, `LoggerLike`, shared option bundles.
- `@opentelemetry/api catalog:observability` — histograms + counters.
- `tslib catalog:build`.
- `zod catalog:forms` — boundary validation.

## Out of scope

- **Server-side relying-party state machine** (challenge generation, credential storage, user-handle binding, attestation-trust-store curation). The package exposes the verification primitives a server needs, but the persistence and challenge-issuance flow belongs to consumers (e.g. `@suaveplan/vault`, `@suaveplan/api-schemas/auth`).
- **MDS3 (FIDO Metadata Service) integration** — `verifyAttestation` returns the `trustPath: X509[]` and `attestationType` so callers can perform MDS3 lookups against their own metadata source. Bundling MDS3 fetch + caching expands scope into a separate package and is a follow-up.
- **WebAuthn Level 2 polyfill** — the package targets WebAuthn L3 only. Browsers without L3 support (e.g. older Safari) surface `WEBAUTHN.NOT_SUPPORTED`.
- **CTAP1 / U2F legacy protocol** — only the CTAP2 mapping is in scope. The `fido-u2f` attestation format is supported because L3 still defines it for backward compatibility; raw U2F register / sign is not.
- **Hardware security key driver code** — the package operates entirely through `navigator.credentials`; it does not speak USB HID, NFC, or BLE directly.
- **`@suaveplan/react-auth` `usePasskeyAutofill` hook implementation** — declared as a target consumer but lives in the `react-auth` change folder; this package only ships the underlying `authenticate({ mediation: "conditional" })` surface.

## Source mapping

This change derives from `../suaveplan/enterprise/webauthn.md`.

| Requirement | Source lines | Notes |
|---|---|---|
| Package purpose, plugin assignment, mixed-tier layout | L1-L15 | Verbatim |
| Current-state assessment + spec anchors | L16-L26 | Verbatim |
| `register` + parse + flag decode | L29-L34 | Verbatim; flag list pinned to W3C L3 §6.1 |
| `authenticate` + assertion parse + `verifyAssertion` + sign-counter regression | L36-L41 | Verbatim; W3C L3 §6.1.1 anchor |
| Attestation `verifyAttestation` + per-format verifiers + pluggable registry + return shape | L43-L47 | Verbatim; W3C L3 §6.5.4 / §8 anchors |
| Conditional UI passthrough + `isConditionalMediationAvailable` | L49-L52 | Verbatim |
| Cross-cutting: tier split, Zod boundaries, error registry, DOMException mapping, OTel, AbortSignal, constant-time compare, 100% coverage, adapter | L54-L64 | Verbatim |
| PRF extension | L68-L69 | W3C L3 §10.1.4 |
| largeBlob extension | L70 | W3C L3 §10.1.3 |
| Test-vector bundle | L71 | Verbatim |
| Mitata benchmarks | L72 | Verbatim |
| Conditional UI React hook target | L67 | Verbatim |
| `WebAuthnAdapter` abstraction | L63 + L79 | Verbatim |
| Error code registry contents | L59 | Verbatim list |
| OTel histogram + counter shapes | L60 | Verbatim |
| Dependency on `@suaveplan/cbor` | L102 | Verbatim |

External standard anchors (every requirement in the spec delta cites at least one):

- W3C WebAuthn L3 §5 "Web Authentication API" (`PublicKeyCredentialCreationOptions`, `PublicKeyCredentialRequestOptions`).
- W3C WebAuthn L3 §6 "WebAuthn Authenticator Model" (auth-data layout, flag bits §6.1, sign-counter regression §6.1.1, attestation §6.5).
- W3C WebAuthn L3 §7 "WebAuthn Relying Party Operations" (register / authenticate algorithms).
- W3C WebAuthn L3 §8 "Defined Attestation Statement Formats" (per-format verifiers).
- W3C WebAuthn L3 §9 "WebAuthn Extensions" (extension processing model).
- W3C WebAuthn L3 §10 "Defined Extensions" (PRF §10.1.4, largeBlob §10.1.3).
- CTAP 2.1 §6.5 "Attestation Object" (attestation envelope CBOR layout, fmt / authData / attStmt fields).
- RFC 9052 §7 "COSE Key Objects" (COSE_Key map, alg label, kty, crv, x/y/n/e fields).
- IANA WebAuthn registries (attestation formats, extension identifiers).

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Subpath split between browser-tier root and universal-tier `./parser` / `./verifier` | Server-side relying-party verifiers must import the verification primitives without a `window` reference; the enterprise doc names this at L56 but the per-subpath listing is genesis-specific. |
| Per-attestation-format subpath (`./attestation/<fmt>`) | Genesis subpath-export convention (`openspec/AGENTS.md` §6); enables tree-shaking of unused formats. |
| `defaultAttestationRegistry()` factory | The enterprise doc specifies pluggable registration; the factory shape is the genesis convention for "ships with all built-ins, accepts overrides". |
| `WEBAUTHN.ABORTED` and `WEBAUTHN.TIMEOUT` distinct codes | Enterprise list groups under `USER_CANCELLED`; genesis convention separates AbortSignal-driven cancellation from authenticator-side timeout for OTel `errors_total{code}` slicing. |

## Verification approach

Each requirement in the spec delta carries a `**Verified by:**` line pointing at concrete test-file paths. Test files:

- `src/register/register.test.ts` — register happy path, client-data type / origin / challenge mismatch, AbortSignal cancellation, DOMException mapping for every native name.
- `src/authenticate/authenticate.test.ts` — authenticate happy path, client-data validation, conditional mediation, AbortSignal.
- `src/parser/authenticator-data.test.ts` — fixed-prefix split, every flag-byte combination, attested-credential-data parse, extensions block presence/absence, malformed-truncation rejection.
- `src/parser/attestation-object.test.ts` — `fmt` / `authData` / `attStmt` extraction, every format produces the expected shape.
- `src/parser/client-data.test.ts` — `webauthn.create` / `webauthn.get` type pinning, base64url challenge decode, origin equality.
- `src/parser/cose-key.test.ts` — RFC 9052 §7 round-trip per supported alg.
- `src/verifier/verify-assertion.test.ts` — ES256 / ES384 / ES512 / EdDSA / RS256 happy path, signature-flip negative, rpIdHash mismatch, sign-counter regression at every boundary (equal, less-than, both-zero acceptance).
- `src/verifier/verify-attestation.test.ts` — registry dispatch, unknown-format error, every built-in format trusted on good vector, every format rejects flipped signature.
- `src/attestation/packed/packed.test.ts`, `src/attestation/fido-u2f/fido-u2f.test.ts`, `src/attestation/tpm/tpm.test.ts`, `src/attestation/android-key/android-key.test.ts`, `src/attestation/android-safetynet/android-safetynet.test.ts`, `src/attestation/apple/apple.test.ts`, `src/attestation/none/none.test.ts` — per-format good + corrupted vectors, attestationType + trustPath shape.
- `src/extensions/prf/prf.test.ts` — PRF eval round-trip on register and authenticate, missing-PRF-result fallback, secret length assertion.
- `src/extensions/large-blob/large-blob.test.ts` — `support: "required"` flag surfaces, `read` returns blob, `write` reports `written: true`.
- `src/adapter/adapter.test.ts` — `defaultWebAuthnAdapter` throws `NOT_SUPPORTED` when `navigator.credentials` missing; conditional-mediation availability check.
- `src/errors/errors.test.ts` — every `WEBAUTHN.*` code is thrown by at least one production path; DOMException-name mapping table covered.
- `src/observability/metrics.test.ts` — every histogram + counter records on its production path against an in-memory `MeterProvider`.
- `src/parser/authenticator-data.property.test.ts` — fast-check fuzz of arbitrary auth-data byte strings; parser never panics, only throws typed errors.
- `src/parser/attestation-object.property.test.ts` — fast-check fuzz of attestation-object envelopes.
- `src/index.test.ts` — every documented subpath resolves through the package's `exports` map.
- `tests/dep-graph.test.ts` — `./parser` and `./verifier` subpaths import zero DOM types (verified with the genesis dep-graph spec-conformance harness).

## Migration impact

Additive only — no existing genesis package depends on a prior WebAuthn surface. Downstream consumers that will adopt this package in follow-up changes:

- `@suaveplan/vault` — passkey-as-master-key-unlock flow (PRF extension materialises the wrap key for the AUK).
- `@suaveplan/react-auth` — `usePasskeyAutofill` hook (conditional-mediation autofill).
- `@suaveplan/api-schemas/auth` — WebAuthn challenge / credential schemas extend the existing auth schemas.

## Impact

### Affected dependents

This is a NEW package — no existing dependents. Run `bunx turbo ls --filter=...@suaveplan/webauthn` after landing to confirm. Downstream adopters listed under "Migration impact" land in their own subsequent changes.

### Dependency on concurrent change

This change is **blocked on `enterprise-cbor` archiving first**. Implementation task 2.1 (CBOR-decode COSE_Key + attestation-object) cannot start until `@suaveplan/cbor` is published from genesis. Spec authoring (proposal + tasks + spec delta) and test-vector bundle prep are unblocked and may proceed in parallel.

## Migration

No prior surface — additive only. There is no obsolete contract for consumers to migrate from.