reddb-io-server 1.24.1

//! Browser credential layer — the hybrid token model (issue #936, PRD
//! #930, ADR 0036 §"Connection security", ADR 0029 §Authorization).
//!
//! A browser SPA cannot safely hold a long-lived bearer credential: any
//! token reachable from JavaScript is exfiltrable by an XSS payload. The
//! hybrid model splits the credential in two:
//!
//!   * a **short-lived access JWT** held only in memory (a JS variable),
//!     presented in the RedWire-over-WSS handshake (ADR 0036) exactly
//!     where native drivers present a bearer/OAuth-JWT, and
//!   * a **long-lived refresh token** delivered as an
//!     `HttpOnly; Secure; SameSite` cookie that JavaScript can never
//!     read. The browser silently mints a fresh access JWT from it at
//!     the `/auth/browser/refresh` endpoint.
//!
//! Both tokens are HS256 JWTs minted and verified by *this* server with
//! a single symmetric secret — RedDB is both issuer and verifier, so the
//! asymmetric RS256/JWKS machinery of [`super::oauth`] (which exists to
//! trust a *foreign* IdP) is unnecessary weight here. The vetted
//! `jsonwebtoken` crate owns signature construction and verification;
//! this module owns the issuer/audience/type/expiry policy on top.
//!
//! ## Why access-token rotation does not tear down in-flight streams
//!
//! ADR 0029 §Authorization makes the bearer token authenticate only the
//! *open* of a stream; an internal, unforwarded **stream lease** bound to
//! the MVCC snapshot pin is the credential consulted for every subsequent
//! chunk. So when a browser's access JWT expires and it mints a new one
//! at `/auth/browser/refresh`, the new token is used for the *next*
//! handshake — the streams already accepted on the live RedWire
//! connection keep flowing under their leases, untouched. The refresh
//! cadence is decoupled from result-set delivery time. This module mints
//! the tokens; that decoupling lives in the stream lease (see
//! `crate::server::output_stream`) and is exercised end-to-end by the
//! issue-#936 integration test.
//!
//! ## What this module deliberately does not do
//!
//! mTLS stays native-only (ADR 0036): browser client certificates are
//! hostile UX, so there is no browser mTLS path here. The access JWT /
//! refresh cookie pair is the browser's sole credential.
//!
//! ## Refresh tokens are revocable
//!
//! Access tokens are deliberately stateless: they live 15 minutes and the
//! cost of validating one must stay a signature check. Refresh tokens are
//! not — they live 30 days, and a purely stateless one cannot be taken
//! back. Logging out, rotating, disabling the account or changing its role
//! would all leave a valid credential in the wild until natural expiry.
//!
//! Every refresh token therefore carries a `jti` recorded in a server-side
//! live-token registry, and [`BrowserTokenAuthority::validate_refresh`]
//! refuses a `jti` the registry does not hold. Rotation removes the old
//! entry as it adds the new one, so a captured cookie stops working the
//! moment the legitimate browser refreshes. The registry is in memory, so a
//! restart invalidates outstanding refresh tokens — the same semantics as
//! the session store, and the safe direction.

use std::collections::{HashMap, HashSet};
use std::sync::{Arc, Mutex};

use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation};

use super::Role;

/// Minimum HS256 secret length. RFC 7518 §3.2 requires a key at least as
/// long as the HMAC output (256 bits / 32 bytes); a shorter key is a
/// silent downgrade of the signature's security, so we reject it at
/// construction rather than mint weakly-keyed tokens.
pub const MIN_SECRET_BYTES: usize = 32;

/// `SameSite` cookie attribute for the refresh cookie. `Strict` is the
/// secure default — the refresh cookie is never attached to a
/// cross-site navigation, which is the cleanest CSRF posture for a
/// same-origin SPA. `Lax`/`None` exist for deployments that serve the
/// SPA from a different site; `None` *requires* `Secure` (enforced in
/// [`BrowserTokenConfig::sanitised`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SameSite {
    Strict,
    Lax,
    None,
}

