first commit

docs/identity/auth/webauthn/src/errors/error-codes.md

@@ -0,0 +1,51 @@
+# WebAuthn error codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Defines the frozen registry of every typed error code raised across the `@suaveplan/webauthn` surface. The codes mirror the W3C WebAuthn Level 3 failure classes (§5, §6, §7, §8, §10) and the CTAP 2.1 attestation-object failure points so consumers can `switch (err.code)` against a stable enum instead of pattern-matching on free-form messages. The registry is the single source of truth for the observability counter `webauthn.errors_total{code}` and for the DOMException mapper at the adapter boundary.
+
+## Features
+
+- Frozen `WEBAUTHN_CODES` registry built via `defineCodes("WEBAUTHN", [...])`.
+- Concrete `WebAuthnError` subclass of `SuaveplanError<WebAuthnErrorCode>`.
+- Literal union `WebAuthnErrorCode` pinned with `expectTypeOf` assertions in tests so any drift between the registry and the union fails typecheck.
+- Every code raised by at least one production path; codes that exist only to placate the conformance harness are forbidden (`AGENTS.md` §2c).
+
+## Usage: Basic Example
+
+```ts
+import { WEBAUTHN_CODES, WebAuthnError } from "@suaveplan/webauthn/errors";
+
+throw new WebAuthnError(
+    WEBAUTHN_CODES.CHALLENGE_MISMATCH,
+    "error.webauthn.challenge-mismatch",
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { WebAuthnError, type WebAuthnErrorCode } from "@suaveplan/webauthn/errors";
+
+function classify(err: unknown): WebAuthnErrorCode | "unknown" {
+    if (err instanceof WebAuthnError) {
+        return err.code;
+    }
+    return "unknown";
+}
+```
+
+## API Reference
+
+- `WEBAUTHN_CODES` — frozen object mapping every code identifier (`NOT_SUPPORTED`, `USER_CANCELLED`, ...) to its dotted string (`"WEBAUTHN.NOT_SUPPORTED"`).
+- `WebAuthnErrorCode` — literal union of every value in `WEBAUTHN_CODES`.
+- `WebAuthnError` — extends `SuaveplanError<WebAuthnErrorCode>`; accepts `(code, messageKey, options?)`.
+
+## Implementation Notes
+
+- Codes are intentionally `SCREAMING_SNAKE` so they survive minification.
+- The order in the `defineCodes` array is alphabetised within W3C section groupings: lifecycle (`NOT_SUPPORTED`, `USER_CANCELLED`, ...), validation (`MALFORMED_RESPONSE`, `CHALLENGE_MISMATCH`, ...), signature (`SIGNATURE_INVALID`, ...), counter (`SIGN_COUNTER_REGRESSION`), attestation (`ATTESTATION_FORMAT_UNSUPPORTED`), flag (`UV_NOT_PERFORMED`, `UP_NOT_PERFORMED`), cancellation (`ABORTED`, `TIMEOUT`), options validation (`INVALID_OPTIONS`).
+- `WEBAUTHN.ABORTED` and `WEBAUTHN.TIMEOUT` are kept distinct from `USER_CANCELLED` so the OTel `errors_total{code}` counter slices AbortSignal cancellation, authenticator-side timeout, and explicit user denial separately.