entropy-auth 2026.7.31

//! `WebAuthn` PRF (Pseudo-Random Function) extension helpers.
//!
//! The PRF extension (W3C `WebAuthn` Level 3, formerly the CTAP2.1
//! `hmac-secret` extension on the wire) lets a relying party derive a
//! credential-scoped 32-byte secret on the authenticator. The output
//! never leaves the client, which is what makes it suitable as a
//! key-encryption-key (KEK) for end-to-end-encrypted vault material:
//! the server learns whether PRF was honoured, but never learns the
//! KEK itself.
//!
//! This module covers only the **request-side** wire format and the
//! **response-side** flag detection. The upstream `webauthn-rs` 0.5.x
//! API does not surface PRF directly (it exposes the CTAP2 `hmac-secret`
//! layer beneath), so this module operates at the JSON layer: we splice
//! a `prf` extension object into the challenge JSON before handing it
//! to the user agent, and we read the `prf.enabled` / `prf.results`
//! flag back out of the user agent's response. The cryptographic
//! validation of the surrounding assertion stays inside `webauthn-rs`.
//!
//! # Salt selection
//!
//! Each credential gets its own random 32-byte salt at registration
//! time. The salt is stored by the relying party (the plan's
//! `user_passkeys.prf_salt` column) and is replayed verbatim on every
//! subsequent authentication. Deterministic per-credential salting
//! guarantees the same PRF output across sessions, which is what makes
//! the wrap stable and the unwrap repeatable.
//!
//! The salt is wrapped in a [`PrfSalt`] newtype that:
//!
//! * Holds exactly 32 bytes — the PRF input is fixed-width per spec.
//! * Implements neither `Display` nor an unredacted `Debug`. The salt
//!   itself is not a secret in the cryptographic sense (it's public
//!   per-credential metadata stored alongside the credential), but
//!   keeping it out of logs prevents accidental correlation across
//!   audit trails.

use core::fmt;

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

use crate::crypto::zeroize::Zeroizing;
use crate::crypto::{RandomError, fill_random};
use crate::encoding::base64url_encode;
use crate::webauthn::error::WebAuthnError;

/// Fixed byte length of a PRF salt (per W3C `WebAuthn` L3 §10.1.4).
pub const PRF_SALT_LEN: usize = 32;

// ---------------------------------------------------------------------------
// PrfSalt
// ---------------------------------------------------------------------------

/// A 32-byte PRF salt bound to a single credential.
///
/// Generate one at registration time via [`PrfSalt::generate`], persist
/// it alongside the credential, and replay it on every authentication
/// for that credential. The salt is not a secret in the cryptographic
/// sense, but its `Debug` impl is redacted to keep it out of audit
/// logs.
// `Zeroizing<T>` deliberately omits `PartialEq` to keep secret material
// off non-constant-time comparison paths; the salt itself is not a
// cryptographic secret (it's per-credential public metadata), but
// preserving the omission keeps the type's compare-via-bytes contract
// uniform across the crate.
#[derive(Clone)]
pub struct PrfSalt {
    bytes: Zeroizing<Vec<u8>>,
}

impl PrfSalt {
    /// Generates a new random 32-byte PRF salt.
    ///
    /// # Errors
    ///
    /// Returns the underlying [`RandomError`] if the platform CSPRNG is
    /// unavailable. This is the same failure surface as
    /// [`fill_random`].
    pub fn generate() -> Result<Self, RandomError> {
        let mut buf = vec![0u8; PRF_SALT_LEN];
        fill_random(&mut buf)?;
        Ok(Self {
            bytes: Zeroizing::new(buf),
        })
    }

    /// Constructs a `PrfSalt` from caller-supplied bytes.
    ///
    /// # Errors
    ///
    /// Returns [`WebAuthnError::invalid_configuration`] if `bytes` is
    /// not exactly [`PRF_SALT_LEN`] (32) bytes long.
    pub fn from_bytes(bytes: Vec<u8>) -> Result<Self, WebAuthnError> {
        if bytes.len() != PRF_SALT_LEN {
            return Err(WebAuthnError::invalid_configuration(format!(
                "prf salt must be {PRF_SALT_LEN} bytes, got {}",
                bytes.len()
            )));
        }
        Ok(Self {
            bytes: Zeroizing::new(bytes),
        })
    }