impl SameSite {
    pub fn as_str(&self) -> &'static str {
        match self {
            SameSite::Strict => "Strict",
            SameSite::Lax => "Lax",
            SameSite::None => "None",
        }
    }
}

/// Configuration for the hybrid-token authority. Secure by default:
/// `Secure` cookies, `SameSite=Strict`, a short access TTL, and an
/// `HttpOnly` refresh cookie.
#[derive(Debug, Clone)]
pub struct BrowserTokenConfig {
    /// HS256 signing/verification secret. Must be ≥ [`MIN_SECRET_BYTES`].
    pub secret: Vec<u8>,
    /// `iss` claim stamped on every token and required on verify.
    pub issuer: String,
    /// `aud` claim stamped on every token and required on verify.
    pub audience: String,
    /// Access-JWT lifetime, seconds. Short by design (default 15 min):
    /// the blast radius of a leaked in-memory access token is one TTL.
    pub access_ttl_secs: i64,
    /// Refresh-cookie lifetime, seconds (default 30 days). Bounds how
    /// long a stolen refresh cookie is useful and sets the cookie's
    /// `Max-Age`.
    pub refresh_ttl_secs: i64,
    /// `Secure` attribute on the refresh cookie. Default true — the
    /// cookie must only ride HTTPS. Tests on a clear-text loopback set
    /// this false explicitly.
    pub cookie_secure: bool,
    /// `SameSite` attribute on the refresh cookie.
    pub same_site: SameSite,
    /// Cookie name. Default `reddb_refresh`.
    pub cookie_name: String,
    /// Cookie `Path` — scopes which requests carry the refresh cookie.
    /// Default `/auth/browser`, so it reaches `refresh`/`logout` but no
    /// other endpoint ever sees it.
    pub cookie_path: String,
}

impl BrowserTokenConfig {
    /// Build a config with secure defaults around an explicit secret.
    pub fn new(secret: impl Into<Vec<u8>>) -> Self {
        Self {
            secret: secret.into(),
            issuer: "reddb-browser".to_string(),
            audience: "reddb-redwire".to_string(),
            access_ttl_secs: 15 * 60,
            refresh_ttl_secs: 30 * 24 * 60 * 60,
            cookie_secure: true,
            same_site: SameSite::Strict,
            cookie_name: "reddb_refresh".to_string(),
            cookie_path: "/auth/browser".to_string(),
        }
    }

    /// Apply cross-field invariants. `SameSite=None` is meaningless
    /// without `Secure` (modern browsers reject it), so we force `Secure`
    /// on rather than mint a cookie the browser will silently drop.
    fn sanitised(mut self) -> Self {
        if self.same_site == SameSite::None {
            self.cookie_secure = true;
        }
        self
    }
}

/// Mint a unique refresh-token id. 128 bits from the OS CSPRNG: the value
/// is a registry key rather than a secret (the JWT signature is what
/// authenticates), but it must not collide across concurrently live tokens.
fn new_token_id() -> String {
    let mut bytes = [0u8; 16];
    crate::crypto::os_random::fill_bytes(&mut bytes)
        .expect("OS CSPRNG unavailable; refusing to mint a refresh token id");
    bytes.iter().map(|b| format!("{b:02x}")).collect()
}

/// The identity carried by a validated browser token.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BrowserIdentity {
    pub username: String,
    pub tenant: Option<String>,
    pub role: Role,
}

/// Reasons a token is refused. Kept distinct so the WS handshake and the
/// refresh endpoint can log *why* without leaking detail to the client.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BrowserTokenError {
    /// Signature, issuer, audience, or structural decode failure. The
    /// string is for server-side logs only.
    Decode(String),
    /// A refresh token was presented where an access token was required,
    /// or vice-versa. A refresh token must never authenticate a session
    /// directly — it only mints access tokens.
    WrongType { expected: TokenType, got: String },
    /// `exp` is at or before now.
    Expired,
    /// `nbf` is in the future.
    NotYetValid,
    /// The embedded `role` claim is not a known [`Role`].
    BadRole(String),
    /// A structurally valid refresh token whose `jti` is no longer live:
    /// the browser logged out, the token was rotated, or every token for
    /// the principal was revoked. Distinct from [`Self::Expired`] so logs
    /// tell "credential withdrawn" apart from "credential aged out".
    Revoked,
}

