rustango 0.62.0

//! URL-token handoff for operator-as-superuser impersonation.
//!
//! The operator console and the tenant admin sit on different origins,
//! so the console cannot set a cookie the tenant admin will read. A
//! `Domain=.<apex>` cookie works on real DNS but not on `localhost`,
//! which Chromium treats as a public-suffix TLD. A token in the URL
//! works everywhere.
//!
//! ## The flow
//!
//! 1. The console mints a short-lived token, signed with HMAC-SHA256
//!    over the tenant session secret, holding `op_id`, `slug`, `exp`
//!    and a single-use `jti`.
//! 2. It redirects to
//!    `<scheme>://<sub>.<apex>:<port><handoff_url>?token=<signed>`,
//!    setting no cookie of its own.
//! 3. The tenant admin checks the signature, the expiry, the slug and
//!    that the `jti` is unused. It then sets the usual
//!    `rustango_tenant_session` cookie host-scoped, with no `Domain=`,
//!    and redirects to the admin index.
//!
//! ## Security
//!
//! The signature stops tampering. The signed `slug` is checked against
//! the resolved tenant, so a token cannot be replayed on another
//! tenant. The `jti` goes into [`JtiBlacklist`] on redemption, so a
//! second use gives [`HandoffError::AlreadyUsed`]. The token lives 60
//! seconds; the cookie it produces keeps the normal impersonation TTL.
//!
//! The token does land in browser history. Single use and the short
//! TTL bound that, and the handoff response sends
//! `Referrer-Policy: no-referrer` so it does not leak through
//! `Referer`.
//!
//! [`JtiBlacklist`] is per process. Behind a load balancer, a redeemed
//! token could be replayed against another process inside the TTL. A
//! shared store (Redis `SETNX`, or a `rustango_used_jti` table) would
//! close that. Ended impersonations are kept there too (#2038).

use std::sync::{Arc, OnceLock};

use base64::Engine;
use serde::{Deserialize, Serialize};

use super::session::SessionError;
pub use super::session::{PasswordFingerprint, SessionSecret};

/// Signature domain of this token kind: it never verifies as another kind.
const HANDOFF_DOMAIN_TAG: &[u8] = b"rustango-impersonation-handoff-v1";

/// Token lifetime, 60 seconds. Click, redirect, redeem: nothing real
/// takes longer, and a wider window only helps an attacker.
pub const HANDOFF_TTL_SECS: i64 = 60;

/// Errors decoding or validating a handoff token.
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
#[non_exhaustive]
pub enum HandoffError {
    /// Token shape is wrong (no `.` separator, bad base64, bad JSON).
    #[error("handoff token malformed")]
    Malformed,
    /// HMAC signature didn't verify.
    #[error("handoff token signature invalid")]
    BadSignature,
    /// `exp` is in the past.
    #[error("handoff token expired")]
    Expired,
    /// The `slug` field doesn't match the resolved tenant slug.
    #[error("handoff token bound to a different tenant")]
    WrongTenant,
    /// The `jti` has already been redeemed.
    #[error("handoff token already used")]
    AlreadyUsed,
}

impl From<SessionError> for HandoffError {
    fn from(e: SessionError) -> Self {
        match e {
            SessionError::Malformed => Self::Malformed,
            SessionError::BadSignature => Self::BadSignature,
            SessionError::Expired => Self::Expired,
            SessionError::WrongTenant => Self::WrongTenant,
        }
    }
}

/// Signed payload carried in the `?token=` query parameter.
///
/// The field names are short so the token fits comfortably in a
/// `Location` header: about 150 bytes encoded.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HandoffPayload {
    /// Operator id from `rustango_operators`. Ends up in the
    /// impersonation cookie's `imp` field.
    pub op: i64,
    /// Tenant slug this token was minted for. Checked against the
    /// resolved org, so a leaked URL cannot be used on another tenant.
    pub slug: String,
    /// Org id this token was minted for; checked with the slug. Required:
    /// a token without it fails to parse rather than reading as org 0.
    pub org: i64,
    /// Expiry as Unix seconds.
    pub exp: i64,
    /// Single-use id: 16 random bytes, base64url. Recorded in
    /// [`JtiBlacklist`] on redemption; a second use gives
    /// [`HandoffError::AlreadyUsed`].
    pub jti: String,
    /// The operator's [`PasswordFingerprint`]. Copied into the
    /// impersonation cookie, so an operator password change ends it.
    pub pwf: PasswordFingerprint,
    /// Issued-at, Unix seconds; the impersonation session inherits it (#1855).
    #[serde(default)]
    pub iat: i64,
}

