didbot_serve/oauth/

consent.rs

//! The consent seam.
//!
//! `plan/oauth.md`'s hard part: OAuth's `authorize` step assumes a human at a
//! browser, and an agent has none. What stands in for the person is the
//! agent's own daemon: `POST /oauth/par` mints a decision record and a
//! one-time [`ConsentReference`] for it, the daemon reads the decision
//! through `bot.did.listPendingAuthorizations` and answers it with
//! `bot.did.approveAuthorization`, carrying that reference under
//! `Credential::AccountSelf`. The DID doing the approving is therefore the one
//! the presented agent token authenticates as, never a value in the body.
//!
//! What this module builds is everything behind that route:
//! [`ConsentReference`] minting, [`ConsentStore`], and [`confirm`] — the
//! function the route reaches, doing two checks:
//!
//! 1. the reference is live and unused, and
//! 2. the account named in the request is the authenticated agent.
//!
//! **Policy is not one of them.** The sign-in was judged once, at PAR
//! ([`crate::oauth::par`]), and the answer is in the record: a record whose
//! verdict is a denial carries no reference, so there is nothing here to
//! confirm. Evaluating again at this point could only contradict a record
//! that already told the agent `allow`.
//!
//! # The invariant
//!
//! **Approval happens because the named agent confirmed, never because
//! there was nobody to say no.** [`confirm`] takes the authenticated DID as
//! an explicit argument rather than trusting anything in the request body,
//! so a caller cannot self-attest its own identity.

use std::collections::HashMap;
use std::sync::RwLock;

use rand::rngs::OsRng;
use rand::TryRngCore;
use time::{Duration, OffsetDateTime};

use didbot_pds::oauth::ClientAuthKey;

use crate::oauth::dpop_seam::DpopThumbprint;
use crate::oauth::scope::ScopeSet;

/// How long a minted consent reference stays live before it must be reissued.
///
/// Short: this is the window between the headless browser reading the
/// `authorize` page and the agent's confirming tool call landing, not a
/// session lifetime.
pub const CONSENT_TTL: Duration = Duration::minutes(5);

/// Random bytes a reference is drawn from.
const REFERENCE_BYTES: usize = 24;

/// A one-time reference minted when `authorize` is ready for confirmation.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ConsentReference(pub String);

impl ConsentReference {
    fn mint() -> Self {
        let mut bytes = [0u8; REFERENCE_BYTES];
        OsRng
            .try_fill_bytes(&mut bytes)
            .expect("the OS random source is available");
        Self(hex::encode(bytes))
    }
}

/// What a pending consent decision is about.
#[derive(Debug, Clone)]
pub struct PendingConsent {
    /// The `request_uri` this consent will confirm, so [`confirm`] can hand
    /// the caller back to `authorize`'s own PAR-backed request state.
    pub request_uri: String,
    /// The account the pushed request named — `login_hint`, resolved to a
    /// DID by whatever resolves at-identifiers. This is "the account named
    /// in the request" that check 2 compares the stamp against.
    pub did: String,
    /// The client asking, carried through for logging.
    pub client_id: String,
    /// What the decision record granted of the client's request — the set
    /// the agent is shown and approves. The code carries it, and what a
    /// token may do is this as the ceiling grants it at each use — see
    /// `crate::oauth::token`.
    pub granted_scope: ScopeSet,
    /// Where the authorization code must be delivered — checked again at
    /// `token`, per RFC 6749 §4.1.3.
    pub redirect_uri: String,
    /// What the client sent as `state`, to be handed back on the redirect.
    /// A client checks it against what it generated, which is how it tells
    /// its own flow from one somebody else started in its name.
    pub state: Option<String>,
    /// PKCE fields, carried through so `token` can verify `code_verifier`
    /// after the pushed request has expired.
    pub code_challenge: String,
    /// The PKCE method the challenge was computed with; always `S256`.
    pub code_challenge_method: String,
    /// The key a confidential client authenticated with at PAR. The code,
    /// and the login it becomes, stay bound to it. `None` for a public
    /// client.
    pub client_auth_key: Option<ClientAuthKey>,
    /// The thumbprint of the DPoP key the push was signed with, carried to
    /// the code, which is exchanged only under the same key.
    pub dpop_jkt: DpopThumbprint,
    expires_at: OffsetDateTime,
    consumed: bool,
}

/// Why [`confirm`] refused.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ConsentError {
    /// Check 1: the reference does not name a pending consent, has expired,
    /// or has already been used.
    #[error("consent reference is not live: {0}")]
    NotLive(&'static str),
    /// Check 2: the stamped DID is not the account the request named.
    #[error("the stamped identity does not match the account this request is for")]
    IdentityMismatch,
}