impl std::fmt::Display for BrowserTokenError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            BrowserTokenError::Decode(m) => write!(f, "token decode failed: {m}"),
            BrowserTokenError::WrongType { expected, got } => {
                write!(
                    f,
                    "wrong token type: expected {}, got {got:?}",
                    expected.as_str()
                )
            }
            BrowserTokenError::Expired => write!(f, "token expired"),
            BrowserTokenError::NotYetValid => write!(f, "token not yet valid"),
            BrowserTokenError::BadRole(r) => write!(f, "token carries unknown role {r:?}"),
            BrowserTokenError::Revoked => write!(f, "refresh token has been revoked"),
        }
    }
}

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

/// Which leg of the hybrid pair a token is. Stamped into the `typ` claim
/// and checked on verify so a refresh token can never be replayed as a
/// session credential (and an access token can never be replayed at the
/// refresh endpoint).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TokenType {
    Access,
    Refresh,
}

impl TokenType {
    pub fn as_str(&self) -> &'static str {
        match self {
            TokenType::Access => "access",
            TokenType::Refresh => "refresh",
        }
    }
}

/// JWT claim set. `exp`/`iat` are unix seconds. `typ` discriminates the
/// pair; `tenant` is omitted entirely when the identity is
/// platform-scoped so the wire form stays minimal.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
struct Claims {
    iss: String,
    aud: String,
    sub: String,
    exp: i64,
    iat: i64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    nbf: Option<i64>,
    typ: String,
    role: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    tenant: Option<String>,
    /// Unique token id. Present on refresh tokens, which are tracked in the
    /// live-token registry; absent on access tokens, which are stateless.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    jti: Option<String>,
}

/// The pair returned to the browser by a successful login / refresh: the
/// access JWT (held in memory) and the refresh JWT (set as a cookie).
#[derive(Debug, Clone)]
pub struct IssuedTokens {
    pub access_token: String,
    /// Seconds until the access token expires — the SPA schedules its
    /// silent refresh a little before this.
    pub access_expires_in: i64,
    pub refresh_token: String,
}

/// Mints and verifies the hybrid-token pair for the browser credential
/// layer. Cheap to clone the `Arc` the runtime holds; the keys inside are
/// derived once at construction.
pub struct BrowserTokenAuthority {
    config: BrowserTokenConfig,
    encoding: EncodingKey,
    decoding: DecodingKey,
    /// Live refresh tokens: `jti` -> the identity it was minted for. An
    /// allowlist rather than a revocation list, so anything the server does
    /// not remember is refused — a restart or an evicted entry fails closed.
    live_refresh: Arc<Mutex<HashMap<String, RefreshOwner>>>,
}

/// Who a live refresh token belongs to, so every token for a principal can
/// be revoked at once when the account is disabled or its role changes.
#[derive(Debug, Clone, PartialEq, Eq)]
struct RefreshOwner {
    username: String,
    tenant: Option<String>,
}

impl std::fmt::Debug for BrowserTokenAuthority {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Never render the keys.
        f.debug_struct("BrowserTokenAuthority")
            .field("issuer", &self.config.issuer)
            .field("audience", &self.config.audience)
            .field("access_ttl_secs", &self.config.access_ttl_secs)
            .field("refresh_ttl_secs", &self.config.refresh_ttl_secs)
            .finish_non_exhaustive()
    }
}

