first commit

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

@@ -0,0 +1,52 @@
+# `none` attestation verifier
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Implements the W3C WebAuthn L3 §8.7 `none` attestation format. This format is used when the RP requests `attestation: "none"` on registration — the authenticator returns the credential public key inside the `authData` segment but emits no attestation statement (no signature, no certificate chain). The verifier asserts the contract: an empty `attStmt` map. A non-empty map fails closed because it indicates protocol drift between the browser, authenticator, and RP.
+
+## Features
+
+- Empty-`attStmt` check rejects with `WEBAUTHN.MALFORMED_RESPONSE` on any non-empty payload.
+- Reports `attestationType: "none"` and `trustPath: []` so consumers know there is no trust anchor for policy decisions.
+- Synchronous — the verifier does no IO and no cryptography.
+
+## Usage: Basic Example
+
+```ts
+import { verifyNoneAttestation } from "@suaveplan/webauthn/attestation/none";
+
+const result = verifyNoneAttestation({
+    attestationObject,
+    clientDataHash,
+    expectedRpIdHash,
+});
+// result.trusted === true, result.attestationType === "none"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    type AttestationFormatRegistry,
+    verifyNoneAttestation,
+} from "@suaveplan/webauthn";
+
+function customRegistry(): AttestationFormatRegistry {
+    const r = new Map();
+    r.set("none", verifyNoneAttestation);
+    return r;
+}
+```
+
+## API Reference
+
+- `verifyNoneAttestation: AttestationFormatVerifier` — the format verifier.
+
+## Implementation Notes
+
+- W3C §8.7 specifies the `attStmt` SHALL be the empty CBOR map; emitting any key constitutes a protocol violation and we reject rather than silently accepting. Production authenticators do conform; we have not observed any wild-emission.
+- `trustPath: []` is significant — relying parties that require a trust anchor (FIDO MDS lookup) cannot satisfy the policy here and must reject the registration at a higher layer.
+- The verifier is the simplest of the seven and serves as the reference implementation pattern for the others: read `attestationObject`, optionally do crypto, return `{ trusted, attestationType, trustPath }`.