/// Where pending consent decisions live between `authorize` minting a
/// reference and a stamped call confirming it.
pub trait ConsentStore: Send + Sync {
    /// Mints and stores a fresh reference for `pending`.
    fn mint(&self, pending: PendingConsent) -> ConsentReference;
    /// Marks the reference consumed and returns what it was pending, if it
    /// was live. Consuming happens whether [`confirm`] goes on to approve or
    /// refuse: a reference is single-use either way, so a caller cannot
    /// retry a refused reference hoping for a different stamped identity.
    fn consume(&self, reference: &ConsentReference) -> Option<PendingConsent>;
    /// Removes a reference [`ConsentStore::mint`] minted moments earlier,
    /// because the decision record it was for was not, after all, stored.
    ///
    /// `oauth::par::push_authorization_request` calls this on both of its
    /// undo branches: [`crate::oauth::consent::begin`] runs before
    /// `DecisionStore::put` — a token has to name the record it approves,
    /// so it cannot be minted after — and a bound that refuses the record
    /// must not leave the reference `begin` already minted for it
    /// behind. Unlike [`ConsentStore::consume`], this does not require the
    /// reference still be live: nothing will ever present a reference for
    /// a push that was undone, live or not, so there is nothing to check.
    fn discard(&self, reference: &ConsentReference);

    /// Drops every reference this store holds for `client_id`, or for
    /// `client_id` on `did` alone. Answers how many went.
    ///
    /// An operator ending an app's logins ends what is in flight too: a
    /// reference left here is one stamped call short of an authorization
    /// code, which is one exchange short of a token.
    fn revoke_client(&self, client_id: &str, did: Option<&str>) -> usize;
}

/// The in-process consent store.
#[derive(Debug, Default)]
pub struct MemoryConsentStore {
    entries: RwLock<HashMap<String, PendingConsent>>,
}

impl MemoryConsentStore {
    /// An empty store.
    pub fn new() -> Self {
        Self::default()
    }

    /// How many references this store still holds — consumed or discarded
    /// ones are gone, expired-but-never-presented ones are gone once
    /// something has called [`ConsentStore::mint`] since they expired. Test
    /// use only, crate-visible so `oauth::par`'s own tests can reach it too.
    #[cfg(test)]
    pub(crate) fn len(&self) -> usize {
        self.entries.read().unwrap_or_else(|p| p.into_inner()).len()
    }
}

impl ConsentStore for MemoryConsentStore {
    fn mint(&self, mut pending: PendingConsent) -> ConsentReference {
        let reference = ConsentReference::mint();
        let now = OffsetDateTime::now_utc();
        pending.expires_at = now + CONSENT_TTL;
        pending.consumed = false;
        let mut entries = self.entries.write().unwrap_or_else(|p| p.into_inner());
        // `consume` and `discard` both remove the one reference they are
        // given, but nothing removes a reference *nobody ever presents* —
        // an abandoned `authorize` page, a decision that expired unread.
        // Swept here, the same way `MemoryDecisionStore::put` sweeps its
        // own map on every write, so this is not the one store in the
        // module an unpresented reference outlives forever.
        entries.retain(|_, pending| !pending.consumed && now < pending.expires_at);
        entries.insert(reference.0.clone(), pending);
        reference
    }

    fn consume(&self, reference: &ConsentReference) -> Option<PendingConsent> {
        let mut entries = self.entries.write().unwrap_or_else(|p| p.into_inner());
        let pending = entries.remove(&reference.0)?;
        if pending.consumed || OffsetDateTime::now_utc() >= pending.expires_at {
            return None;
        }
        Some(pending)
    }

    fn discard(&self, reference: &ConsentReference) {
        self.entries
            .write()
            .unwrap_or_else(|p| p.into_inner())
            .remove(&reference.0);
    }

    fn revoke_client(&self, client_id: &str, did: Option<&str>) -> usize {
        let mut entries = self.entries.write().unwrap_or_else(|p| p.into_inner());
        let before = entries.len();
        entries.retain(|_, pending| {
            !(pending.client_id == client_id && did.is_none_or(|did| pending.did == did))
        });
        before - entries.len()
    }
}

/// Mints a pending consent, for `authorize` to hand back as the reference the
/// agent's confirming tool call must carry.
///
/// `expires_at` and `consumed` on the passed [`PendingConsent`] are ignored
/// and overwritten by the store — callers construct one with any
/// placeholder for both.
#[allow(clippy::too_many_arguments)]
pub fn begin(
    store: &dyn ConsentStore,
    request_uri: String,
    did: String,
    client_id: String,
    granted_scope: ScopeSet,
    redirect_uri: String,
    state: Option<String>,
    code_challenge: String,
    code_challenge_method: String,
    client_auth_key: Option<ClientAuthKey>,
    dpop_jkt: DpopThumbprint,
) -> ConsentReference {
    store.mint(PendingConsent {
        request_uri,
        did,
        client_id,
        granted_scope,
        redirect_uri,
        state,
        code_challenge,
        code_challenge_method,
        client_auth_key,
        dpop_jkt,
        expires_at: OffsetDateTime::now_utc(),
        consumed: true,
    })
}