impl BrowserTokenAuthority {
    /// Construct an authority. Fails if the secret is shorter than
    /// [`MIN_SECRET_BYTES`] — a weak key is rejected loudly rather than
    /// silently weakening every token.
    pub fn new(config: BrowserTokenConfig) -> Result<Self, String> {
        if config.secret.len() < MIN_SECRET_BYTES {
            return Err(format!(
                "browser-token secret must be at least {MIN_SECRET_BYTES} bytes, got {}",
                config.secret.len()
            ));
        }
        let config = config.sanitised();
        let encoding = EncodingKey::from_secret(&config.secret);
        let decoding = DecodingKey::from_secret(&config.secret);
        Ok(Self {
            config,
            encoding,
            decoding,
            live_refresh: Arc::new(Mutex::new(HashMap::new())),
        })
    }

    pub fn access_ttl_secs(&self) -> i64 {
        self.config.access_ttl_secs
    }

    pub fn cookie_name(&self) -> &str {
        &self.config.cookie_name
    }

    /// Mint an access + refresh pair for an authenticated identity at
    /// `now` (unix seconds). Used by `/auth/browser/login`.
    pub fn issue(&self, identity: &BrowserIdentity, now: i64) -> Result<IssuedTokens, String> {
        let access_token = self.encode(
            identity,
            TokenType::Access,
            now,
            self.config.access_ttl_secs,
        )?;
        let refresh_token = self.encode(
            identity,
            TokenType::Refresh,
            now,
            self.config.refresh_ttl_secs,
        )?;
        Ok(IssuedTokens {
            access_token,
            access_expires_in: self.config.access_ttl_secs,
            refresh_token,
        })
    }

    /// Mint a fresh access token (only) for an identity recovered from a
    /// valid refresh token at `now`. Used by `/auth/browser/refresh`.
    pub fn issue_access(&self, identity: &BrowserIdentity, now: i64) -> Result<String, String> {
        self.encode(
            identity,
            TokenType::Access,
            now,
            self.config.access_ttl_secs,
        )
    }

    fn encode(
        &self,
        identity: &BrowserIdentity,
        typ: TokenType,
        now: i64,
        ttl: i64,
    ) -> Result<String, String> {
        // Only refresh tokens are tracked; an access token is short-lived
        // and validating one must stay a pure signature check.
        let jti = match typ {
            TokenType::Refresh => Some(new_token_id()),
            TokenType::Access => None,
        };
        let claims = Claims {
            iss: self.config.issuer.clone(),
            aud: self.config.audience.clone(),
            sub: identity.username.clone(),
            exp: now + ttl,
            iat: now,
            nbf: Some(now),
            typ: typ.as_str().to_string(),
            role: identity.role.as_str().to_string(),
            tenant: identity.tenant.clone(),
            jti: jti.clone(),
        };
        let token = encode(&Header::new(Algorithm::HS256), &claims, &self.encoding)
            .map_err(|e| format!("encode browser token: {e}"))?;
        if let Some(jti) = jti {
            self.register_refresh(jti, identity);
        }
        Ok(token)
    }

    /// Record a freshly minted refresh token as live.
    fn register_refresh(&self, jti: String, identity: &BrowserIdentity) {
        if let Ok(mut live) = self.live_refresh.lock() {
            live.insert(
                jti,
                RefreshOwner {
                    username: identity.username.clone(),
                    tenant: identity.tenant.clone(),
                },
            );
        }
    }

    /// Revoke one refresh token by the `jti` inside it. Called on logout and
    /// on rotation, so the cookie the browser just replaced stops working
    /// even if it was captured in transit.
    pub fn revoke_refresh_token(&self, token: &str) {
        if let Some(jti) = self.refresh_token_id(token) {
            if let Ok(mut live) = self.live_refresh.lock() {
                live.remove(&jti);
            }
        }
    }

    /// Revoke every refresh token belonging to a principal. Called when the
    /// account is disabled, deleted, or has its role or password changed —
    /// the cases where a 30-day credential must not outlive the decision.
    pub fn revoke_all_for(&self, username: &str, tenant: Option<&str>) {
        if let Ok(mut live) = self.live_refresh.lock() {
            live.retain(|_, owner| {
                !(owner.username == username && owner.tenant.as_deref() == tenant)
            });
        }
    }