    /// Returns the salt as raw bytes.
    #[must_use]
    #[inline]
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Returns the salt as URL-safe base64 (no padding), the on-wire
    /// encoding required by the `WebAuthn` PRF extension.
    #[must_use]
    #[inline]
    pub fn to_base64url(&self) -> String {
        base64url_encode(&self.bytes)
    }
}

impl fmt::Debug for PrfSalt {
    /// SECURITY: Redacted to keep per-credential salts out of audit logs.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("PrfSalt").finish_non_exhaustive()
    }
}

impl Serialize for PrfSalt {
    /// Serialized as its raw bytes so a credential carrying a PRF salt can
    /// be persisted and replayed on later authentications. The salt is
    /// per-credential metadata, not a cryptographic secret (the PRF output
    /// never leaves the client), so persisting it is intended.
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        self.as_bytes().serialize(serializer)
    }
}

impl<'de> Deserialize<'de> for PrfSalt {
    /// Reconstructed from raw bytes via [`PrfSalt::from_bytes`] (which
    /// enforces the 32-byte length invariant).
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let bytes = Vec::<u8>::deserialize(deserializer)?;
        Self::from_bytes(bytes).map_err(serde::de::Error::custom)
    }
}

// ---------------------------------------------------------------------------
// Request payload (registration)
// ---------------------------------------------------------------------------

/// The PRF extension request payload for a registration ceremony.
///
/// At registration time, we only need to *signal* that the authenticator
/// should generate PRF material for this credential. The client agent
/// (browser or platform API) inspects `prf.eval.first` and decides
/// whether to enroll the credential with PRF capability. `to_json_value`
/// emits the `eval`-only shape, which is what W3C `WebAuthn` L3 specifies for
/// `create()`. (The doc previously claimed both `eval` and `enabled: true`
/// were sent; only `eval` ever was.)
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct PrfRegistrationRequest {
    /// Salt under `eval.first`; encoded as URL-safe base64 (no padding).
    pub eval_first_b64url: String,
}

impl PrfRegistrationRequest {
    /// Builds a registration-side PRF request from a credential salt.
    #[must_use]
    pub fn from_salt(salt: &PrfSalt) -> Self {
        Self {
            eval_first_b64url: salt.to_base64url(),
        }
    }

    /// Renders this request as the JSON object the user agent expects
    /// under `publicKey.extensions.prf`.
    #[must_use]
    pub fn to_json_value(&self) -> Value {
        serde_json::json!({
            "eval": {
                "first": self.eval_first_b64url,
            },
        })
    }
}

// ---------------------------------------------------------------------------
// Request payload (authentication)
// ---------------------------------------------------------------------------

/// The PRF extension request payload for an authentication ceremony.
///
/// At authentication time, the relying party must supply the credential
/// salt under `eval.first`. The user agent invokes the authenticator's
/// hmac-secret, prefixed with the `WebAuthn` PRF context string, and
/// returns the 32-byte output under `clientExtensionResults.prf.results`.
/// That output never reaches the server; only the *presence* of the
/// `results` field is observed, and that is what
/// [`PrfClientResult::was_honored`] checks.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct PrfAuthenticationRequest {
    /// Salt under `eval.first`; encoded as URL-safe base64 (no padding).
    pub eval_first_b64url: String,
}

impl PrfAuthenticationRequest {
    /// Builds an authentication-side PRF request from a credential salt.
    #[must_use]
    pub fn from_salt(salt: &PrfSalt) -> Self {
        Self {
            eval_first_b64url: salt.to_base64url(),
        }
    }

    /// Renders this request as the JSON object the user agent expects
    /// under `publicKey.extensions.prf`.
    #[must_use]
    pub fn to_json_value(&self) -> Value {
        serde_json::json!({
            "eval": {
                "first": self.eval_first_b64url,
            },
        })
    }
}

