entropy-auth 2026.7.31

//! `WebAuthn` / passkey authentication.
//!
//! This module wraps the [`webauthn-rs`](https://docs.rs/webauthn-rs)
//! crate (always-on per the crate's security-defaults policy), exposing
//! the registration and authentication ceremonies in the same
//! trait-and-builder shape as the rest of `entropy-auth`:
//!
//! * [`RelyingParty`] — builder for the RP-ID, RP-name, and origin
//!   allowlist (mirrors [`OAuthConfigBuilder`](crate::oauth::OAuthConfigBuilder)).
//! * [`PasskeyCredential`] — stored credential record carrying the
//!   credential ID, public key (serialised), sign-count, transports,
//!   AAGUID, label, PRF flag and salt, and timestamps.
//! * [`PasskeyCredentialStore`] — trait that mirrors
//!   [`CredentialStore`](crate::local::CredentialStore): one associated
//!   `type Error: std::error::Error` plus pluggable persistence methods.
//! * [`InMemoryPasskeyStore`] — testing-only implementation, the
//!   analogue of
//!   [`InMemoryCredentialStore`](crate::local::InMemoryCredentialStore).
//!   Backed by a `Vec` and walked with constant-time comparison so the
//!   in-memory path mirrors the rest of the crate's policy.
//! * [`RegistrationCeremony`] / [`AuthenticationCeremony`] — type-state
//!   wrappers over `webauthn-rs`'s `Webauthn` that drive the two-step
//!   begin/finish protocol and surface PRF as a flag rather than an
//!   error (per the plan's prefer-not-require model).
//!
//! # PRF / hmac-secret
//!
//! The W3C `WebAuthn` Level 3 `prf` extension lets a relying party derive
//! a credential-scoped 32-byte secret on the authenticator. Because
//! `webauthn-rs` 0.5.x does not currently expose `prf` directly — it
//! only surfaces the lower-level CTAP2 `hmac-secret` — this module
//! treats PRF as an out-of-band concern, layered on top of the
//! webauthn-rs ceremony:
//!
//! 1. At [`RegistrationCeremony::begin`], the caller can request that a
//!    [`PrfSalt`] be generated. The salt is returned alongside the
//!    challenge JSON; the documented happy path is to forward
//!    [`RegistrationChallenge::merged_challenge_json`] to the user agent,
//!    which already splices the PRF block under `publicKey.extensions.prf`.
//!    The raw [`prf_extension_json`](RegistrationChallenge::prf_extension_json)
//!    accessor is retained for callers that need to perform the splice
//!    by hand.
//! 2. The browser returns its `clientExtensionResults`; the caller
//!    extracts the `prf` block and passes it to
//!    [`RegistrationCeremony::finish`]. Whether PRF was honoured is
//!    returned in the [`RegistrationOutcome`] as a flag, never as an
//!    error.
//! 3. Authentication replays the salt under `evalByCredential`, keyed by the
//!    base64url credential ID, so a request covering several allowed
//!    credentials carries the right salt for whichever one responds. The
//!    response's `prf.results.first` presence signals that the client
//!    successfully derived its KEK. (`PrfAuthenticationRequest` still models
//!    the older single-`eval` shape and is retained for single-credential
//!    callers only.)
//!
//! See the [`prf`] module for the wire-format helpers and the
//! [WebAuthn rollout plan §2.2](https://entropysoftworks.example/plans/webauthn)
//! for the security rationale (zero-knowledge preservation, hardware
//! compatibility, no server-wrapped fallback).
//!
//! # Example
//!
//! ```ignore
//! use entropy_auth::webauthn::{
//!     RelyingParty, RegistrationCeremony, PasskeyUser, Uuid,
//! };
//!
//! let rp = RelyingParty::builder("example.com", "Example Corp")
//!     .origin("https://example.com")
//!     .build()
//!     .unwrap();
//!
//! let challenge = RegistrationCeremony::begin(
//!     &rp,
//!     PasskeyUser {
//!         id: Uuid::new_v4(),
//!         name: "alice@example.com".to_owned(),
//!         display_name: "Alice".to_owned(),
//!     },
//!     None,  // exclude_credentials
//!     true,  // request PRF
//! )
//! .unwrap();
//!
//! // Use `challenge.merged_challenge_json()` to obtain the JSON the
//! // browser expects — PRF extension already spliced under
//! // `publicKey.extensions.prf`. Persist `challenge.into_state_with_salt()`
//! // for the matching finish call; the tuple carries both the
//! // PasskeyRegistration state and the optional PrfSalt.
//! let outgoing = challenge.merged_challenge_json();
//! let (_state, _prf_salt) = challenge.into_state_with_salt();
//! # let _ = outgoing;
//! ```

use std::fmt;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use webauthn_rs::prelude::{AuthenticationResult, Url, Webauthn, WebauthnBuilder};

use crate::crypto::constant_time::constant_time_eq;
use crate::util::timestamp::Timestamp;

pub mod error;
pub mod prf;

pub use error::WebAuthnError;
pub use prf::{
    PRF_SALT_LEN, PrfAuthenticationRequest, PrfClientResult, PrfRegistrationRequest, PrfSalt,
};

// Convenience re-exports from `webauthn-rs::prelude` so consumers don't
// need a direct dependency on the upstream crate for the common types
// surfaced by our ceremonies.
pub use webauthn_rs::prelude::{
    CredentialID, Passkey, PasskeyAuthentication, PasskeyRegistration, PublicKeyCredential,
    RegisterPublicKeyCredential, Uuid,
};

// ---------------------------------------------------------------------------
// RelyingParty
// ---------------------------------------------------------------------------

/// A configured `WebAuthn` relying party.
///
/// Construct via [`RelyingParty::builder`]. The configuration is
/// validated at build time, not at ceremony time, so invalid origins
/// or empty allowlists fail fast.
///
/// Internally wraps a [`Webauthn`] from `webauthn-rs`. Sub-domain and
/// port matching follow `webauthn-rs`'s defaults (strict).
pub struct RelyingParty {
    rp_id: String,
    rp_name: String,
    origins: Vec<String>,
    inner: Webauthn,
}

impl RelyingParty {
    /// Creates a new [`RelyingPartyBuilder`] for the given RP-ID and
    /// human-readable RP-name.
    ///
    /// The `rp_id` MUST be a registrable domain suffix of the page
    /// origin (per W3C `WebAuthn` §5.1.3). Validation happens at
    /// [`build`](RelyingPartyBuilder::build).
    #[must_use]
    pub fn builder(rp_id: &str, rp_name: &str) -> RelyingPartyBuilder {
        RelyingPartyBuilder {
            rp_id: rp_id.to_owned(),
            rp_name: rp_name.to_owned(),
            origins: Vec::new(),
        }
    }

    /// Returns the relying-party identifier (e.g. `example.com`).
    #[must_use]
    #[inline]
    pub fn rp_id(&self) -> &str {
        &self.rp_id
    }

    /// Returns the human-readable relying-party name.
    #[must_use]
    #[inline]
    pub fn rp_name(&self) -> &str {
        &self.rp_name
    }

    /// Returns the configured origin allowlist.
    #[must_use]
    #[inline]
    pub fn origins(&self) -> &[String] {
        &self.origins
    }
}

impl fmt::Debug for RelyingParty {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("RelyingParty")
            .field("rp_id", &self.rp_id)
            .field("rp_name", &self.rp_name)
            .field("origins", &self.origins)
            // `inner` is the opaque webauthn-rs handle; deliberately omitted.
            .finish_non_exhaustive()
    }
}

/// Whether a host is a loopback name for which plain HTTP is permitted.
///
/// `WebAuthn` treats loopback as a secure context, so local development does not
/// need TLS. Nothing else may use HTTP.
fn is_loopback_host(host: &str) -> bool {
    // Only the NAME form: an IP-literal origin is rejected before this is
    // reached (see `validate_origin`), because webauthn-rs requires a
    // registrable domain for the RP-ID.
    host == "localhost"
}

/// Enforce the documented origin rules: HTTPS (loopback excepted) and a host
/// that is `rp_id` itself or a sub-domain of it.
///
/// A relying party that accepts an origin outside its RP-ID is accepting
/// assertions minted for a site it does not control.
fn validate_origin(url: &Url, rp_id: &str) -> Result<(), WebAuthnError> {
    let host = url
        .host_str()
        .ok_or_else(|| WebAuthnError::invalid_configuration(format!("origin {url} has no host")))?;
    // An IP-literal origin can never work: `WebauthnBuilder::new` requires the
    // RP-ID to be a registrable domain and rejects it two steps later with an
    // opaque error. Say so here instead. (`127.0.0.1` is therefore NOT a usable
    // dev origin — `http://localhost` is.)
    if host.parse::<std::net::IpAddr>().is_ok() || (host.starts_with('[') && host.ends_with(']')) {
        return Err(WebAuthnError::invalid_configuration(format!(
            "origin {url}: rp_id must be a registrable domain, not an IP literal — \
             use http://localhost for local development"
        )));
    }
    if url.scheme() != "https" && !is_loopback_host(host) {
        return Err(WebAuthnError::invalid_configuration(format!(
            "origin {url} must use https (only loopback may use http)"
        )));
    }
    // `rp_id` is a registrable suffix of the origin's host: equal, or the host
    // ends with `.<rp_id>`. A bare `endswith` would wrongly accept
    // "evilexample.com" for rp_id "example.com".
    let matches_rp = host == rp_id
        || host
            .strip_suffix(rp_id)
            .is_some_and(|prefix| prefix.ends_with('.'));
    if !matches_rp {
        return Err(WebAuthnError::invalid_configuration(format!(
            "origin {url} is not rp_id '{rp_id}' or a sub-domain of it"
        )));
    }
    Ok(())
}