impl HandoffPayload {
    /// Build a fresh payload with a random `jti` and `exp = now + ttl`.
    /// `pwf` is the fingerprint of the operator's current hash.
    #[must_use]
    pub fn new(
        op_id: i64,
        tenant: &crate::tenancy::TenantSlug,
        ttl_secs: i64,
        pwf: PasswordFingerprint,
    ) -> Self {
        let now = chrono::Utc::now().timestamp();
        // From the OS CSPRNG. A guessable jti would let someone who saw
        // one handoff URL predict the next and slip past the
        // single-use check.
        use rand::{rngs::OsRng, RngCore};
        let mut bytes = [0u8; 16];
        OsRng.fill_bytes(&mut bytes[..]);
        let jti = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes);
        Self {
            op: op_id,
            slug: tenant.slug.clone(),
            org: tenant.org_id,
            exp: now + ttl_secs,
            jti,
            pwf,
            iat: now,
        }
    }
}

impl crate::session::Expiring for HandoffPayload {
    fn is_expired_at(&self, now: i64) -> bool {
        now >= self.exp
    }
}

/// Sign and encode a payload as `<b64(json)>.<b64(hmac)>`. It shares the
/// tenant session key but not its tag, so neither verifies as the other.
#[must_use]
pub fn mint(secret: &SessionSecret, payload: &HandoffPayload) -> String {
    crate::session::SealedToken::seal(secret.key(), HANDOFF_DOMAIN_TAG, payload)
}

/// Verify a handoff token, decode it, and check it is bound to
/// `tenant` (slug and org id).
///
/// It does not check the `jti`. The caller does that, so it can
/// `mark_used` in the same step that mints the cookie.
///
/// # Errors
/// See [`HandoffError`].
pub fn decode(
    secret: &SessionSecret,
    tenant: &crate::tenancy::TenantSlug,
    value: &str,
) -> Result<HandoffPayload, HandoffError> {
    let payload: HandoffPayload =
        crate::session::SealedToken::open(secret.key(), HANDOFF_DOMAIN_TAG, value)
            .map_err(SessionError::from)?;
    if !tenant.binds(&payload.slug, payload.org) {
        return Err(HandoffError::WrongTenant);
    }
    Ok(payload)
}

/// Tracks which handoff tokens have been redeemed.
///
/// Storage comes from [`crate::jti_store::JtiStore`]. The default is
/// in-process; pass a shared store to [`Self::with_store`] to make it
/// work across processes.
pub struct JtiBlacklist {
    store: Arc<dyn crate::jti_store::JtiStore>,
}

impl JtiBlacklist {
    /// An in-memory store, fine for one process. Use
    /// [`Self::with_store`] when you run more than one.
    fn new() -> Self {
        Self {
            store: Arc::new(crate::jti_store::InMemoryJtiStore::new()),
        }
    }

    /// Back the blacklist with your own store, e.g. a shared one for a
    /// multi-process deployment.
    #[must_use]
    pub fn with_store(store: Arc<dyn crate::jti_store::JtiStore>) -> Self {
        Self { store }
    }