/// Builds the authentication-side PRF extension value using
/// `evalByCredential` (`WebAuthn` L3): each credential ID maps to its own
/// salt under `first`, so the authenticator derives PRF output with the
/// **correct** salt for whichever credential ends up signing.
///
/// This is required for a user with more than one PRF credential: a single
/// `eval.first` would send one credential's salt for all of them, so signing
/// with a *different* credential would derive a different KEK than the one the
/// data was wrapped under — silently breaking unwrap. Returns `None` if no
/// credential carries a salt.
///
/// `entries` pairs each credential's raw ID with its salt. The returned value
/// is spliced under `publicKey.extensions.prf` by
/// [`merge_prf_extension`](super::merge_prf_extension).
#[must_use]
pub(crate) fn eval_by_credential_value(entries: &[(&[u8], &PrfSalt)]) -> Option<Value> {
    if entries.is_empty() {
        return None;
    }
    let mut by_cred = serde_json::Map::with_capacity(entries.len());
    for (cred_id, salt) in entries {
        by_cred.insert(
            base64url_encode(cred_id),
            serde_json::json!({ "first": salt.to_base64url() }),
        );
    }
    Some(serde_json::json!({ "evalByCredential": by_cred }))
}

// ---------------------------------------------------------------------------
// Response inspection
// ---------------------------------------------------------------------------

/// Result of looking at the PRF section of a `clientExtensionResults`
/// object.
///
/// The relying party never receives the PRF output bytes themselves
/// (that's the whole point of PRF — the secret stays on the client).
/// What it sees is one of three states:
///
/// * [`PrfClientResult::Honored`] — the authenticator generated PRF
///   material and the client used it. For registration, this means the
///   credential is PRF-capable for future authentications; the
///   `user_passkeys.prf_supported` flag is set. For authentication,
///   this means the client successfully derived its KEK.
/// * [`PrfClientResult::Unsupported`] — the authenticator did not
///   honor the extension. The credential is still valid; vault unlock
///   falls back to the master password path.
/// * [`PrfClientResult::Absent`] — the response did not include any
///   `prf` block at all. Treated identically to `Unsupported` by the
///   relying party.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PrfClientResult {
    /// The authenticator generated PRF material.
    Honored,
    /// The authenticator declined the extension.
    Unsupported,
    /// The response carried no `prf` block.
    Absent,
}

impl PrfClientResult {
    /// Returns `true` iff PRF material was successfully generated.
    #[must_use]
    #[inline]
    pub fn was_honored(self) -> bool {
        matches!(self, Self::Honored)
    }
}

// ---------------------------------------------------------------------------
// Wire-format inspection (registration)
// ---------------------------------------------------------------------------

/// Inspects a registration response's `clientExtensionResults` object
/// for the `prf` block.
///
/// The `WebAuthn` L3 spec uses `prf.enabled: bool` at registration time
/// to signal whether the authenticator agreed to generate PRF material.
/// Some browsers also include `prf.results` if the registration ceremony
/// requested `eval` (which we always do for compatibility). Either
/// signal counts as "honored".
#[must_use]
pub fn inspect_registration_response(client_extension_results: &Value) -> PrfClientResult {
    let Some(prf) = client_extension_results.get("prf") else {
        return PrfClientResult::Absent;
    };

    // `enabled` is authoritative when present: `true` means the
    // authenticator agreed to generate PRF material, `false` is an explicit
    // decline that overrides any stray `results` block.
    match prf.get("enabled").and_then(Value::as_bool) {
        Some(true) => return PrfClientResult::Honored,
        Some(false) => return PrfClientResult::Unsupported,
        None => {}
    }

    // `enabled` absent: fall back to a `results` block, which some browsers
    // emit when registration requested `eval`. Require a non-null object —
    // an explicit `results: null` is malformed and must not read as honored.
    if prf.get("results").and_then(Value::as_object).is_some() {
        return PrfClientResult::Honored;
    }

    // `prf` block present but empty or unrecognised shape — treat as
    // unsupported rather than absent to record that the authenticator
    // did acknowledge the extension.
    PrfClientResult::Unsupported
}

// ---------------------------------------------------------------------------
// Wire-format inspection (authentication)
// ---------------------------------------------------------------------------