    /// Number of live refresh tokens. Test and telemetry helper.
    pub fn live_refresh_count(&self) -> usize {
        self.live_refresh.lock().map(|live| live.len()).unwrap_or(0)
    }

    /// Decode `token` far enough to read its `jti` without enforcing
    /// expiry — revocation must work on a token that is already expired.
    fn refresh_token_id(&self, token: &str) -> Option<String> {
        let mut validation = Validation::new(Algorithm::HS256);
        validation.set_issuer(&[self.config.issuer.as_str()]);
        validation.set_audience(&[self.config.audience.as_str()]);
        validation.validate_exp = false;
        validation.validate_nbf = false;
        validation.required_spec_claims = HashSet::new();
        decode::<Claims>(token, &self.decoding, &validation)
            .ok()
            .and_then(|data| data.claims.jti)
    }

    /// Verify an access token presented in the RedWire WS handshake.
    pub fn validate_access(
        &self,
        token: &str,
        now: i64,
    ) -> Result<BrowserIdentity, BrowserTokenError> {
        self.validate(token, TokenType::Access, now)
    }

    /// Verify a refresh token presented (as a cookie) at the refresh
    /// endpoint.
    pub fn validate_refresh(
        &self,
        token: &str,
        now: i64,
    ) -> Result<BrowserIdentity, BrowserTokenError> {
        self.validate(token, TokenType::Refresh, now)
    }

    /// Signature + issuer + audience are verified by the vetted
    /// `jsonwebtoken` decode; the temporal checks (`exp`/`nbf`) run here
    /// against the injected `now` so the clock is testable — mirroring
    /// the injected-clock pattern of [`super::oauth::OAuthValidator`].
    fn validate(
        &self,
        token: &str,
        expected: TokenType,
        now: i64,
    ) -> Result<BrowserIdentity, BrowserTokenError> {
        let mut validation = Validation::new(Algorithm::HS256);
        validation.set_issuer(&[self.config.issuer.as_str()]);
        validation.set_audience(&[self.config.audience.as_str()]);
        // We own the clock: disable the library's own exp/nbf checks (it
        // reads the wall clock, which tests cannot freeze) and enforce
        // them below against the injected `now`. The signature, `iss`,
        // and `aud` checks the library *does* run are the security core.
        validation.validate_exp = false;
        validation.validate_nbf = false;
        validation.required_spec_claims = HashSet::new();

        let data = decode::<Claims>(token, &self.decoding, &validation)
            .map_err(|e| BrowserTokenError::Decode(e.to_string()))?;
        let claims = data.claims;

        if claims.typ != expected.as_str() {
            return Err(BrowserTokenError::WrongType {
                expected,
                got: claims.typ,
            });
        }
        if now >= claims.exp {
            return Err(BrowserTokenError::Expired);
        }
        if let Some(nbf) = claims.nbf {
            if now < nbf {
                return Err(BrowserTokenError::NotYetValid);
            }
        }
        let role = Role::from_str(&claims.role).ok_or(BrowserTokenError::BadRole(claims.role))?;
        if expected == TokenType::Refresh {
            // A signature-valid refresh token is not enough: it must still be
            // one this server considers live. Logout, rotation and account
            // changes drop the entry, which is what makes those actions
            // actually revoke the 30-day credential.
            let live = claims
                .jti
                .as_ref()
                .and_then(|jti| {
                    self.live_refresh
                        .lock()
                        .ok()
                        .map(|live| live.contains_key(jti))
                })
                .unwrap_or(false);
            if !live {
                return Err(BrowserTokenError::Revoked);
            }
        }
        Ok(BrowserIdentity {
            username: claims.sub,
            tenant: claims.tenant,
            role,
        })
    }

    /// `Set-Cookie` value that installs the refresh token. `HttpOnly`
    /// (unreadable from JS), plus the configured `Secure`/`SameSite`/
    /// `Path` and a `Max-Age` matching the refresh TTL.
    pub fn refresh_cookie(&self, refresh_token: &str) -> String {
        self.build_cookie(refresh_token, self.config.refresh_ttl_secs)
    }

