# `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.