/// Inspects an authentication response's `clientExtensionResults` for
/// the `prf` block.
///
/// At authentication time the signal is `prf.results.first`: a 32-byte
/// base64url string. If present, the client successfully evaluated the
/// PRF and the relying party can return the stored wrap row. If absent,
/// the relying party returns no wrap and the client falls back to the
/// master password unlock path.
#[must_use]
pub fn inspect_authentication_response(client_extension_results: &Value) -> PrfClientResult {
    let Some(prf) = client_extension_results.get("prf") else {
        return PrfClientResult::Absent;
    };

    // `first` must be a non-null base64url string. An explicit `null` (or any
    // non-string shape) means no PRF output was derived — `Value::get` returns
    // `Some(Value::Null)` for `"first": null`, so a bare `.is_some()` would
    // wrongly read that as honored. Require an actual string.
    if let Some(results) = prf.get("results") {
        if results.get("first").and_then(Value::as_str).is_some() {
            return PrfClientResult::Honored;
        }
    }

    PrfClientResult::Unsupported
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    #[test]
    fn salt_generate_is_correct_length() {
        let salt = PrfSalt::generate().unwrap();
        assert_eq!(salt.as_bytes().len(), PRF_SALT_LEN);
    }

    #[test]
    fn salt_from_bytes_correct_length() {
        let salt = PrfSalt::from_bytes(vec![0u8; PRF_SALT_LEN]).unwrap();
        assert_eq!(salt.as_bytes(), &[0u8; PRF_SALT_LEN]);
    }

    #[test]
    fn salt_from_bytes_rejects_short_input() {
        let err = PrfSalt::from_bytes(vec![0u8; 16]).unwrap_err();
        assert!(err.is_invalid_configuration());
    }

    #[test]
    fn salt_from_bytes_rejects_long_input() {
        let err = PrfSalt::from_bytes(vec![0u8; 64]).unwrap_err();
        assert!(err.is_invalid_configuration());
    }

    #[test]
    fn salt_debug_redacts() {
        let salt = PrfSalt::from_bytes(vec![0xAB; PRF_SALT_LEN]).unwrap();
        let dbg = format!("{salt:?}");
        assert!(dbg.contains("PrfSalt"));
        // Hex of 0xAB
        assert!(!dbg.contains("AB"));
        assert!(!dbg.contains("ab"));
    }

    #[test]
    fn salt_base64url_round_trip_stable() {
        let bytes: Vec<u8> = (0u8..32).collect();
        let salt = PrfSalt::from_bytes(bytes.clone()).unwrap();
        let s1 = salt.to_base64url();
        let s2 = salt.to_base64url();
        assert_eq!(s1, s2);
        // No padding, URL-safe alphabet.
        assert!(!s1.contains('='));
        assert!(!s1.contains('+'));
        assert!(!s1.contains('/'));
    }

    #[test]
    fn prf_client_result_was_honored() {
        assert!(PrfClientResult::Honored.was_honored());
        assert!(!PrfClientResult::Unsupported.was_honored());
        assert!(!PrfClientResult::Absent.was_honored());
    }

    #[test]
    fn registration_request_to_json_value_shape() {
        let salt = PrfSalt::from_bytes(vec![1u8; PRF_SALT_LEN]).unwrap();
        let req = PrfRegistrationRequest::from_salt(&salt);
        let v = req.to_json_value();
        assert_eq!(v["eval"]["first"], salt.to_base64url());
    }

    #[test]
    fn authentication_request_to_json_value_shape() {
        let salt = PrfSalt::from_bytes(vec![2u8; PRF_SALT_LEN]).unwrap();
        let req = PrfAuthenticationRequest::from_salt(&salt);
        let v = req.to_json_value();
        assert_eq!(v["eval"]["first"], salt.to_base64url());
    }

    #[test]
    fn inspect_registration_response_enabled_true() {
        let v = serde_json::json!({"prf": {"enabled": true}});
        assert_eq!(inspect_registration_response(&v), PrfClientResult::Honored);
    }

    #[test]
    fn inspect_registration_response_results_present() {
        let v = serde_json::json!({"prf": {"results": {"first": "AAAA"}}});
        assert_eq!(inspect_registration_response(&v), PrfClientResult::Honored);
    }

    #[test]
    fn inspect_registration_response_enabled_false_overrides_results() {
        // `enabled: false` is an authoritative decline at registration and
        // must win even if a stray `results` block is also present.
        let v = serde_json::json!({"prf": {"enabled": false, "results": {"first": "AAAA"}}});
        assert_eq!(
            inspect_registration_response(&v),
            PrfClientResult::Unsupported
        );
    }

    #[test]
    fn inspect_registration_response_enabled_false() {
        let v = serde_json::json!({"prf": {"enabled": false}});
        assert_eq!(
            inspect_registration_response(&v),
            PrfClientResult::Unsupported
        );
    }

    #[test]
    fn inspect_registration_response_absent() {
        let v = serde_json::json!({});
        assert_eq!(inspect_registration_response(&v), PrfClientResult::Absent);
    }

    #[test]
    fn inspect_authentication_response_results_first_present() {
        let v = serde_json::json!({"prf": {"results": {"first": "AAAA"}}});
        assert_eq!(
            inspect_authentication_response(&v),
            PrfClientResult::Honored
        );
    }

    #[test]
    fn inspect_authentication_response_no_results() {
        let v = serde_json::json!({"prf": {}});
        assert_eq!(
            inspect_authentication_response(&v),
            PrfClientResult::Unsupported
        );
    }

    #[test]
    fn inspect_authentication_response_absent() {
        let v = serde_json::json!({});
        assert_eq!(inspect_authentication_response(&v), PrfClientResult::Absent);
    }

    #[test]
    fn inspect_authentication_response_first_null_is_not_honored() {
        // `serde_json::Value::get` returns `Some(Value::Null)` for an explicit
        // `null`; a bare `.is_some()` would wrongly treat that as honored.
        let v = serde_json::json!({"prf": {"results": {"first": null}}});
        assert_eq!(
            inspect_authentication_response(&v),
            PrfClientResult::Unsupported
        );
    }

    #[test]
    fn inspect_authentication_response_first_non_string_is_not_honored() {
        let v = serde_json::json!({"prf": {"results": {"first": 123}}});
        assert_eq!(
            inspect_authentication_response(&v),
            PrfClientResult::Unsupported
        );
    }

    #[test]
    fn eval_by_credential_maps_each_credential_to_its_own_salt() {
        let salt_a = PrfSalt::from_bytes(vec![0xAAu8; PRF_SALT_LEN]).unwrap();
        let salt_b = PrfSalt::from_bytes(vec![0xBBu8; PRF_SALT_LEN]).unwrap();
        let cred_a: &[u8] = b"cred-a";
        let cred_b: &[u8] = b"cred-b";

        let v = eval_by_credential_value(&[(cred_a, &salt_a), (cred_b, &salt_b)]).unwrap();
        let by_cred = v
            .get("evalByCredential")
            .and_then(Value::as_object)
            .unwrap();

        // One entry per credential, keyed by base64url(credential_id), each
        // carrying its OWN salt under `first`.
        assert_eq!(by_cred.len(), 2);
        let key_a = crate::encoding::base64url_encode(cred_a);
        let key_b = crate::encoding::base64url_encode(cred_b);
        assert_eq!(
            by_cred[&key_a]["first"].as_str().unwrap(),
            salt_a.to_base64url()
        );
        assert_eq!(
            by_cred[&key_b]["first"].as_str().unwrap(),
            salt_b.to_base64url()
        );
        assert_ne!(salt_a.to_base64url(), salt_b.to_base64url());
    }

    #[test]
    fn eval_by_credential_empty_is_none() {
        assert!(eval_by_credential_value(&[]).is_none());
    }

    #[test]
    fn inspect_registration_response_results_null_is_not_honored() {
        // `enabled` absent and `results: null` is a malformed shape — it must
        // not read as honored.
        let v = serde_json::json!({"prf": {"results": null}});
        assert_eq!(
            inspect_registration_response(&v),
            PrfClientResult::Unsupported
        );
    }

    #[test]
    fn salt_determinism_same_input_same_output() {
        // Same input bytes must always produce the same wire-encoded
        // form. This is the property the consumer relies on to make
        // PRF wrap/unwrap stable across sessions.
        let bytes: Vec<u8> = (0u8..32).map(|i| i.wrapping_mul(7)).collect();
        let a = PrfSalt::from_bytes(bytes.clone()).unwrap();
        let b = PrfSalt::from_bytes(bytes).unwrap();
        assert_eq!(a.to_base64url(), b.to_base64url());
        assert_eq!(a.as_bytes(), b.as_bytes());
    }
}