/// Builder for [`RelyingParty`].
///
/// At least one origin must be supplied before calling
/// [`build`](RelyingPartyBuilder::build).
#[derive(Clone, Debug)]
pub struct RelyingPartyBuilder {
    rp_id: String,
    rp_name: String,
    origins: Vec<String>,
}

impl RelyingPartyBuilder {
    /// Appends an origin to the allowlist. Origins must be HTTPS
    /// (except `localhost` for development), parseable as a URL, and
    /// share the RP-ID as a registrable domain suffix.
    #[must_use]
    pub fn origin(mut self, origin: &str) -> Self {
        self.origins.push(origin.to_owned());
        self
    }

    /// Validates the configuration and constructs the underlying
    /// [`Webauthn`].
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError::invalid_configuration`] if:
    /// * `rp_id` is empty.
    /// * No origins were supplied.
    /// * Any origin fails to parse as a URL.
    /// * Any origin is not HTTPS (loopback may use HTTP for development).
    /// * Any origin's host is not `rp_id` or a sub-domain of it.
    /// * The upstream [`WebauthnBuilder`] rejects the configuration
    ///   (typically a sub-domain or scheme mismatch).
    pub fn build(self) -> Result<RelyingParty, WebAuthnError> {
        if self.rp_id.is_empty() {
            return Err(WebAuthnError::invalid_configuration("rp_id is empty"));
        }
        if self.origins.is_empty() {
            return Err(WebAuthnError::invalid_configuration(
                "at least one origin is required",
            ));
        }

        // Parse all origins up front. webauthn-rs takes a single primary
        // origin and accepts additional origins via `append_allowed_origin`.
        let mut parsed_origins: Vec<Url> = Vec::with_capacity(self.origins.len());
        for raw in &self.origins {
            let url = Url::parse(raw).map_err(|e| {
                WebAuthnError::invalid_configuration(format!("invalid origin {raw}: {e}"))
            })?;
            // Enforced here, for EVERY origin. webauthn-rs validates only the
            // primary origin it is constructed with; `append_allowed_origin`
            // takes the rest on trust. Since these documented rules are what
            // stop a misconfigured deployment from accepting assertions from a
            // plaintext or unrelated origin, they cannot live in the docs alone.
            validate_origin(&url, &self.rp_id)?;
            parsed_origins.push(url);
        }

        let primary = parsed_origins
            .first()
            .ok_or_else(|| WebAuthnError::invalid_configuration("no primary origin"))?
            .clone();

        let mut builder = WebauthnBuilder::new(&self.rp_id, &primary)
            .map_err(|e| WebAuthnError::invalid_configuration(e.to_string()))?
            .rp_name(&self.rp_name);

        for extra in parsed_origins.iter().skip(1) {
            builder = builder.append_allowed_origin(extra);
        }

        let inner = builder
            .build()
            .map_err(|e| WebAuthnError::invalid_configuration(e.to_string()))?;

        Ok(RelyingParty {
            rp_id: self.rp_id,
            rp_name: self.rp_name,
            origins: self.origins,
            inner,
        })
    }
}

// ---------------------------------------------------------------------------
// PasskeyCredential
// ---------------------------------------------------------------------------

/// A stored passkey credential record.
///
/// Mirrors the on-disk shape called out in the rollout plan's Phase 2
/// `user_passkeys` schema:
///
/// * `credential_id` — opaque byte string, unique per credential.
/// * `passkey` — the full serialised webauthn-rs [`Passkey`] (contains
///   the COSE public key, sign-count, transports, AAGUID, and per-cred
///   policy). Stored as opaque CBOR/JSON in the database.
/// * `sign_count` — the counter the crate's explicit rollback check
///   ([`AuthenticationCeremony::finish`]) reads and that
///   [`PasskeyCredentialStore::update_sign_count`] keeps current; the
///   embedded [`Passkey`] also carries a counter that webauthn-rs maintains
///   internally, but it is this field that gates our rollback decision.
/// * `transports` — denormalised list of authenticator transports.
/// * `aaguid` — authenticator attestation GUID (zero bytes for
///   self-attesting authenticators).
/// * `label` — user-supplied nickname ("`YubiKey` 5", "iPhone").
/// * `prf_supported` — set at registration based on the assertion's
///   `clientExtensionResults.prf`. Drives the unlock badge in the UI.
/// * `prf_salt` — present iff `prf_supported`; the 32-byte salt used
///   to derive the client-side KEK.
/// * `created_at` / `last_used_at` — UTC timestamps.
#[derive(Clone, Serialize, Deserialize)]
pub struct PasskeyCredential {
    credential_id: Vec<u8>,
    passkey: Passkey,
    sign_count: u32,
    transports: Vec<String>,
    aaguid: Vec<u8>,
    label: String,
    prf_supported: bool,
    prf_salt: Option<PrfSalt>,
    created_at: Timestamp,
    last_used_at: Option<Timestamp>,
}

impl PasskeyCredential {
    /// Returns the credential ID bytes (opaque, unique per credential).
    #[must_use]
    #[inline]
    pub fn credential_id(&self) -> &[u8] {
        &self.credential_id
    }

    /// Returns the embedded webauthn-rs [`Passkey`], suitable for
    /// passing back into [`AuthenticationCeremony::begin`].
    #[must_use]
    #[inline]
    pub fn passkey(&self) -> &Passkey {
        &self.passkey
    }

    /// Returns the last-known authenticator sign-count.
    #[must_use]
    #[inline]
    pub fn sign_count(&self) -> u32 {
        self.sign_count
    }

    /// Apply an authentication result to the stored credential, returning
    /// whether anything changed (i.e. whether the caller must re-persist).
    ///
    /// The embedded [`Passkey`] carries state webauthn-rs maintains itself —
    /// its own counter plus the backup-eligibility / backup-state flags — and
    /// the ceremony previously exposed the `Passkey` only immutably, so
    /// `update_credential` could never be applied and the stored blob drifted
    /// permanently out of date. The separate `sign_count` field (which gates
    /// our explicit rollback check) is synced alongside it.
    pub fn apply_authentication_result(&mut self, result: &AuthenticationResult) -> bool {
        let changed = self.passkey.update_credential(result).unwrap_or(false);
        if self.sign_count < result.counter() {
            self.sign_count = result.counter();
            return true;
        }
        changed
    }

    /// Returns the authenticator-asserted transport hints.
    #[must_use]
    #[inline]
    pub fn transports(&self) -> &[String] {
        &self.transports
    }

    /// Returns the authenticator AAGUID (16 bytes, zeros for
    /// self-attesting passkeys).
    #[must_use]
    #[inline]
    pub fn aaguid(&self) -> &[u8] {
        &self.aaguid
    }

    /// Returns the user-supplied label.
    #[must_use]
    #[inline]
    pub fn label(&self) -> &str {
        &self.label
    }

    /// Returns `true` if this credential is PRF-capable.
    #[must_use]
    #[inline]
    pub fn prf_supported(&self) -> bool {
        self.prf_supported
    }

    /// Returns the per-credential PRF salt, if this credential is
    /// PRF-capable. The salt is `None` exactly when
    /// [`prf_supported`](Self::prf_supported) returns `false`.
    #[must_use]
    #[inline]
    pub fn prf_salt(&self) -> Option<&PrfSalt> {
        self.prf_salt.as_ref()
    }

    /// Returns the credential's creation timestamp.
    #[must_use]
    #[inline]
    pub fn created_at(&self) -> &Timestamp {
        &self.created_at
    }

    /// Returns the credential's last-used timestamp, if any.
    #[must_use]
    #[inline]
    pub fn last_used_at(&self) -> Option<&Timestamp> {
        self.last_used_at.as_ref()
    }

    /// Renames the credential. Returns a new value (functional update).
    #[must_use]
    pub fn with_label(mut self, label: impl Into<String>) -> Self {
        self.label = label.into();
        self
    }

    /// Returns a copy with the signature counter updated to `sign_count`.
    ///
    /// A storage-backed [`PasskeyCredentialStore`] persists the credential as
    /// opaque bytes and reloads it for the next ceremony; the
    /// rollback-detection check in [`AuthenticationCeremony::finish`] compares
    /// the asserted counter against this field, so after a successful
    /// authentication the caller MUST persist the credential with the new
    /// counter ([`AuthenticationOutcome::new_sign_count`]) — otherwise every
    /// future assertion is compared against the stale registration-time
    /// counter and replay/rollback detection degrades. This functional update
    /// lets a serialize-based store apply that bump before re-persisting.
    #[must_use]
    pub fn with_sign_count(mut self, sign_count: u32) -> Self {
        self.sign_count = sign_count;
        self
    }
}

impl fmt::Debug for PasskeyCredential {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // SECURITY: redact the embedded Passkey's public key and the
        // PRF salt. credential_id is rendered as a length to keep
        // logs readable.
        f.debug_struct("PasskeyCredential")
            .field("credential_id_len", &self.credential_id.len())
            .field("sign_count", &self.sign_count)
            .field("transports", &self.transports)
            .field("aaguid_len", &self.aaguid.len())
            .field("label", &self.label)
            .field("prf_supported", &self.prf_supported)
            .field("prf_salt", &self.prf_salt)
            .field("created_at", &self.created_at)
            .field("last_used_at", &self.last_used_at)
            .finish_non_exhaustive()
    }
}

// ---------------------------------------------------------------------------
// PasskeyCredentialStore trait
// ---------------------------------------------------------------------------

/// Trait for passkey credential storage backends.
///
/// Mirrors [`CredentialStore`](crate::local::CredentialStore) exactly:
/// one associated error type, pluggable persistence. Implementations
/// keyed on `(user_id, credential_id)` and on `credential_id` alone
/// for the authenticate-by-discoverable-credential path.
///
/// All implementations MUST treat `credential_id` as opaque bytes and
/// MUST NOT trust its length to be bounded.
pub trait PasskeyCredentialStore {
    /// Error type returned by storage operations.
    type Error: std::error::Error;

    /// Returns all passkeys registered to the given user.
    ///
    /// # Errors
    ///
    /// Returns the backend's error if the lookup fails.
    fn lookup_by_user(&self, user_id: &[u8]) -> Result<Vec<PasskeyCredential>, Self::Error>;

    /// Returns the credential with the given credential ID, if any.
    ///
    /// # Errors
    ///
    /// Returns the backend's error if the lookup fails.
    fn lookup_by_credential_id(
        &self,
        credential_id: &[u8],
    ) -> Result<Option<PasskeyCredential>, Self::Error>;

    /// Persists a new credential.
    ///
    /// # Contract
    ///
    /// `WebAuthn` §7.1 step 22 requires that a credential ID is not already
    /// registered to ANOTHER user. Nothing in the crate enforced that — the
    /// registration ceremony takes no store — so an implementation was free to
    /// silently re-point an existing credential at a different user handle,
    /// which is an account-takeover primitive for anyone who can replay a
    /// registration. Implementations MUST fail rather than rebind an existing
    /// credential ID to a different `user_id`; re-storing the SAME
    /// (`user_id`, `credential_id`) pair is an idempotent update and is allowed.
    ///
    /// # Errors
    ///
    /// Returns the backend's error if persistence fails, or if the credential
    /// ID is already registered to a different user.
    fn store(&mut self, user_id: &[u8], credential: &PasskeyCredential) -> Result<(), Self::Error>;

    /// Updates the sign-count for the given credential.
    ///
    /// # Errors
    ///
    /// Returns the backend's error if the update fails.
    fn update_sign_count(
        &mut self,
        credential_id: &[u8],
        sign_count: u32,
    ) -> Result<(), Self::Error>;

    /// Updates the last-used timestamp for the given credential.
    ///
    /// # Errors
    ///
    /// Returns the backend's error if the update fails.
    fn update_last_used(
        &mut self,
        credential_id: &[u8],
        last_used_at: Timestamp,
    ) -> Result<(), Self::Error>;

    /// Removes the credential. Returns `Ok(true)` if a row was deleted,
    /// `Ok(false)` if no matching credential existed.
    ///
    /// # Errors
    ///
    /// Returns the backend's error if the delete fails.
    fn remove(&mut self, credential_id: &[u8]) -> Result<bool, Self::Error>;
}

// ---------------------------------------------------------------------------
// InMemoryPasskeyStore
// ---------------------------------------------------------------------------

/// A passkey store for testing and prototyping.
///
/// Not suitable for production use. Mirrors
/// [`InMemoryCredentialStore`](crate::local::InMemoryCredentialStore).
///
/// # Comparisons
///
/// Credential-ID and user-handle comparisons go through
/// [`constant_time_eq`] rather
/// than the more efficient `HashMap` lookup. `WebAuthn` credential IDs are
/// public per §6.1, but a constant-time path here keeps the in-memory
/// store consistent with the rest of the crate's comparison policy and
/// avoids surprises if a test fixture is reused as a building block in
/// a higher-stakes context. Production stores (`SqlxPasskeyStore`,
/// Phase 2) defer the comparison to the database, where indexed
/// lookups are not the timing-attack vector this guard protects.
pub struct InMemoryPasskeyStore {
    // Linear store: `(user_handle, credential)` entries. The Vec is
    // walked in full on every lookup so the lookup time is independent
    // of which entry matches.
    entries: Vec<(Vec<u8>, PasskeyCredential)>,
}

impl Default for InMemoryPasskeyStore {
    fn default() -> Self {
        Self::new()
    }
}

impl InMemoryPasskeyStore {
    /// Creates an empty in-memory passkey store.
    #[must_use]
    pub fn new() -> Self {
        Self {
            entries: Vec::new(),
        }
    }
}

impl fmt::Debug for InMemoryPasskeyStore {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("InMemoryPasskeyStore")
            .field("len", &self.entries.len())
            .finish()
    }
}

/// Error type for the in-memory passkey store.
///
/// Mirrors the in-memory [`CredentialStore`](crate::local) error — the in-memory
/// store never produces errors in practice, but the trait requires an
/// error type.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InMemoryPasskeyStoreError {
    kind: InMemoryPasskeyStoreErrorKind,
}

/// Why an in-memory store operation failed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum InMemoryPasskeyStoreErrorKind {
    /// The credential ID is already registered to a different user.
    CredentialIdInUse,
}

impl InMemoryPasskeyStoreError {
    /// Whether this is the `WebAuthn` §7.1 step 22 uniqueness violation.
    #[must_use]
    pub fn is_credential_id_in_use(&self) -> bool {
        self.kind == InMemoryPasskeyStoreErrorKind::CredentialIdInUse
    }
}

impl fmt::Display for InMemoryPasskeyStoreError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.kind {
            InMemoryPasskeyStoreErrorKind::CredentialIdInUse => {
                f.write_str("in-memory passkey store: credential ID already registered")
            }
        }
    }
}

impl std::error::Error for InMemoryPasskeyStoreError {}

impl PasskeyCredentialStore for InMemoryPasskeyStore {
    type Error = InMemoryPasskeyStoreError;

    fn lookup_by_user(&self, user_id: &[u8]) -> Result<Vec<PasskeyCredential>, Self::Error> {
        // SECURITY: walk the full vec on every lookup; compare each
        // user-handle through constant_time_eq.
        Ok(self
            .entries
            .iter()
            .filter(|(uid, _)| constant_time_eq(uid, user_id))
            .map(|(_, cred)| cred.clone())
            .collect())
    }

    fn lookup_by_credential_id(
        &self,
        credential_id: &[u8],
    ) -> Result<Option<PasskeyCredential>, Self::Error> {
        // SECURITY: walk the full vec on every lookup; compare each
        // credential ID through constant_time_eq.
        let mut found: Option<PasskeyCredential> = None;
        for (_, cred) in &self.entries {
            if constant_time_eq(&cred.credential_id, credential_id) {
                found = Some(cred.clone());
            }
        }
        Ok(found)
    }

    fn store(&mut self, user_id: &[u8], credential: &PasskeyCredential) -> Result<(), Self::Error> {
        // WebAuthn §7.1 step 22: a credential ID already registered to a
        // DIFFERENT user must be refused. Re-pointing it (as the previous
        // insert-replace semantics did) lets a replayed registration move
        // someone else's authenticator onto the attacker's account. Walk the
        // full vec so the comparison stays constant-time.
        let mut replaced = false;
        for entry in &mut self.entries {
            if constant_time_eq(&entry.1.credential_id, &credential.credential_id) {
                if !constant_time_eq(&entry.0, user_id) {
                    return Err(InMemoryPasskeyStoreError {
                        kind: InMemoryPasskeyStoreErrorKind::CredentialIdInUse,
                    });
                }
                entry.1 = credential.clone();
                replaced = true;
            }
        }
        if !replaced {
            self.entries.push((user_id.to_vec(), credential.clone()));
        }
        Ok(())
    }

    fn update_sign_count(
        &mut self,
        credential_id: &[u8],
        sign_count: u32,
    ) -> Result<(), Self::Error> {
        for entry in &mut self.entries {
            if constant_time_eq(&entry.1.credential_id, credential_id) {
                entry.1.sign_count = sign_count;
            }
        }
        Ok(())
    }

    fn update_last_used(
        &mut self,
        credential_id: &[u8],
        last_used_at: Timestamp,
    ) -> Result<(), Self::Error> {
        for entry in &mut self.entries {
            if constant_time_eq(&entry.1.credential_id, credential_id) {
                entry.1.last_used_at = Some(last_used_at);
            }
        }
        Ok(())
    }

    fn remove(&mut self, credential_id: &[u8]) -> Result<bool, Self::Error> {
        let before = self.entries.len();
        self.entries
            .retain(|(_, cred)| !constant_time_eq(&cred.credential_id, credential_id));
        Ok(self.entries.len() != before)
    }
}

// ---------------------------------------------------------------------------
// Registration ceremony
// ---------------------------------------------------------------------------

/// User identifier for a passkey registration.
///
/// `id` is the `WebAuthn` `user.id` — a 1-to-64-byte opaque handle that
/// the authenticator MAY store. `name` is the human-readable account
/// identifier (e.g. an email address). `display_name` is the
/// human-friendly label shown by the authenticator UI.
#[derive(Clone, Debug)]
pub struct PasskeyUser {
    /// Opaque user handle (1–64 bytes).
    pub id: Uuid,
    /// Account identifier shown in the credential picker.
    pub name: String,
    /// Display name shown by the authenticator.
    pub display_name: String,
}

/// Output of [`RegistrationCeremony::begin`].
///
/// The caller MUST persist `state` (server-side) and forward
/// `challenge_json` to the user agent. If `prf_extension_json` is
/// `Some`, the caller MUST merge it into the outgoing
/// `publicKey.extensions.prf` field before sending to the browser.
pub struct RegistrationChallenge {
    challenge_json: Value,
    state: PasskeyRegistration,
    prf_salt: Option<PrfSalt>,
    prf_extension_json: Option<Value>,
}

impl RegistrationChallenge {
    /// The raw `PublicKeyCredentialCreationOptions` JSON produced by
    /// `webauthn-rs`, **without** the PRF extension spliced in.
    ///
    /// Most callers want [`merged_challenge_json`](Self::merged_challenge_json)
    /// instead — it returns the same JSON with the PRF extension already
    /// merged under `publicKey.extensions.prf`. Use this accessor only
    /// when you need to perform the splice yourself (e.g. to layer
    /// additional extensions or to round-trip the raw shape through
    /// caching).
    #[must_use]
    pub fn challenge_json(&self) -> &Value {
        &self.challenge_json
    }

    /// The `PublicKeyCredentialCreationOptions` JSON the user agent
    /// expects, with the PRF extension (if any) already spliced in
    /// under `publicKey.extensions.prf`.
    ///
    /// This is the documented happy-path API for forwarding the
    /// challenge to the browser: call it, encode as JSON, ship to the
    /// client. Forgetting the manual splice required by the legacy
    /// [`prf_extension_json`](Self::prf_extension_json) accessor used
    /// to silently disable PRF.
    ///
    /// The merge is pure and idempotent: any pre-existing
    /// `publicKey.extensions` object emitted by `webauthn-rs` is
    /// preserved verbatim, and only the `prf` key under `extensions`
    /// is touched. If no PRF was requested, this is equivalent to
    /// [`challenge_json`](Self::challenge_json).
    #[must_use]
    pub fn merged_challenge_json(&self) -> Value {
        merge_prf_extension(&self.challenge_json, self.prf_extension_json.as_ref())
    }

    /// Server-side ceremony state. MUST be persisted (e.g. in
    /// `passkey_challenges`) and replayed on the matching
    /// [`RegistrationCeremony::finish`] call.
    #[must_use]
    pub fn state(&self) -> &PasskeyRegistration {
        &self.state
    }

    /// Consumes the challenge, returning ownership of the state for
    /// serialisation.
    ///
    /// **Discards the PRF salt.** Use this only when the salt does not
    /// need to round-trip — typically in tests that begin and finish
    /// the ceremony in the same scope, or for callers that have not
    /// opted into PRF. Persistence-flow callers must use
    /// [`into_state_with_salt`](Self::into_state_with_salt) instead;
    /// otherwise the salt is dropped and PRF cannot be honoured on
    /// the matching [`RegistrationCeremony::finish`] call.
    #[must_use]
    pub fn into_state(self) -> PasskeyRegistration {
        self.state
    }

    /// Consumes the challenge, returning both the state and the
    /// (optional) PRF salt as a single tuple.
    ///
    /// This is the persistence-friendly variant of
    /// [`into_state`](Self::into_state): when the begin and finish
    /// handlers are separate HTTP requests (the common case), both
    /// pieces must survive the round-trip to the storage layer.
    /// Callers can persist the tuple together (e.g. one row keyed by
    /// challenge id) instead of juggling two columns or a JSON sidecar
    /// to keep them aligned.
    ///
    /// The salt is `None` iff PRF was not requested at
    /// [`RegistrationCeremony::begin`].
    #[must_use]
    pub fn into_state_with_salt(self) -> (PasskeyRegistration, Option<PrfSalt>) {
        (self.state, self.prf_salt)
    }

    /// The salt assigned to this candidate credential, if PRF was
    /// requested. The salt must be persisted alongside the eventual
    /// stored credential.
    #[must_use]
    pub fn prf_salt(&self) -> Option<&PrfSalt> {
        self.prf_salt.as_ref()
    }

    /// The PRF extension JSON to merge into `publicKey.extensions.prf`
    /// when forwarding the challenge to the user agent. Returns `None`
    /// when PRF was not requested.
    ///
    /// Prefer [`merged_challenge_json`](Self::merged_challenge_json),
    /// which performs the splice for you. This accessor is retained
    /// for callers that need fine-grained control over the outgoing
    /// JSON shape.
    #[must_use]
    pub fn prf_extension_json(&self) -> Option<&Value> {
        self.prf_extension_json.as_ref()
    }
}

/// Successful outcome of [`RegistrationCeremony::finish`].
///
/// The caller stores `credential` and reads `prf_supported` to drive
/// the per-credential unlock-badge UI.
pub struct RegistrationOutcome {
    /// The newly-registered credential, ready to be persisted via
    /// [`PasskeyCredentialStore::store`].
    pub credential: PasskeyCredential,
    /// Whether the authenticator honored the PRF extension during this
    /// registration. Mirrors the credential's `prf_supported` field
    /// for convenience.
    pub prf_supported: bool,
}

/// Drives a `WebAuthn` registration ceremony.
///
/// Sole entry-point: [`RegistrationCeremony::begin`] returns a
/// [`RegistrationChallenge`]; the matching call to
/// [`RegistrationCeremony::finish`] consumes the state.
pub struct RegistrationCeremony;

impl RegistrationCeremony {
    /// Starts a registration ceremony.
    ///
    /// `exclude_credentials` SHOULD list the credential IDs already
    /// registered to this user, so the authenticator avoids enrolling
    /// the same key twice.
    ///
    /// `request_prf` controls whether a [`PrfSalt`] is generated and
    /// the PRF extension is requested. Passing `false` disables PRF
    /// for this credential at registration; passing `true` requests
    /// PRF but does **not** require it — the authenticator may decline.
    ///
    /// # Forwarding the challenge
    ///
    /// Use [`RegistrationChallenge::merged_challenge_json`] to obtain
    /// the JSON that should be shipped to the user agent. It returns
    /// `webauthn-rs`'s challenge JSON with the PRF extension already
    /// spliced under `publicKey.extensions.prf`; forgetting that
    /// splice silently disables PRF for the credential.
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError`] if:
    /// * The platform CSPRNG fails while generating a PRF salt
    ///   ([`WebAuthnError::is_internal`]).
    /// * webauthn-rs rejects the user fields
    ///   ([`WebAuthnError::is_internal`]).
    // `user` is taken by value as the intended caller ergonomics (callers build
    // a `PasskeyUser` and hand it off); its fields are Copy/borrowed internally.
    #[allow(clippy::needless_pass_by_value)]
    pub fn begin(
        rp: &RelyingParty,
        user: PasskeyUser,
        exclude_credentials: Option<Vec<CredentialID>>,
        request_prf: bool,
    ) -> Result<RegistrationChallenge, WebAuthnError> {
        let (ccr, state) = rp
            .inner
            .start_passkey_registration(
                user.id,
                &user.name,
                &user.display_name,
                exclude_credentials,
            )
            .map_err(|e| WebAuthnError::internal(format!("start_passkey_registration: {e}")))?;

        let challenge_json = serde_json::to_value(&ccr)
            .map_err(|e| WebAuthnError::internal(format!("serialise challenge: {e}")))?;

        let (prf_salt, prf_extension_json) = if request_prf {
            let salt = PrfSalt::generate()
                .map_err(|e| WebAuthnError::internal(format!("prf salt random: {e}")))?;
            let ext = PrfRegistrationRequest::from_salt(&salt).to_json_value();
            (Some(salt), Some(ext))
        } else {
            (None, None)
        };

        Ok(RegistrationChallenge {
            challenge_json,
            state,
            prf_salt,
            prf_extension_json,
        })
    }

    /// Completes a registration ceremony.
    ///
    /// `state` is the value returned from
    /// [`RegistrationChallenge::into_state`] (or a deserialised copy
    /// that was persisted between requests). `client_response` is the
    /// `RegisterPublicKeyCredential` returned by the user agent.
    /// `client_extension_results` is the user agent's
    /// `getClientExtensionResults()` — pass `None` if the user agent
    /// returned no extension results.
    ///
    /// `label` is the user-supplied nickname; pass an empty string and
    /// rename later via [`PasskeyCredential::with_label`] if the UI
    /// collects the label after registration completes.
    ///
    /// # PRF
    ///
    /// `prf_salt` MUST be the same salt returned by
    /// [`RegistrationChallenge::prf_salt`] if PRF was requested. If
    /// the authenticator honored PRF, the salt is stored on the
    /// returned [`PasskeyCredential`]; otherwise it is discarded and
    /// `prf_supported` is set to `false`. Missing PRF is **not** an
    /// error.
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError`] with one of:
    /// * `is_attestation_failed` — signature, certificate, or
    ///   authenticator-data verification failed.
    /// * `is_origin_mismatch` — assertion origin not in RP allowlist.
    /// * `is_rp_id_mismatch` — RP-ID hash mismatch.
    /// * `is_challenge_mismatch` — state vs. response mismatch.
    /// * `is_internal` — upstream library error not otherwise
    ///   categorised.
    pub fn finish(
        rp: &RelyingParty,
        state: &PasskeyRegistration,
        client_response: &RegisterPublicKeyCredential,
        client_extension_results: Option<&Value>,
        prf_salt: Option<PrfSalt>,
        label: impl Into<String>,
        now: Timestamp,
    ) -> Result<RegistrationOutcome, WebAuthnError> {
        let passkey = rp
            .inner
            .finish_passkey_registration(client_response, state)
            .map_err(map_webauthn_register_error)?;

        let credential_id = passkey.cred_id().as_ref().to_vec();
        // `webauthn-rs` 0.5 keeps the inner `cred.transports`, the
        // AAGUID (nested under `cred.attestation.metadata`), and the
        // counter behind a `pub(crate)` boundary on `Passkey`. We
        // recover them by round-tripping through the public serde
        // shape; see `passkey_metadata` for the defensive details and
        // the test pinning the current `webauthn-rs` shape.
        let (aaguid, transports, sign_count) = passkey_metadata(&passkey);

        let prf_result = client_extension_results
            .map_or(PrfClientResult::Absent, prf::inspect_registration_response);
        // Gate on a salt actually having been generated for this ceremony, not
        // on the client-supplied extension echo alone: otherwise a client that
        // reports PRF when none was requested (`prf_salt` = None) would set
        // `prf_supported = true` with no stored salt, breaking the documented
        // `prf_salt present iff prf_supported` invariant.
        let prf_supported = prf_salt.is_some() && prf_result.was_honored();
        let stored_salt = if prf_supported { prf_salt } else { None };

        let credential = PasskeyCredential {
            credential_id,
            passkey,
            sign_count,
            transports,
            aaguid,
            label: label.into(),
            prf_supported,
            prf_salt: stored_salt,
            created_at: now,
            last_used_at: None,
        };

        Ok(RegistrationOutcome {
            credential,
            prf_supported,
        })
    }
}

// ---------------------------------------------------------------------------
// Authentication ceremony
// ---------------------------------------------------------------------------

/// Output of [`AuthenticationCeremony::begin`].
///
/// Mirrors [`RegistrationChallenge`]: the caller persists `state`,
/// forwards `challenge_json`, and merges `prf_extension_json` into
/// `publicKey.extensions.prf` if present.
pub struct AuthenticationChallenge {
    challenge_json: Value,
    state: PasskeyAuthentication,
    prf_extension_json: Option<Value>,
}

impl AuthenticationChallenge {
    /// The raw `PublicKeyCredentialRequestOptions` JSON produced by
    /// `webauthn-rs`, **without** the PRF extension spliced in.
    ///
    /// Most callers want [`merged_challenge_json`](Self::merged_challenge_json)
    /// instead. This accessor is retained for callers that need
    /// fine-grained control over the outgoing JSON shape.
    #[must_use]
    pub fn challenge_json(&self) -> &Value {
        &self.challenge_json
    }

    /// The `PublicKeyCredentialRequestOptions` JSON the user agent
    /// expects, with the PRF extension (if any) already spliced in
    /// under `publicKey.extensions.prf`.
    ///
    /// This is the documented happy-path API for forwarding the
    /// challenge to the browser. The merge is pure and idempotent:
    /// any pre-existing `publicKey.extensions` object emitted by
    /// `webauthn-rs` is preserved verbatim and only the `prf` key
    /// under `extensions` is touched. If no PRF-capable credentials
    /// were supplied to [`AuthenticationCeremony::begin`], this is
    /// equivalent to [`challenge_json`](Self::challenge_json).
    #[must_use]
    pub fn merged_challenge_json(&self) -> Value {
        merge_prf_extension(&self.challenge_json, self.prf_extension_json.as_ref())
    }

    /// Server-side ceremony state. MUST be persisted and replayed on
    /// the matching [`AuthenticationCeremony::finish`] call.
    #[must_use]
    pub fn state(&self) -> &PasskeyAuthentication {
        &self.state
    }

    /// Consumes the challenge, returning ownership of the state.
    #[must_use]
    pub fn into_state(self) -> PasskeyAuthentication {
        self.state
    }

    /// The PRF extension JSON to splice into the outgoing challenge,
    /// or `None` if no PRF-capable credentials were supplied to
    /// [`AuthenticationCeremony::begin`].
    ///
    /// Prefer [`merged_challenge_json`](Self::merged_challenge_json),
    /// which performs the splice for you.
    #[must_use]
    pub fn prf_extension_json(&self) -> Option<&Value> {
        self.prf_extension_json.as_ref()
    }
}

/// Successful outcome of [`AuthenticationCeremony::finish`].
pub struct AuthenticationOutcome {
    /// The credential ID that authenticated.
    pub credential_id: Vec<u8>,
    /// The new sign-count to persist via
    /// [`PasskeyCredentialStore::update_sign_count`].
    pub new_sign_count: u32,
    /// Whether the assertion asserted user-verified (UV).
    pub user_verified: bool,
    /// Whether the authenticator honored the PRF extension on this
    /// authentication. When `true`, the client successfully derived
    /// its KEK and the relying party should return the stored
    /// wrap row in its response. When `false`, the relying party
    /// returns no wrap and the client falls back to the master
    /// password unlock path.
    pub prf_supported: bool,
    /// Whether webauthn-rs reports the stored [`Passkey`] itself needs
    /// re-persisting (`AuthenticationResult::needs_update`).
    ///
    /// This is separate from `new_sign_count`: the embedded `Passkey` also
    /// carries backup-eligibility / backup-state flags that change over a
    /// credential's life. Ignoring it left the stored blob stale, so those
    /// flags never reflected reality. Callers should call
    /// [`PasskeyCredential::apply_authentication_result`] and re-persist when
    /// this is `true`.
    pub needs_update: bool,
}

/// Drives a `WebAuthn` authentication ceremony.
pub struct AuthenticationCeremony;

impl AuthenticationCeremony {
    /// Starts an authentication ceremony against a known set of
    /// credentials.
    ///
    /// The provided `allow_credentials` MUST be the user's full passkey
    /// set (typically from
    /// [`PasskeyCredentialStore::lookup_by_user`]). Each PRF-capable
    /// credential's own salt is spliced into the request via the
    /// `evalByCredential` map (`WebAuthn` L3), keyed by credential ID, so the
    /// authenticator derives PRF output with the correct salt for whichever
    /// credential it signs with — correct even when the user has several PRF
    /// credentials with distinct salts.
    ///
    /// # Forwarding the challenge
    ///
    /// Use [`AuthenticationChallenge::merged_challenge_json`] to obtain
    /// the JSON to ship to the user agent. It pre-merges the PRF
    /// extension under `publicKey.extensions.prf`; the bare
    /// [`AuthenticationChallenge::challenge_json`] accessor does not.
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError::is_internal`] if `webauthn-rs` rejects
    /// the credential set.
    pub fn begin(
        rp: &RelyingParty,
        allow_credentials: &[PasskeyCredential],
    ) -> Result<AuthenticationChallenge, WebAuthnError> {
        let passkeys: Vec<Passkey> = allow_credentials
            .iter()
            .map(|c| c.passkey.clone())
            .collect();
        let (rcr, state) = rp
            .inner
            .start_passkey_authentication(&passkeys)
            .map_err(|e| WebAuthnError::internal(format!("start_passkey_authentication: {e}")))?;

        let challenge_json = serde_json::to_value(&rcr)
            .map_err(|e| WebAuthnError::internal(format!("serialise challenge: {e}")))?;

        // PRF on authentication: emit `evalByCredential` keyed by each
        // PRF-capable credential's ID → that credential's own salt. This is
        // correct for users with more than one PRF credential — a single
        // `eval.first` would send one salt for all of them, deriving the wrong
        // KEK when a different credential signs. The authenticator honors the
        // extension only for whichever PRF-capable credential it signs with.
        let prf_entries: Vec<(&[u8], &PrfSalt)> = allow_credentials
            .iter()
            .filter_map(|c| {
                c.prf_salt
                    .as_ref()
                    .map(|salt| (c.credential_id.as_slice(), salt))
            })
            .collect();
        let prf_extension_json = prf::eval_by_credential_value(&prf_entries);

        Ok(AuthenticationChallenge {
            challenge_json,
            state,
            prf_extension_json,
        })
    }

    /// Completes an authentication ceremony.
    ///
    /// `store` is consulted to verify the asserted credential exists
    /// and to read the stored sign-count. The sign-count check rejects
    /// any assertion whose counter is less than or equal to the
    /// stored value (per `WebAuthn` §7.2 step 21).
    ///
    /// `client_extension_results` is the user agent's
    /// `getClientExtensionResults()`; pass `None` for clients that
    /// don't return extensions.
    ///
    /// `require_user_verification` adds an explicit post-check that the
    /// authenticator asserted user verification. It is **defense-in-depth
    /// only**: passing `false` does **not** disable UV — webauthn-rs already
    /// enforces `UserVerificationPolicy::Required` for passkeys during
    /// `finish_passkey_authentication`, so a non-UV assertion is rejected
    /// upstream regardless. Passing `true` re-asserts that invariant here.
    ///
    /// # Security
    ///
    /// The distinct error variants below exist for server-side logging and
    /// metrics only. To avoid credential enumeration, callers **must**
    /// collapse every failure into a single opaque response over the wire —
    /// never signal to the client which check failed (unknown credential
    /// vs. sign-count rollback vs. bad signature).
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError`] with one of:
    /// * `is_credential_not_found` — assertion references an unknown
    ///   credential ID.
    /// * `is_sign_count_rollback` — counter did not advance.
    /// * `is_user_verification_failed` — UV required but not asserted.
    /// * `is_attestation_failed` — signature verification failed.
    /// * `is_origin_mismatch`, `is_rp_id_mismatch`,
    ///   `is_challenge_mismatch` — assertion failed structural checks.
    /// * `is_internal` — upstream library error.
    pub fn finish<S>(
        rp: &RelyingParty,
        state: &PasskeyAuthentication,
        client_response: &PublicKeyCredential,
        client_extension_results: Option<&Value>,
        store: &S,
        require_user_verification: bool,
    ) -> Result<AuthenticationOutcome, WebAuthnError>
    where
        S: PasskeyCredentialStore,
    {
        let result: AuthenticationResult = rp
            .inner
            .finish_passkey_authentication(client_response, state)
            .map_err(map_webauthn_auth_error)?;

        let credential_id: Vec<u8> = result.cred_id().as_ref().to_vec();

        let stored = store
            .lookup_by_credential_id(&credential_id)
            .map_err(|e| WebAuthnError::internal(format!("store lookup: {e}")))?
            .ok_or_else(WebAuthnError::credential_not_found)?;

        let new_sign_count: u32 = result.counter();
        check_sign_count(new_sign_count, stored.sign_count)?;

        if require_user_verification && !result.user_verified() {
            return Err(WebAuthnError::user_verification_failed());
        }

        let prf_result = client_extension_results.map_or(
            PrfClientResult::Absent,
            prf::inspect_authentication_response,
        );
        // PRF on the response is only meaningful for credentials that
        // were registered as PRF-capable. If the stored credential is
        // not PRF-capable, ignore any incidental PRF block.
        let prf_supported = stored.prf_supported && prf_result.was_honored();

        Ok(AuthenticationOutcome {
            credential_id,
            new_sign_count,
            user_verified: result.user_verified(),
            prf_supported,
            needs_update: result.needs_update(),
        })
    }
}

// ---------------------------------------------------------------------------
// Error mapping
// ---------------------------------------------------------------------------

/// Maps a webauthn-rs registration error onto our [`WebAuthnError`]
/// taxonomy.
fn map_webauthn_register_error(err: webauthn_rs::prelude::WebauthnError) -> WebAuthnError {
    use webauthn_rs::prelude::WebauthnError as W;
    match err {
        W::InvalidRPOrigin => WebAuthnError::origin_mismatch(),
        W::InvalidRPIDHash => WebAuthnError::rp_id_mismatch(),
        W::MismatchedChallenge => WebAuthnError::challenge_mismatch(),
        // Both the "user not verified" and "user not present" gestures map to
        // one variant: the taxonomy intentionally does not distinguish them
        // (the wire response is opaque either way), and "the required user
        // gesture was absent" is the actionable cause for both.
        W::UserNotVerified | W::UserNotPresent => WebAuthnError::user_verification_failed(),
        other => WebAuthnError::attestation_failed(other.to_string()),
    }
}

/// Maps a webauthn-rs authentication error onto our [`WebAuthnError`]
/// taxonomy.
fn map_webauthn_auth_error(err: webauthn_rs::prelude::WebauthnError) -> WebAuthnError {
    use webauthn_rs::prelude::WebauthnError as W;
    match err {
        W::InvalidRPOrigin => WebAuthnError::origin_mismatch(),
        W::InvalidRPIDHash => WebAuthnError::rp_id_mismatch(),
        W::MismatchedChallenge => WebAuthnError::challenge_mismatch(),
        // Both the "user not verified" and "user not present" gestures map to
        // one variant: the taxonomy intentionally does not distinguish them
        // (the wire response is opaque either way), and "the required user
        // gesture was absent" is the actionable cause for both.
        W::UserNotVerified | W::UserNotPresent => WebAuthnError::user_verification_failed(),
        W::CredentialNotFound => WebAuthnError::credential_not_found(),
        // webauthn-rs flags counter rollback as `CredentialPossibleCompromise`
        // (see core::error.rs). Our taxonomy folds that into `sign_count_rollback`
        // since it is the precipitating cause.
        W::CredentialPossibleCompromise => WebAuthnError::sign_count_rollback(),
        other => WebAuthnError::attestation_failed(other.to_string()),
    }
}

// ---------------------------------------------------------------------------
// PRF extension splicing
// ---------------------------------------------------------------------------

/// Merges a `prf` extension block under `publicKey.extensions.prf` of
/// the supplied challenge JSON.
///
/// Returns a clone of `challenge_json` with the merge applied. If
/// `prf_extension_json` is `None`, the clone is returned unchanged. The
/// function is pure and idempotent: it never mutates the input,
/// preserves any pre-existing keys under `publicKey.extensions` (so a
/// future `webauthn-rs` release that puts other extensions there isn't
/// clobbered), and overwrites only the `prf` key when PRF is supplied.
///
/// The defensive shape (clone, mutate, return) is the on-purpose trade
/// for keeping the accessor return-by-value friendly and the merge
/// behaviour locally provable in a single unit test.
fn merge_prf_extension(challenge_json: &Value, prf_extension_json: Option<&Value>) -> Value {
    let mut merged = challenge_json.clone();
    let Some(prf) = prf_extension_json else {
        return merged;
    };

    // Walk down `publicKey.extensions`, creating objects as needed.
    // The webauthn-rs challenge JSON always wraps options under
    // `publicKey`, so the top-level shape is `{ "publicKey": { ... } }`.
    let Some(root) = merged.as_object_mut() else {
        return merged;
    };

    let public_key = root
        .entry("publicKey")
        .or_insert_with(|| Value::Object(serde_json::Map::new()));
    let Some(public_key) = public_key.as_object_mut() else {
        return merged;
    };

    let extensions = public_key
        .entry("extensions")
        .or_insert_with(|| Value::Object(serde_json::Map::new()));
    let Some(extensions) = extensions.as_object_mut() else {
        return merged;
    };

    extensions.insert("prf".to_owned(), prf.clone());
    merged
}

// ---------------------------------------------------------------------------
// Passkey metadata recovery
// ---------------------------------------------------------------------------

/// Internal: enforces the `WebAuthn` §7.2 step 21 signature-counter rule.
///
/// Accepts the assertion iff the counter has not rolled back:
///
/// * if the authenticator reports a non-zero counter, `new` MUST be
///   strictly greater than `stored`;
/// * a `new` of zero is only acceptable when `stored` is also zero (an
///   authenticator that does not implement a counter — common for platform
///   passkeys); a zero `new` after a non-zero `stored` is a rollback.
///
/// Factored out as a free function so the four quadrants of the decision
/// can be unit-tested without constructing a `Passkey`.
fn check_sign_count(new: u32, stored: u32) -> Result<(), WebAuthnError> {
    let rollback = (new != 0 && new <= stored) || (new == 0 && stored != 0);
    if rollback {
        return Err(WebAuthnError::sign_count_rollback());
    }
    Ok(())
}

/// Internal: extracts AAGUID, transports, and counter from a freshly
/// minted [`Passkey`] by round-tripping through `serde_json::Value`.
///
/// `webauthn-rs` 0.5 keeps the inner `cred.transports`, the AAGUID
/// (nested under `cred.attestation.metadata`), and the counter behind
/// a `pub(crate)` boundary on [`Passkey`]. The public on-wire shape
/// (which `webauthn-rs` itself documents as stable enough to persist
/// in a database) preserves these fields; we recover them by
/// inspecting the serialised JSON.
///
/// All extraction is defensive: missing fields produce empty defaults
/// rather than panics, the call cannot fail, and a future
/// `webauthn-rs` release that renames or moves a field degrades to
/// "empty metadata" rather than an error or a panic. A regression
/// test (see `tests` module) pins the current shape so any silent
/// degradation surfaces during CI.
///
/// Returned tuple is `(aaguid_bytes, transports, counter)`.
///
/// * `aaguid_bytes` — 16 raw bytes if the attestation carries an
///   AAGUID (Packed, Tpm, etc.); empty `Vec` for self-attesting
///   authenticators or any unrecognised attestation shape.
/// * `transports` — lowercase string list (`["usb", "nfc", ...]`);
///   empty if the authenticator did not assert transports.
/// * `counter` — current authenticator counter (almost always `0` at
///   registration time; non-zero for hardware keys that ship a
///   pre-incremented counter).
fn passkey_metadata(passkey: &Passkey) -> (Vec<u8>, Vec<String>, u32) {
    let Ok(value) = serde_json::to_value(passkey) else {
        return (Vec::new(), Vec::new(), 0);
    };
    metadata_from_value(&value)
}

/// Extracts `(aaguid, transports, counter)` from a `Passkey`'s serialized
/// JSON `Value`. Split out from [`passkey_metadata`] so the extraction
/// logic can be unit-tested directly against a synthetic `Value` (the
/// upstream `Passkey` has no public constructor) — the regression test
/// therefore exercises the production code path, not a copy of it.
fn metadata_from_value(value: &Value) -> (Vec<u8>, Vec<String>, u32) {
    // The Passkey serializes as `{ "cred": { ... } }`.
    let Some(cred) = value.get("cred") else {
        return (Vec::new(), Vec::new(), 0);
    };

    // The WebAuthn signature counter is a u32 by spec, so a value that does
    // not fit can only come from upstream corruption. Degrade to 0 ("no
    // counter implemented") rather than saturating to u32::MAX — saturating
    // would permanently poison the credential, rejecting every later
    // assertion (all `<= u32::MAX`) as a rollback.
    let counter =
        u32::try_from(cred.get("counter").and_then(Value::as_u64).unwrap_or(0)).unwrap_or(0);

    let transports: Vec<String> = cred
        .get("transports")
        .and_then(Value::as_array)
        .map(|arr| {
            arr.iter()
                .filter_map(|v| v.as_str().map(str::to_owned))
                .collect()
        })
        .unwrap_or_default();

    // AAGUID lives under `cred.attestation.metadata.<Variant>.aaguid`
    // when the variant is `Packed` or `Tpm`; the variant is encoded as
    // an externally-tagged enum (the default serde representation for
    // `AttestationMetadata`). When the variant is `None` (no AAGUID),
    // the field is the JSON string `"None"`, not an object.
    let aaguid = cred
        .get("attestation")
        .and_then(|a| a.get("metadata"))
        .and_then(Value::as_object)
        .and_then(|m| m.values().next())
        .and_then(|inner| inner.get("aaguid"))
        .and_then(parse_uuid_from_value)
        .unwrap_or_default();

    (aaguid, transports, counter)
}

/// Parses a UUID from a JSON value, accepting either the canonical
/// hyphenated form (`"550e8400-e29b-41d4-a716-446655440000"`) or a
/// 16-element byte array. Returns the raw 16 bytes on success.
fn parse_uuid_from_value(v: &Value) -> Option<Vec<u8>> {
    if let Some(s) = v.as_str() {
        return Uuid::parse_str(s).ok().map(|u| u.as_bytes().to_vec());
    }
    if let Some(arr) = v.as_array() {
        if arr.len() == 16 {
            let mut bytes = Vec::with_capacity(16);
            for el in arr {
                let b = el.as_u64()?;
                bytes.push(u8::try_from(b).ok()?);
            }
            return Some(bytes);
        }
    }
    None
}

// ---------------------------------------------------------------------------
// Serializable PasskeyCredential surface
// ---------------------------------------------------------------------------

/// Serde-friendly form of [`PasskeyCredential`] for persisting to a
/// database. The embedded `Passkey` is serialised by webauthn-rs.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct StoredPasskey {
    /// Opaque credential ID bytes.
    pub credential_id: Vec<u8>,
    /// webauthn-rs Passkey (CBOR-/JSON-serialisable).
    pub passkey: Passkey,
    /// Denormalised sign-count.
    pub sign_count: u32,
    /// Authenticator transports.
    pub transports: Vec<String>,
    /// Authenticator AAGUID.
    pub aaguid: Vec<u8>,
    /// User-supplied nickname.
    pub label: String,
    /// PRF capability flag.
    pub prf_supported: bool,
    /// PRF salt, present iff `prf_supported`.
    #[serde(default)]
    pub prf_salt: Option<Vec<u8>>,
    /// Created-at timestamp (Unix seconds).
    pub created_at_unix_secs: u64,
    /// Last-used-at timestamp (Unix seconds), if any.
    #[serde(default)]
    pub last_used_at_unix_secs: Option<u64>,
}

impl PasskeyCredential {
    /// Converts this credential into a serializable [`StoredPasskey`].
    #[must_use]
    pub fn to_stored(&self) -> StoredPasskey {
        StoredPasskey {
            credential_id: self.credential_id.clone(),
            passkey: self.passkey.clone(),
            sign_count: self.sign_count,
            transports: self.transports.clone(),
            aaguid: self.aaguid.clone(),
            label: self.label.clone(),
            prf_supported: self.prf_supported,
            prf_salt: self.prf_salt.as_ref().map(|s| s.as_bytes().to_vec()),
            created_at_unix_secs: self.created_at.unix_epoch_secs(),
            last_used_at_unix_secs: self.last_used_at.as_ref().map(Timestamp::unix_epoch_secs),
        }
    }

    /// Reconstructs a credential from its serializable form.
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError::invalid_configuration`] if `prf_salt`
    /// is present with the wrong length.
    pub fn from_stored(stored: StoredPasskey) -> Result<Self, WebAuthnError> {
        let prf_salt = match stored.prf_salt {
            Some(bytes) => Some(PrfSalt::from_bytes(bytes)?),
            None => None,
        };
        Ok(Self {
            credential_id: stored.credential_id,
            passkey: stored.passkey,
            sign_count: stored.sign_count,
            transports: stored.transports,
            aaguid: stored.aaguid,
            label: stored.label,
            prf_supported: stored.prf_supported,
            prf_salt,
            created_at: Timestamp::from_unix_secs(stored.created_at_unix_secs),
            last_used_at: stored.last_used_at_unix_secs.map(Timestamp::from_unix_secs),
        })
    }
}