/// **This is the seam.** A future `PreToolUse`-stamped tool call reaches this
/// function (through whatever HTTP or in-process boundary the harness that
/// drives it uses — not decided here) with `reference` from the tool call's
/// arguments and `stamped_did` from the rewrite, not from the caller.
///
/// Runs the two checks in order, so the error always names the first one
/// that failed:
///
/// 1. `store.consume(reference)` — live and unused.
/// 2. `stamped_did == pending.did` — the account named in the request is the
///    agent that was stamped.
///
/// There is no policy check here, and the reference's own existence is why:
/// a reference is minted only for a decision PAR did not deny.
///
/// Consuming the reference happens as check 1 regardless of what check 2
/// decides: a reference is spent by the attempt, not by success, so a
/// refused attempt cannot be retried with a different claimed identity.
pub fn confirm(
    store: &dyn ConsentStore,
    reference: &ConsentReference,
    stamped_did: &str,
) -> Result<PendingConsent, ConsentError> {
    let pending = store
        .consume(reference)
        .ok_or(ConsentError::NotLive("unknown, expired, or already used"))?;
    if pending.did != stamped_did {
        return Err(ConsentError::IdentityMismatch);
    }
    Ok(pending)
}

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

    fn begin_test(store: &dyn ConsentStore) -> ConsentReference {
        begin(
            store,
            "urn:...:abc".to_owned(),
            "did:web:agent".to_owned(),
            "https://c".to_owned(),
            ScopeSet::parse("atproto").unwrap(),
            "https://c/cb".to_owned(),
            None,
            "challenge".to_owned(),
            "S256".to_owned(),
            None,
            DpopThumbprint("the-pushs-own-key".to_owned()),
        )
    }

    #[test]
    fn a_reference_is_single_use() {
        let store = MemoryConsentStore::new();
        let reference = begin_test(&store);
        assert!(confirm(&store, &reference, "did:web:agent").is_ok());
        let err = confirm(&store, &reference, "did:web:agent").unwrap_err();
        assert!(matches!(err, ConsentError::NotLive(_)));
    }

    #[test]
    fn a_mismatched_stamped_identity_is_refused_and_still_consumes() {
        let store = MemoryConsentStore::new();
        let reference = begin_test(&store);
        let err = confirm(&store, &reference, "did:web:someone-else").unwrap_err();
        assert!(matches!(err, ConsentError::IdentityMismatch));
        // Spent by the attempt, not by success.
        let err2 = confirm(&store, &reference, "did:web:agent").unwrap_err();
        assert!(matches!(err2, ConsentError::NotLive(_)));
    }

    #[test]
    fn an_unknown_reference_is_refused() {
        let store = MemoryConsentStore::new();
        let err = confirm(
            &store,
            &ConsentReference("nope".to_owned()),
            "did:web:agent",
        )
        .unwrap_err();
        assert!(matches!(err, ConsentError::NotLive(_)));
    }

    /// A reference nobody ever presents — an abandoned `authorize` page, a
    /// decision that expired unread — is not removed by anything else in
    /// this module: `consume` only fires on presentation, and `discard`
    /// only on a push `oauth::par` undoes. Without a sweep this is the one
    /// store in the module an entry outlives forever. Constructed directly
    /// rather than through `begin`, which always sets its own fresh expiry
    /// — the point here is a reference `begin` could never mint.
    #[test]
    fn an_unpresented_reference_is_swept_once_it_has_expired() {
        let store = MemoryConsentStore::new();
        let stale = ConsentReference::mint();
        store.entries.write().unwrap().insert(
            stale.0.clone(),
            PendingConsent {
                request_uri: "urn:...:stale".to_owned(),
                did: "did:web:agent".to_owned(),
                client_id: "https://c".to_owned(),
                granted_scope: ScopeSet::parse("atproto").unwrap(),
                redirect_uri: "https://c/cb".to_owned(),
                state: None,
                code_challenge: "challenge".to_owned(),
                code_challenge_method: "S256".to_owned(),
                client_auth_key: None,
                dpop_jkt: DpopThumbprint("the-pushs-own-key".to_owned()),
                expires_at: OffsetDateTime::now_utc() - Duration::seconds(1),
                consumed: false,
            },
        );
        assert_eq!(store.len(), 1);

        // Minting an unrelated, fresh reference is the only trigger a
        // sweep needs — see `MemoryConsentStore::mint`'s own doc.
        let _ = begin_test(&store);
        assert_eq!(
            store.len(),
            1,
            "the stale reference is gone, the fresh one is the only one left"
        );
        assert!(store.entries.read().unwrap().get(&stale.0).is_none());
    }
}