    /// `Set-Cookie` value that clears the refresh cookie (logout). Empty
    /// value, `Max-Age=0`, same attributes so the browser matches and
    /// evicts it.
    pub fn clear_cookie(&self) -> String {
        self.build_cookie("", 0)
    }

    fn build_cookie(&self, value: &str, max_age: i64) -> String {
        let mut cookie = format!(
            "{}={}; HttpOnly; Path={}; Max-Age={}; SameSite={}",
            self.config.cookie_name,
            value,
            self.config.cookie_path,
            max_age,
            self.config.same_site.as_str()
        );
        if self.config.cookie_secure {
            cookie.push_str("; Secure");
        }
        cookie
    }
}

/// Extract a named cookie's value from a raw `Cookie:` request header.
/// Returns the first match. Cookie values are not URL-decoded — JWT
/// compact serialization is already cookie-safe (base64url + `.`).
pub fn cookie_value<'a>(cookie_header: &'a str, name: &str) -> Option<&'a str> {
    cookie_header.split(';').find_map(|pair| {
        let pair = pair.trim();
        let (k, v) = pair.split_once('=')?;
        if k.trim() == name {
            Some(v.trim())
        } else {
            None
        }
    })
}

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

    const NOW: i64 = 1_750_000_000;

    fn authority() -> BrowserTokenAuthority {
        let secret = b"0123456789abcdef0123456789abcdef".to_vec();
        BrowserTokenAuthority::new(BrowserTokenConfig::new(secret)).unwrap()
    }

    fn identity() -> BrowserIdentity {
        BrowserIdentity {
            username: "alice".to_string(),
            tenant: Some("acme".to_string()),
            role: Role::Write,
        }
    }

    #[test]
    fn rejects_short_secret() {
        let err = BrowserTokenAuthority::new(BrowserTokenConfig::new(b"too-short".to_vec()));
        assert!(err.is_err());
    }

    #[test]
    fn issue_then_validate_access_roundtrip() {
        let auth = authority();
        let tokens = auth.issue(&identity(), NOW).unwrap();
        let id = auth
            .validate_access(&tokens.access_token, NOW + 60)
            .unwrap();
        assert_eq!(id, identity());
        assert_eq!(tokens.access_expires_in, 15 * 60);
    }

    #[test]
    fn platform_scoped_identity_has_no_tenant() {
        let auth = authority();
        let id = BrowserIdentity {
            username: "root".to_string(),
            tenant: None,
            role: Role::Admin,
        };
        let tokens = auth.issue(&id, NOW).unwrap();
        let got = auth.validate_access(&tokens.access_token, NOW + 1).unwrap();
        assert_eq!(got.tenant, None);
        assert_eq!(got.role, Role::Admin);
    }

    #[test]
    fn expired_access_token_rejected() {
        let auth = authority();
        let tokens = auth.issue(&identity(), NOW).unwrap();
        // 15-minute TTL; ask at now + 16 minutes.
        let err = auth
            .validate_access(&tokens.access_token, NOW + 16 * 60)
            .unwrap_err();
        assert_eq!(err, BrowserTokenError::Expired);
    }

    #[test]
    fn not_yet_valid_token_rejected() {
        let auth = authority();
        let tokens = auth.issue(&identity(), NOW).unwrap();
        // nbf = NOW; validate at NOW - 10.
        let err = auth
            .validate_access(&tokens.access_token, NOW - 10)
            .unwrap_err();
        assert_eq!(err, BrowserTokenError::NotYetValid);
    }

    #[test]
    fn refresh_token_cannot_authenticate_a_session() {
        // A refresh token presented where an access token is required
        // (the WS handshake) must be refused on type, even though its
        // signature is perfectly valid.
        let auth = authority();
        let tokens = auth.issue(&identity(), NOW).unwrap();
        let err = auth
            .validate_access(&tokens.refresh_token, NOW + 60)
            .unwrap_err();
        assert!(matches!(err, BrowserTokenError::WrongType { .. }));
    }

    #[test]
    fn access_token_cannot_be_used_at_refresh_endpoint() {
        let auth = authority();
        let tokens = auth.issue(&identity(), NOW).unwrap();
        let err = auth
            .validate_refresh(&tokens.access_token, NOW + 60)
            .unwrap_err();
        assert!(matches!(err, BrowserTokenError::WrongType { .. }));
    }

    #[test]
    fn refresh_validates_and_mints_new_access() {
        let auth = authority();
        let tokens = auth.issue(&identity(), NOW).unwrap();
        // Later, the cookie is replayed to mint a new access token.
        let later = NOW + 10 * 60;
        let id = auth.validate_refresh(&tokens.refresh_token, later).unwrap();
        let new_access = auth.issue_access(&id, later).unwrap();
        // The freshly-minted access token is valid well past the
        // original access token's expiry — refresh genuinely extends.
        let got = auth.validate_access(&new_access, NOW + 20 * 60).unwrap();
        assert_eq!(got, identity());
    }

    #[test]
    fn token_signed_by_a_different_secret_is_rejected() {
        let auth = authority();
        let other = BrowserTokenAuthority::new(BrowserTokenConfig::new(
            b"FEDCBA9876543210FEDCBA9876543210".to_vec(),
        ))
        .unwrap();
        let tokens = other.issue(&identity(), NOW).unwrap();
        let err = auth
            .validate_access(&tokens.access_token, NOW + 60)
            .unwrap_err();
        assert!(matches!(err, BrowserTokenError::Decode(_)));
    }

    #[test]
    fn wrong_audience_rejected() {
        let auth = authority();
        let mut cfg = BrowserTokenConfig::new(b"0123456789abcdef0123456789abcdef".to_vec());
        cfg.audience = "someone-else".to_string();
        let other = BrowserTokenAuthority::new(cfg).unwrap();
        let tokens = other.issue(&identity(), NOW).unwrap();
        let err = auth
            .validate_access(&tokens.access_token, NOW + 60)
            .unwrap_err();
        assert!(matches!(err, BrowserTokenError::Decode(_)));
    }

    #[test]
    fn refresh_cookie_carries_security_attributes() {
        let auth = authority();
        let cookie = auth.refresh_cookie("the.jwt.value");
        assert!(cookie.contains("reddb_refresh=the.jwt.value"));
        assert!(cookie.contains("HttpOnly"));
        assert!(cookie.contains("Secure"));
        assert!(cookie.contains("SameSite=Strict"));
        assert!(cookie.contains("Path=/auth/browser"));
        assert!(cookie.contains("Max-Age=2592000"));
    }

    #[test]
    fn clear_cookie_expires_immediately() {
        let auth = authority();
        let cookie = auth.clear_cookie();
        assert!(cookie.contains("reddb_refresh=;"));
        assert!(cookie.contains("Max-Age=0"));
        assert!(cookie.contains("HttpOnly"));
    }

    #[test]
    fn samesite_none_forces_secure() {
        let mut cfg = BrowserTokenConfig::new(b"0123456789abcdef0123456789abcdef".to_vec());
        cfg.same_site = SameSite::None;
        cfg.cookie_secure = false; // should be overridden
        let auth = BrowserTokenAuthority::new(cfg).unwrap();
        let cookie = auth.refresh_cookie("x");
        assert!(cookie.contains("SameSite=None"));
        assert!(cookie.contains("Secure"));
    }

    #[test]
    fn cookie_value_extracts_named_cookie() {
        let header = "other=1; reddb_refresh=abc.def.ghi; theme=dark";
        assert_eq!(cookie_value(header, "reddb_refresh"), Some("abc.def.ghi"));
        assert_eq!(cookie_value(header, "missing"), None);
    }

    #[test]
    fn cookie_value_handles_single_cookie() {
        assert_eq!(
            cookie_value("reddb_refresh=solo", "reddb_refresh"),
            Some("solo")
        );
    }
}