    /// Process-wide singleton over the in-memory store. Run more than
    /// one process and you want your own [`Self::with_store`] instead,
    /// passed into the redeem path.
    pub fn shared() -> &'static Self {
        static INSTANCE: OnceLock<JtiBlacklist> = OnceLock::new();
        INSTANCE.get_or_init(Self::new)
    }

    /// `true` if the jti was already marked used.
    pub async fn is_used(&self, jti: &str) -> bool {
        self.store.is_used(jti).await
    }

    /// Check and record in one step. Gives `Err(AlreadyUsed)` if the
    /// jti is already there, otherwise stores `(jti, exp)`. The store
    /// prunes expired entries.
    ///
    /// # Errors
    /// [`HandoffError::AlreadyUsed`] when the jti was already redeemed.
    pub async fn mark_used(&self, jti: &str, exp: i64) -> Result<(), HandoffError> {
        if self.store.mark_used(jti, exp).await {
            Ok(())
        } else {
            Err(HandoffError::AlreadyUsed)
        }
    }

    /// Revoke the impersonation session `sid` until its cookie's `exp` (#2038).
    pub async fn end_session(&self, sid: &str, exp: i64) {
        self.store.mark_used(&Self::ended_key(sid), exp).await;
    }

    /// `true` once [`Self::end_session`] revoked `sid`.
    pub async fn session_ended(&self, sid: &str) -> bool {
        self.store.is_used(&Self::ended_key(sid)).await
    }

    /// The `:` keeps it apart from a handoff jti, which is base64url.
    fn ended_key(sid: &str) -> String {
        format!("ended:{sid}")
    }
}

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

    fn key() -> SessionSecret {
        SessionSecret::from_bytes(b"a-test-secret-thirty-two-bytes-x".to_vec())
    }

    fn acme() -> crate::tenancy::TenantSlug {
        crate::tenancy::TenantSlug::new(1, "acme")
    }

    /// A tenant that reuses a purged tenant's slug refuses its handoff tokens.
    #[test]
    fn rejects_token_minted_for_a_purged_tenant_with_the_slug() {
        let secret = key();
        let token = mint(&secret, &payload(60));
        let heir = crate::tenancy::TenantSlug::new(2, "acme");
        assert_eq!(
            decode(&secret, &heir, &token).unwrap_err(),
            HandoffError::WrongTenant,
        );
    }

    /// A token with no `org` fails to parse, so it cannot pass for org 0.
    #[test]
    fn rejects_token_without_an_org() {
        let secret = key();
        let mut json = serde_json::to_value(payload(60)).unwrap();
        json.as_object_mut().unwrap().remove("org");
        let b64 = base64::engine::general_purpose::URL_SAFE_NO_PAD
            .encode(serde_json::to_vec(&json).unwrap());
        let sig = crate::session::sign_tagged(&secret, HANDOFF_DOMAIN_TAG, b64.as_bytes());
        let sig_b64 = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(sig);
        let zero = crate::tenancy::TenantSlug::new(0, "acme");
        assert_eq!(
            decode(&secret, &zero, &format!("{b64}.{sig_b64}")).unwrap_err(),
            HandoffError::Malformed,
        );
    }

    fn payload(ttl: i64) -> HandoffPayload {
        HandoffPayload::new(7, &acme(), ttl, PasswordFingerprint::of(&key(), "$h"))
    }

    #[test]
    fn round_trip_valid_payload() {
        let secret = key();
        let payload = payload(60);
        let token = mint(&secret, &payload);
        let back = decode(&secret, &acme(), &token).unwrap();
        assert_eq!(back, payload);
    }

    #[test]
    fn rejects_token_minted_for_a_different_tenant() {
        let secret = key();
        let payload = payload(60);
        let token = mint(&secret, &payload);
        assert_eq!(
            decode(
                &secret,
                &crate::tenancy::TenantSlug::new(2, "globex"),
                &token
            )
            .unwrap_err(),
            HandoffError::WrongTenant,
        );
    }

    #[test]
    fn rejects_tampered_signature() {
        let secret = key();
        let payload = payload(60);
        let token = mint(&secret, &payload);
        // Flip a byte in the middle of the signature, not the last one.
        // The last base64 char of a 32-byte HMAC has only some valid
        // values, so flipping it can give `Malformed` instead of the
        // `BadSignature` this test is about.
        let mut bytes = token.into_bytes();
        let dot = bytes
            .iter()
            .rposition(|&b| b == b'.')
            .expect("token has `payload.sig` shape");
        let mid_sig = dot + 1 + (bytes.len() - dot - 1) / 2;
        bytes[mid_sig] = if bytes[mid_sig] == b'A' { b'B' } else { b'A' };
        let tampered = String::from_utf8(bytes).unwrap();
        assert_eq!(
            decode(&secret, &acme(), &tampered).unwrap_err(),
            HandoffError::BadSignature,
        );
    }

    #[test]
    fn rejects_token_signed_with_a_different_secret() {
        let s1 = key();
        let s2 = SessionSecret::from_bytes(b"b-other-secret-thirty-two-bytes-x".to_vec());
        let token = mint(&s1, &payload(60));
        assert_eq!(
            decode(&s2, &acme(), &token).unwrap_err(),
            HandoffError::BadSignature,
        );
    }

    #[test]
    fn rejects_expired_token() {
        let secret = key();
        let token = mint(&secret, &payload(-10));
        assert_eq!(
            decode(&secret, &acme(), &token).unwrap_err(),
            HandoffError::Expired,
        );
    }

    #[test]
    fn rejects_malformed_token() {
        let secret = key();
        assert_eq!(
            decode(&secret, &acme(), "not-a-token").unwrap_err(),
            HandoffError::Malformed,
        );
        // A malformed sig segment (non-base64) reports Malformed
        // before any constant-time compare runs.
        assert_eq!(
            decode(&secret, &acme(), "abc.!!!").unwrap_err(),
            HandoffError::Malformed,
        );
    }

    #[test]
    fn jtis_are_unique_across_mints() {
        let p1 = payload(60);
        let p2 = payload(60);
        assert_ne!(p1.jti, p2.jti, "random jti collision is unacceptable");
    }

    #[tokio::test]
    async fn jti_blacklist_first_use_succeeds_second_fails() {
        let bl = JtiBlacklist::new();
        let jti = "abc123";
        let exp = chrono::Utc::now().timestamp() + 60;
        bl.mark_used(jti, exp).await.unwrap();
        assert!(bl.is_used(jti).await);
        assert_eq!(
            bl.mark_used(jti, exp).await.unwrap_err(),
            HandoffError::AlreadyUsed
        );
    }

    #[tokio::test]
    async fn jti_blacklist_with_store_delegates_to_swapped_backend() {
        // v0.47 — proves the multi-instance hook: an Arc<dyn JtiStore>
        // passed via `with_store` is the source of truth, not the
        // default in-memory map. Two JtiBlacklist handles built from
        // the same store share state — that's exactly what a Redis-
        // backed store would give a multi-process deployment.
        use crate::jti_store::{InMemoryJtiStore, JtiStore};
        use std::sync::Arc;
        let shared: Arc<dyn JtiStore> = Arc::new(InMemoryJtiStore::new());
        let bl_a = JtiBlacklist::with_store(Arc::clone(&shared));
        let bl_b = JtiBlacklist::with_store(Arc::clone(&shared));
        let jti = "shared-token";
        let exp = chrono::Utc::now().timestamp() + 60;
        bl_a.mark_used(jti, exp).await.unwrap();
        assert!(
            bl_b.is_used(jti).await,
            "second handle on the shared store must see the mark"
        );
        assert_eq!(
            bl_b.mark_used(jti, exp).await.unwrap_err(),
            HandoffError::AlreadyUsed,
            "single-use guard must hold across handles on the shared store"
        );
    }

    // v0.47 — JTI pruning behaviour moved to the `JtiStore` trait
    // and is covered by `jti_store::tests::expired_entries_are_pruned_on_next_mark`.
    // The duplicate JtiBlacklist-level test reached into `bl.inner`
    // directly which is no longer a field (storage is now an
    // `Arc<dyn JtiStore>`).

    /// `HANDOFF_TTL_SECS` is short by design — long enough for the
    /// browser to redirect, short enough that browser-history leak
    /// is bounded. Pin the value so a future caller can't quietly
    /// bump it to "5 minutes" without thinking about the trade-off.
    #[test]
    fn handoff_ttl_default_is_one_minute() {
        assert_eq!(HANDOFF_TTL_SECS, 60);
    }
}