// ---------------------------------------------------------------------------
// In-module tests
//
// `Passkey` from `webauthn-rs` has no public constructor and a strict
// serde shape, so unit tests in this module cover only the surface
// that does not need a `Passkey` instance:
//
// * `RelyingParty` builder validation.
// * `InMemoryPasskeyStore` empty-state behaviour.
// * `WebAuthnError` taxonomy via the public `is_*` predicates.
//
// Credential / Passkey round-trip tests belong in the Phase-2 server
// integration suite, where a real ceremony can produce real
// credentials. See plan §3, Phase 2 deliverable 9.
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    fn valid_builder() -> RelyingPartyBuilder {
        RelyingParty::builder("example.com", "Example Corp").origin("https://example.com")
    }

    #[test]
    fn rp_builder_happy_path() {
        let rp = valid_builder().build().unwrap();
        assert_eq!(rp.rp_id(), "example.com");
        assert_eq!(rp.rp_name(), "Example Corp");
        assert_eq!(rp.origins(), &["https://example.com".to_owned()]);
    }

    #[test]
    fn rp_builder_rejects_empty_rp_id() {
        let err = RelyingParty::builder("", "x")
            .origin("https://example.com")
            .build()
            .unwrap_err();
        assert!(err.is_invalid_configuration());
        assert!(err.to_string().contains("rp_id is empty"));
    }

    #[test]
    fn rp_builder_rejects_no_origins() {
        let err = RelyingParty::builder("example.com", "x")
            .build()
            .unwrap_err();
        assert!(err.is_invalid_configuration());
        assert!(err.to_string().contains("origin"));
    }

    #[test]
    fn rp_builder_rejects_malformed_origin() {
        let err = RelyingParty::builder("example.com", "x")
            .origin("not a url")
            .build()
            .unwrap_err();
        assert!(err.is_invalid_configuration());
    }

    #[test]
    fn rp_builder_accepts_multiple_origins() {
        let rp = RelyingParty::builder("example.com", "x")
            .origin("https://example.com")
            .origin("https://app.example.com")
            .build()
            .unwrap();
        assert_eq!(rp.origins().len(), 2);
    }

    #[test]
    fn rp_debug_includes_rp_id() {
        let rp = valid_builder().build().unwrap();
        let dbg = format!("{rp:?}");
        assert!(dbg.contains("example.com"));
    }

    #[test]
    fn empty_store_lookups_return_none_and_empty() {
        let store = InMemoryPasskeyStore::new();
        assert!(store.lookup_by_credential_id(b"x").unwrap().is_none());
        assert!(store.lookup_by_user(b"u").unwrap().is_empty());
    }

    #[test]
    fn empty_store_remove_returns_false() {
        let mut store = InMemoryPasskeyStore::new();
        assert!(!store.remove(b"never").unwrap());
    }

    #[test]
    fn empty_store_update_is_silent_noop() {
        let mut store = InMemoryPasskeyStore::new();
        store.update_sign_count(b"never", 7).unwrap();
        store
            .update_last_used(b"never", Timestamp::from_unix_secs(0))
            .unwrap();
        assert!(store.lookup_by_credential_id(b"never").unwrap().is_none());
    }

    #[test]
    fn in_memory_store_debug_reports_size() {
        let store = InMemoryPasskeyStore::new();
        let dbg = format!("{store:?}");
        assert!(dbg.contains("InMemoryPasskeyStore"));
        assert!(dbg.contains("len"));
    }

    #[test]
    fn stub_to_satisfy_pattern_completeness() {
        // Pull stub out to suppress dead-code warnings on the
        // accessors the integration test crate exercises. Kept here
        // as a single non-trivial assertion so the in-module test
        // suite still demonstrates the accessor surface compiles
        // even when no real Passkey is in scope.
        let cred_id: Vec<u8> = b"sentinel".to_vec();
        // We don't construct a PasskeyCredential here (it would
        // require a Passkey). Just exercise the function-pointer
        // surface so any rename in a future refactor breaks the
        // compile.
        let _: fn(&PasskeyCredential) -> &[u8] = PasskeyCredential::credential_id;
        let _: fn(&PasskeyCredential) -> u32 = PasskeyCredential::sign_count;
        let _: fn(&PasskeyCredential) -> bool = PasskeyCredential::prf_supported;
        let _: fn(&PasskeyCredential) -> &str = PasskeyCredential::label;
        let _: fn(&PasskeyCredential) -> Option<&PrfSalt> = PasskeyCredential::prf_salt;
        drop(cred_id);
    }

    // -- merge_prf_extension --------------------------------------------------

    #[test]
    fn merge_prf_extension_returns_unchanged_when_prf_is_none() {
        let challenge = serde_json::json!({
            "publicKey": {
                "challenge": "abc",
                "rp": { "id": "example.com", "name": "Example" },
            }
        });
        let merged = merge_prf_extension(&challenge, None);
        assert_eq!(merged, challenge);
        assert!(merged["publicKey"].get("extensions").is_none());
    }

    #[test]
    fn merge_prf_extension_splices_under_public_key_extensions_prf() {
        let challenge = serde_json::json!({
            "publicKey": {
                "challenge": "abc",
                "rp": { "id": "example.com", "name": "Example" },
            }
        });
        let prf = serde_json::json!({"eval": {"first": "salt-b64"}});
        let merged = merge_prf_extension(&challenge, Some(&prf));
        assert_eq!(
            merged["publicKey"]["extensions"]["prf"]["eval"]["first"],
            "salt-b64"
        );
        // SECURITY: every other field is preserved untouched.
        assert_eq!(merged["publicKey"]["challenge"], "abc");
        assert_eq!(merged["publicKey"]["rp"]["id"], "example.com");
    }

    #[test]
    fn merge_prf_extension_preserves_pre_existing_extensions_keys() {
        // SECURITY: if a future webauthn-rs version already places
        // extensions under `publicKey.extensions` (e.g. credProps), our
        // merge must not clobber them. We only own the `prf` key.
        let challenge = serde_json::json!({
            "publicKey": {
                "challenge": "abc",
                "extensions": {
                    "credProps": true,
                    "appid": "https://example.com/appid",
                },
            }
        });
        let prf = serde_json::json!({"eval": {"first": "salt-b64"}});
        let merged = merge_prf_extension(&challenge, Some(&prf));
        assert_eq!(merged["publicKey"]["extensions"]["credProps"], true);
        assert_eq!(
            merged["publicKey"]["extensions"]["appid"],
            "https://example.com/appid"
        );
        assert_eq!(
            merged["publicKey"]["extensions"]["prf"]["eval"]["first"],
            "salt-b64"
        );
    }

    #[test]
    fn merge_prf_extension_is_idempotent() {
        let challenge = serde_json::json!({
            "publicKey": { "challenge": "abc" }
        });
        let prf = serde_json::json!({"eval": {"first": "salt-b64"}});
        let once = merge_prf_extension(&challenge, Some(&prf));
        let twice = merge_prf_extension(&once, Some(&prf));
        assert_eq!(once, twice, "merge must be idempotent");
    }

    #[test]
    fn merge_prf_extension_creates_extensions_object_when_absent() {
        let challenge = serde_json::json!({"publicKey": {}});
        let prf = serde_json::json!({"eval": {"first": "x"}});
        let merged = merge_prf_extension(&challenge, Some(&prf));
        assert_eq!(
            merged["publicKey"]["extensions"]["prf"]["eval"]["first"],
            "x"
        );
    }

    #[test]
    fn merge_prf_extension_does_not_mutate_input() {
        let challenge = serde_json::json!({"publicKey": {}});
        let before = challenge.clone();
        let prf = serde_json::json!({"eval": {"first": "x"}});
        let _ = merge_prf_extension(&challenge, Some(&prf));
        assert_eq!(challenge, before, "merge must not mutate its input");
    }

    // -- passkey_metadata: round-trip from a synthetic Passkey JSON ----------
    //
    // The Passkey struct has no public constructor in webauthn-rs 0.5,
    // so we craft a JSON shape that matches the upstream `Serialize`
    // impl and round-trip it through `serde_json::from_value`. The
    // shape is pinned by these tests: if a future webauthn-rs release
    // changes its serialised form, the deserialize will fail (loud) or
    // our metadata recovery will degrade to empty values (soft).
    // Either way the breakage surfaces in CI rather than in
    // production.

    fn synthetic_passkey_json(aaguid_uuid: &str, transports: &[&str], counter: u64) -> Value {
        // The actual COSEKey CBOR-based shape varies; the only fields
        // we care about for metadata recovery are `cred_id`, `counter`,
        // `transports`, and `attestation.metadata`. We construct a
        // minimal-but-valid shape and verify the recovery helper
        // reads them off the expected paths. Note: `serde_json::from_value`
        // through to `Passkey` is *not* attempted (Passkey requires
        // every field), so the test instead exercises the helper
        // directly via `metadata_from_value` below.
        serde_json::json!({
            "cred": {
                "cred_id": "Y3JlZGlk",
                "counter": counter,
                "transports": transports,
                "attestation": {
                    "metadata": { "Packed": { "aaguid": aaguid_uuid } }
                }
            }
        })
    }

    // The extraction logic is exercised against the production
    // `metadata_from_value` directly — `Passkey` has no public
    // constructor, so we feed it the synthetic `Value` a `Passkey`
    // would serialize to. This pins the real code path, so an upstream
    // serialization-shape change surfaces in CI.
    use super::metadata_from_value;

    #[test]
    fn passkey_metadata_recovers_aaguid_transports_and_counter() {
        let uuid_str = "550e8400-e29b-41d4-a716-446655440000";
        let json = synthetic_passkey_json(uuid_str, &["usb", "nfc"], 7);
        let (aaguid, transports, counter) = metadata_from_value(&json);

        let expected = Uuid::parse_str(uuid_str).unwrap().as_bytes().to_vec();
        assert_eq!(aaguid, expected, "AAGUID must round-trip through 16 bytes");
        assert_eq!(transports, vec!["usb".to_owned(), "nfc".to_owned()]);
        assert_eq!(counter, 7);
    }

    #[test]
    fn passkey_metadata_handles_missing_attestation_metadata() {
        // No metadata variant (or `None` variant): AAGUID should
        // degrade to empty rather than panic.
        let json = serde_json::json!({
            "cred": {
                "cred_id": "Y3JlZGlk",
                "counter": 0,
                "transports": null,
                "attestation": { "metadata": "None" }
            }
        });
        let (aaguid, transports, counter) = metadata_from_value(&json);
        assert!(aaguid.is_empty());
        assert!(transports.is_empty());
        assert_eq!(counter, 0);
    }

    #[test]
    fn passkey_metadata_handles_completely_missing_fields() {
        // Empty value: every field defaults.
        let json = serde_json::json!({});
        let (aaguid, transports, counter) = metadata_from_value(&json);
        assert!(aaguid.is_empty());
        assert!(transports.is_empty());
        assert_eq!(counter, 0);
    }

    #[test]
    fn passkey_metadata_tolerates_oversized_counter() {
        // SECURITY: a hostile or buggy webauthn-rs release that emits a
        // > u32::MAX counter must not panic, and must degrade to 0 ("no
        // counter") rather than u32::MAX — the latter would poison the
        // credential so every later assertion is rejected as a rollback.
        let json = serde_json::json!({
            "cred": { "counter": u64::MAX }
        });
        let (_, _, counter) = metadata_from_value(&json);
        assert_eq!(counter, 0);
    }

    #[test]
    fn sign_count_advancing_is_accepted() {
        // Strictly greater non-zero counter: normal hardware-key path.
        assert!(check_sign_count(5, 4).is_ok());
    }

    #[test]
    fn sign_count_first_assertion_from_zero_stored_is_accepted() {
        // stored == 0 (registered without a counter), authenticator now
        // reports a non-zero counter: accepted, not a rollback.
        assert!(check_sign_count(5, 0).is_ok());
    }

    #[test]
    fn sign_count_both_zero_is_accepted() {
        // Counter-less authenticator (platform passkey): always zero.
        assert!(check_sign_count(0, 0).is_ok());
    }

    #[test]
    fn sign_count_equal_nonzero_is_rollback() {
        // Replay: counter did not advance.
        let err = check_sign_count(4, 4).unwrap_err();
        assert!(err.is_sign_count_rollback());
    }

    #[test]
    fn sign_count_decreasing_is_rollback() {
        let err = check_sign_count(3, 4).unwrap_err();
        assert!(err.is_sign_count_rollback());
    }

    #[test]
    fn sign_count_zero_after_nonzero_is_rollback() {
        // Authenticator that previously reported a counter now reports 0.
        let err = check_sign_count(0, 4).unwrap_err();
        assert!(err.is_sign_count_rollback());
    }

    #[test]
    fn parse_uuid_accepts_canonical_string() {
        let v = serde_json::json!("550e8400-e29b-41d4-a716-446655440000");
        let bytes = parse_uuid_from_value(&v).unwrap();
        assert_eq!(bytes.len(), 16);
    }

    #[test]
    fn parse_uuid_accepts_byte_array() {
        let bytes: Vec<Value> = (0u8..16).map(|b| Value::from(u64::from(b))).collect();
        let v = Value::Array(bytes);
        let recovered = parse_uuid_from_value(&v).unwrap();
        assert_eq!(recovered, (0u8..16).collect::<Vec<u8>>());
    }

    #[test]
    fn parse_uuid_rejects_unrelated_shape() {
        assert!(parse_uuid_from_value(&serde_json::json!(42)).is_none());
        assert!(parse_uuid_from_value(&serde_json::json!({})).is_none());
        // Wrong-length array.
        assert!(parse_uuid_from_value(&serde_json::json!([1, 2, 3])).is_none());
    }

    // -- InMemoryPasskeyStore: constant-time lookup behaviour ------------------

    #[test]
    fn empty_store_lookup_returns_none_for_short_and_long_inputs() {
        // SECURITY: constant_time_eq returns false immediately on
        // length mismatch, so lookups for arbitrary-length unknown
        // credential IDs return None without panicking.
        let store = InMemoryPasskeyStore::new();
        assert!(store.lookup_by_credential_id(b"").unwrap().is_none());
        assert!(store.lookup_by_credential_id(&[0u8; 64]).unwrap().is_none());
        assert!(
            store
                .lookup_by_credential_id(&[0u8; 1024])
                .unwrap()
                .is_none()
        );
    }

    // -- StoredPasskey serde shape contract -----------------------------------
    //
    // We cannot construct a real `Passkey` in a unit test (no public
    // constructor in webauthn-rs 0.5). What we *can* confirm is that
    // every non-Passkey field on `StoredPasskey` (the fields Phase 2's
    // `SqlxPasskeyStore` will be responsible for writing/reading) is
    // covered by `#[derive(Serialize, Deserialize)]` and round-trips
    // losslessly through JSON when the embedded Passkey is replaced
    // with a serde stand-in.

    #[derive(serde::Serialize, serde::Deserialize, PartialEq, Debug)]
    struct StoredPasskeyShapeProbe {
        credential_id: Vec<u8>,
        // The real `passkey` field is intentionally omitted from this
        // probe: we test the surrounding shape, not the upstream
        // Passkey serialisation (which webauthn-rs owns and pins).
        sign_count: u32,
        transports: Vec<String>,
        aaguid: Vec<u8>,
        label: String,
        prf_supported: bool,
        #[serde(default)]
        prf_salt: Option<Vec<u8>>,
        created_at_unix_secs: u64,
        #[serde(default)]
        last_used_at_unix_secs: Option<u64>,
    }

    #[test]
    fn stored_passkey_shape_round_trips_through_json() {
        let probe = StoredPasskeyShapeProbe {
            credential_id: vec![1, 2, 3, 4],
            sign_count: 9,
            transports: vec!["usb".to_owned(), "hybrid".to_owned()],
            aaguid: vec![0xAA; 16],
            label: "YubiKey 5".to_owned(),
            prf_supported: true,
            prf_salt: Some(vec![0xCC; PRF_SALT_LEN]),
            created_at_unix_secs: 1_700_000_000,
            last_used_at_unix_secs: Some(1_710_000_000),
        };
        let json = serde_json::to_string(&probe).expect("serialise");
        let back: StoredPasskeyShapeProbe = serde_json::from_str(&json).expect("deserialise");
        assert_eq!(probe, back);
    }

    #[test]
    fn stored_passkey_shape_round_trips_with_optional_fields_absent() {
        let probe = StoredPasskeyShapeProbe {
            credential_id: vec![],
            sign_count: 0,
            transports: vec![],
            aaguid: vec![],
            label: String::new(),
            prf_supported: false,
            prf_salt: None,
            created_at_unix_secs: 0,
            last_used_at_unix_secs: None,
        };
        let json = serde_json::to_string(&probe).unwrap();
        let back: StoredPasskeyShapeProbe = serde_json::from_str(&json).unwrap();
        assert_eq!(probe, back);
    }
}