first commit

docs/identity/auth/webauthn/src/attestation/packed/packed.md

@@ -0,0 +1,63 @@
+# `packed` attestation verifier
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Implements the W3C WebAuthn L3 §8.2 `packed` attestation format, the most common format on modern authenticators (Yubikey 5, Feitian, every FIDO2-certified platform authenticator that emits non-self-signed attestations). The verifier supports both attestation paths: self-attestation (no `x5c`, signature made by the credential's own key) and full attestation (with `x5c` chain, signature made by a manufacturer-issued attestation key).
+
+## Features
+
+- Self-attestation detection by `attStmt.x5c` absence; signature verified directly against the embedded credential public key.
+- `alg`-match check: when the credential public key carries an `alg`, it MUST equal `attStmt.alg` per W3C §8.2 step 3.1.
+- Full-attestation path: caller-supplied trust binding via `trustPath` (the leaf-first DER chain). Chain validation against a trust anchor is intentionally left to the caller; the verifier confirms structural validity and surfaces the chain.
+- Constant-time `rpIdHash` compare on both paths.
+- Signature verification delegates to `verifyOverCoseKey` from `verify-assertion`, so the same algorithm dispatch (ES256 / ES384 / ES512 / EdDSA / RS256) applies.
+
+## Usage: Basic Example
+
+```ts
+import { verifyPackedAttestation } from "@suaveplan/webauthn/attestation/packed";
+
+const result = await verifyPackedAttestation({
+    attestationObject,
+    clientDataHash,
+    expectedRpIdHash,
+});
+if (result.attestationType === "self") {
+    // RP policy: accept self-attestation for low-assurance flows.
+} else {
+    await validateChainAgainstMds(result.trustPath);
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    defaultAttestationRegistry,
+    verifyPackedAttestation,
+} from "@suaveplan/webauthn";
+
+const registry = defaultAttestationRegistry();
+// Override with a custom packed verifier that also enforces a max chain depth:
+registry.set("packed", async (input) => {
+    const r = await verifyPackedAttestation(input);
+    if (r.trustPath.length > 3) {
+        throw new Error("chain too deep");
+    }
+    return r;
+});
+```
+
+## API Reference
+
+- `verifyPackedAttestation: AttestationFormatVerifier` — the format verifier.
+
+## Implementation Notes
+
+- The verifier does not perform `x509.validateChain` against a trust anchor — that requires an out-of-band trust source (FIDO Metadata Service, per-RP attestation-CA allow-list) that the package cannot ship. The caller wires that policy via the returned `trustPath`.
+- Full-attestation `attestationType` is reported as `"basic"` rather than `"attCA"` because the W3C spec treats `packed` with `x5c` as basic attestation; `attCA` is reserved for `tpm` and `android-key` where the chain goes back to a manufacturer-rooted certification authority.
+- The signed payload is `authData || clientDataHash` — concatenated raw — per §8.2 step 2. The signature verifier hashes the message internally per the algorithm (ECDSA hashes inside; Ed25519 signs over the full message; RSA hashes inside).
+- `alg` is read as the COSE numeric label (-7 for ES256, etc.). The credential key's `alg` field is read as the named string the COSE_Key decoder produces — we cross-reference via the `NAMED_ALG_TO_LABEL` map.