didbot_serve/

operator.rs

//! Signing in as the operator, over atproto OAuth, to reach this server's
//! operator controls.
//!
//! One deployment has one operator, and this server was told which DID that
//! is: `--operator`, held as [`didbot_pds::OperatorRelation`]'s `operator_did` and
//! documented there as configuration. So authenticating an operator is
//! establishing that whoever is asking controls that one DID, and the
//! comparison at the end is a string equality against a value already in
//! this process.
//!
//! # Nothing is granted, and nothing is kept
//!
//! The scope requested is `atproto` and nothing else: no repository access,
//! no write, nothing this server could use even if it wanted to. It is an
//! identity sign-in, and the only thing taken from it is the `sub` the
//! operator's own authorization server put in the token response. The OAuth
//! session is dropped the moment the callback has read that — see
//! [`OperatorAuth::finish`] — so no credential belonging to the operator is
//! ever stored here. That is what keeps `plan/handshake.md`'s rule intact:
//! a server reads who operates it out of configuration and a record in the
//! operator's own repository, and is never handed a secret to check.
//!
//! What this server does issue is its own session, which says only "the
//! browser holding this proved control of the operator DID at some point in
//! the last [`OperatorAuth::session_ttl`]". It is minted here, it never leaves this
//! process, and it is not a credential any other party accepts.
//!
//! # `bot.did.operator` is a different question
//!
//! The operator poll reads a `bot.did.operator` record out of the
//! operator's repository to decide whether this server is *claimed* — the
//! operator's vouch for the server, fetched over the network. Sign-in does
//! not consult it. Putting a remote fetch in front of a button press would
//! make the operator's controls unreachable exactly when their own server is
//! unreachable, and an operator has business here — reading the onboarding
//! surface, throwing the stop — before any claim has landed.

use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use bytes::Bytes;
use jacquard_common::http_client::HttpClient;
use jacquard_common::types::did::Did;
use jacquard_common::types::string::Handle;
use jacquard_common::BosStr;
use jacquard_identity::resolver::{
    DidDocResponse, IdentityError, IdentityResolver, ResolverOptions,
};
use jacquard_identity::JacquardResolver;
use jacquard_oauth::atproto::{atproto_client_metadata, AtprotoClientMetadata};
use jacquard_oauth::authstore::MemoryAuthStore;
use jacquard_oauth::client::OAuthClient;
use jacquard_oauth::dpop::DpopExt;
use jacquard_oauth::resolver::OAuthResolver;
use jacquard_oauth::scopes::Scopes;
use jacquard_oauth::session::ClientData;
use jacquard_oauth::types::{AuthorizeOptions, CallbackParams};
use smol_str::SmolStr;

use crate::auth::constant_time_eq;

/// How long a signed-in browser stays signed in, absent
/// `--operator-session-ttl` or an `[operator]` section.
///
/// One working day, so a sign-in in the morning has not expired by the
/// evening. See `didbot_config::sections::OperatorSection` for the range
/// worth staying inside and why.
pub const DEFAULT_SESSION_TTL: Duration = Duration::from_secs(12 * 60 * 60);

/// The one scope this server ever asks an operator's server for.
const SIGN_IN_SCOPE: &str = "atproto";

/// The path the operator's authorization server redirects back to.
pub const CALLBACK_PATH: &str = "/dashboard/callback";

/// The path this server publishes its client metadata document at. This URL
/// *is* the `client_id`: an atproto client is identified by a document its
/// authorization server can fetch.
pub const CLIENT_METADATA_PATH: &str = "/dashboard/oauth/client-metadata.json";

/// How long a started sign-in has to come back before its pending state is
/// dropped. Generous enough for a consent screen and a password manager,
/// short enough that an abandoned one does not linger.
const PENDING_TTL: Duration = Duration::from_secs(10 * 60);

/// How many sign-ins may be in flight at once.
///
/// [`OperatorAuth::start`] is reachable without a credential — it has to be,
/// since signing in is how a caller gets one — and every call it accepts
/// holds an entry until it is used or ages out. One operator needs one at a
/// time; this is high enough never to be reached by a person and low enough
/// that a flood cannot grow this map without bound. Past it, the oldest
/// entry is dropped rather than the newest refused, so an attacker filling
/// it cannot lock the operator out.
const MAX_PENDING: usize = 64;

/// A browser that proved control of the operator DID.
struct Session {
    /// When this stops being accepted.
    expires: Instant,
    /// The token a mutating request must echo back in a header, so that a
    /// cookie alone — which another origin can make a browser send — is not
    /// enough to throw the stop. See [`OperatorAuth::authorize`].
    csrf: String,
}

/// Every way signing in can fail before a session exists.
#[derive(Debug, thiserror::Error)]
pub enum SignInError {
    /// The handle or DID could not be resolved, or its server would not
    /// start an authorization request.
    #[error("could not start sign-in: {0}")]
    Start(String),
    /// The redirect came back, but the exchange failed.
    #[error("could not finish sign-in: {0}")]
    Finish(String),
    /// The sign-in completed and authenticated somebody who is not the
    /// operator this deployment was started with.
    #[error("signed in as {got}, which is not this deployment's --operator")]
    NotTheOperator {
        /// The DID that actually signed in.
        got: String,
    },
    /// A caller asked to be sent somewhere that is not this machine.
    #[error("{got} is not a loopback address, so this server will not send a session there")]
    NotLoopback {
        /// What was asked for.
        got: String,
    },
}

/// The operator sign-in for one deployment.
pub struct OperatorAuth {
    operator_did: String,
    session_ttl: Duration,
    client: OAuthClient<Resolver, MemoryAuthStore>,
    sessions: Mutex<HashMap<String, Session>>,
    /// Sign-ins started but not yet come back, keyed by the `state` this
    /// server chose. The value is where to send the browser afterwards —
    /// `None` for the dashboard's own flow, and a loopback URL for a CLI
    /// waiting on one. See [`Self::start`].
    pending: Mutex<HashMap<String, (Option<String>, Instant)>>,
}

impl OperatorAuth {
    /// Builds the sign-in for `operator_did`, publishing client metadata at
    /// `base_url` + [`CLIENT_METADATA_PATH`].
    ///
    /// `base_url` is this deployment's own public origin, with no trailing
    /// slash — the authorization server fetches the metadata document from
    /// it and checks the redirect against it, so it has to be the address a
    /// browser actually reached.
    pub fn new(
        operator_did: impl Into<String>,
        base_url: &str,
        session_ttl: Duration,
    ) -> Result<Arc<Self>, String> {
        let operator_did = operator_did.into();
        let client_id = format!("{base_url}{CLIENT_METADATA_PATH}")
            .parse()
            .map_err(|err| format!("{base_url} is not a usable client_id: {err:?}"))?;
        let redirect = format!("{base_url}{CALLBACK_PATH}")
            .parse()
            .map_err(|err| format!("{base_url} is not a usable redirect_uri: {err:?}"))?;
        let scopes: Scopes<SmolStr> = Scopes::new(SmolStr::new_static(SIGN_IN_SCOPE))
            .map_err(|err| format!("the sign-in scope does not parse: {err:?}"))?;
        let metadata = AtprotoClientMetadata::new(vec![redirect], client_id, Some(scopes));
        let client = OAuthClient::new_from_resolver(
            MemoryAuthStore::new(),
            Resolver::new(didbot_http::client()),
            ClientData::new_public(metadata),
        );
        Ok(Arc::new(Self {
            operator_did,
            session_ttl,
            client,
            sessions: Mutex::new(HashMap::new()),
            pending: Mutex::new(HashMap::new()),
        }))
    }

    /// The DID this deployment will accept a sign-in from, and nobody else.
    pub fn operator_did(&self) -> &str {
        &self.operator_did
    }

    /// How long a session this issues stays good for.
    pub fn session_ttl(&self) -> Duration {
        self.session_ttl
    }

    /// The client metadata document, as the JSON served at
    /// [`CLIENT_METADATA_PATH`].
    pub fn client_metadata_document(&self) -> Result<serde_json::Value, String> {
        let metadata = atproto_client_metadata(
            &self.client.registry.client_data.config,
            &self.client.registry.client_data.keyset,
        )
        .map_err(|err| format!("{err:?}"))?;
        serde_json::to_value(metadata).map_err(|err| err.to_string())
    }

    /// Resolves this deployment's operator and returns the URL to send the
    /// browser to.
    ///
    /// The identity is the one `--operator` names and no other, so no
    /// caller picks the host this server resolves and pushes an
    /// authorization request to. What is checked at the far end is still
    /// the `sub` that comes back.
    ///
    /// `cli_redirect` is where to send the browser once the sign-in lands,
    /// for a command-line caller waiting on a loopback address. It is
    /// **refused unless it is loopback**: this
    /// server would otherwise bounce a browser anywhere a link asked it to,
    /// carrying a freshly minted operator session.
    pub async fn start(&self, cli_redirect: Option<&str>) -> Result<String, SignInError> {
        if let Some(redirect) = cli_redirect {
            if !is_loopback_redirect(redirect) {
                return Err(SignInError::NotLoopback {
                    got: redirect.to_owned(),
                });
            }
        }
        let state = random_token();
        let url = self
            .client
            .start_auth(
                self.operator_did(),
                AuthorizeOptions {
                    state: Some(state.clone().into()),
                    ..Default::default()
                },
            )
            .await
            .map_err(|err| SignInError::Start(format!("{err:?}")))?;
        let mut pending = self.pending.lock().unwrap_or_else(|p| p.into_inner());
        let now = Instant::now();
        pending.retain(|_, (_, started)| now.duration_since(*started) < PENDING_TTL);
        while pending.len() >= MAX_PENDING {
            // Oldest first: a flood evicts its own earlier attempts before
            // it can evict a sign-in the operator started a moment ago.
            let oldest = pending
                .iter()
                .min_by_key(|(_, (_, started))| *started)
                .map(|(key, _)| key.clone());
            match oldest {
                Some(key) => {
                    pending.remove(&key);
                }
                None => break,
            }
        }
        pending.insert(state, (cli_redirect.map(str::to_owned), now));
        Ok(url)
    }

    /// Completes the redirect and, if it authenticated the operator, mints a
    /// session. Returns the session token and its CSRF token.
    ///
    /// The OAuth session itself is dropped here: this server wanted the
    /// `sub` and has it.
    pub async fn finish(&self, params: CallbackParams) -> Result<SignedIn, SignInError> {
        // Claimed before the exchange, so a replayed callback cannot mint a
        // second session off one sign-in.
        let cli_redirect = params.state.as_ref().and_then(|state| {
            self.pending
                .lock()
                .unwrap_or_else(|p| p.into_inner())
                .remove(AsRef::<str>::as_ref(state))
                .and_then(|(redirect, _)| redirect)
        });
        let session = self
            .client
            .callback(params)
            .await
            .map_err(|err| SignInError::Finish(format!("{err:?}")))?;
        let (did, _) = session.session_info().await;
        let did = did.to_string();
        // Ends the OAuth session on the operator's own server rather than
        // leaving a grant behind that nothing here will ever use again.
        let _ = session.logout().await;
        if did != self.operator_did {
            return Err(SignInError::NotTheOperator { got: did });
        }
        let mut signed_in = self.mint();
        signed_in.cli_redirect = cli_redirect;
        Ok(signed_in)
    }

    /// Issues a session for a caller already established as the operator.
    ///
    /// `pub(crate)` and no wider: this is the one call that hands out an
    /// operator session without authenticating anybody, so the only callers
    /// are [`Self::finish`], which has just checked the `sub`, and tests:
    /// the dashboard's own, and [`Self::mint_for_tests`]'s.
    pub(crate) fn mint(&self) -> SignedIn {
        let token = random_token();
        let csrf = random_token();
        let mut sessions = self.sessions.lock().unwrap_or_else(|p| p.into_inner());
        let now = Instant::now();
        sessions.retain(|_, held| held.expires > now);
        sessions.insert(
            token.clone(),
            Session {
                expires: now + self.session_ttl,
                csrf: csrf.clone(),
            },
        );
        SignedIn {
            token,
            csrf,
            cli_redirect: None,
        }
    }

    /// A session as if the operator had just signed in, for a test standing
    /// a server up with no authorization server to sign in through.
    #[cfg(feature = "test-support")]
    pub fn mint_for_tests(&self) -> SignedIn {
        self.mint()
    }

    /// Whether `token` is a live session, and if so what CSRF token it
    /// expects. A read may stop here; see [`Self::authorize`].
    pub fn lookup(&self, token: &str) -> Option<String> {
        let mut sessions = self.sessions.lock().unwrap_or_else(|p| p.into_inner());
        let now = Instant::now();
        sessions.retain(|_, held| held.expires > now);
        sessions.get(token).map(|held| held.csrf.clone())
    }

    /// Whether `token` may perform a *mutating* operator action.
    ///
    /// A cookie is sent by the browser on a request another origin caused,
    /// so a live session is necessary and not sufficient: a request that
    /// changes something must also echo the session's own CSRF token, which
    /// only a page served from this origin can have read.
    pub fn authorize(&self, token: &str, presented_csrf: Option<&str>) -> bool {
        let Some(expected) = self.lookup(token) else {
            return false;
        };
        presented_csrf
            .is_some_and(|presented| constant_time_eq(presented.as_bytes(), expected.as_bytes()))
    }

    /// Ends one session.
    pub fn sign_out(&self, token: &str) {
        self.sessions
            .lock()
            .unwrap_or_else(|p| p.into_inner())
            .remove(token);
    }
}

/// What a completed sign-in hands the browser.
pub struct SignedIn {
    /// Goes in the session cookie.
    pub token: String,
    /// Must come back as a header on anything that changes state.
    pub csrf: String,
    /// Where to send the browser next, for a sign-in a command line
    /// started. Always loopback; see [`OperatorAuth::start`].
    pub cli_redirect: Option<String>,
}

/// The identity resolution behind [`OperatorAuth`].
///
/// jacquard-identity builds a `did:web` document URL by pasting the
/// method-specific identifier after `https://`, so `did:web:localhost%3A3415`
/// becomes a request to a host literally named `localhost%3A3415`. atproto
/// permits exactly that shape — a port, with its colon percent-encoded —
/// for `localhost` and nowhere else, "only in testing and development", and
/// [`didbot_identity::did::AccountDid`] decodes it. This puts that answer in
/// front of the library's.
///
/// Only a DID that carries a port takes this path, and only a bare loopback
/// hostname may carry one, so a deployment on a public zone never reaches
/// it. Every such fetch is `https://` like any other.
struct Resolver {
    inner: JacquardResolver<reqwest::Client>,
}

impl Resolver {
    fn new(http: reqwest::Client) -> Self {
        Self {
            inner: JacquardResolver::new(http, ResolverOptions::default()),
        }
    }

    /// Where `did`'s document is served, for a `did:web` this resolver reads
    /// itself rather than handing to the library.
    fn ported_document_url(&self, did: &str) -> Option<String> {
        let parsed = didbot_identity::did::AccountDid::parse(did).ok()?;
        parsed.port().is_some().then(|| parsed.did_json_url())
    }
}

impl HttpClient for Resolver {
    type Error = IdentityError;

    async fn send_http(
        &self,
        request: http::Request<Vec<u8>>,
    ) -> Result<http::Response<Vec<u8>>, Self::Error> {
        self.inner.send_http(request).await
    }
}

impl IdentityResolver for Resolver {
    fn options(&self) -> &ResolverOptions {
        self.inner.options()
    }

    async fn resolve_handle<S: BosStr + Sync>(
        &self,
        handle: &Handle<S>,
    ) -> jacquard_identity::resolver::Result<Did> {
        self.inner.resolve_handle(handle).await
    }

    async fn resolve_did_doc<S: BosStr + Sync>(
        &self,
        did: &Did<S>,
    ) -> jacquard_identity::resolver::Result<DidDocResponse> {
        let Some(url) = self.ported_document_url(did.as_str()) else {
            return self.inner.resolve_did_doc(did).await;
        };
        let request = http::Request::get(&url)
            .body(Vec::new())
            .map_err(IdentityError::url)?;
        let response = self.send_http(request).await?;
        Ok(DidDocResponse {
            status: response.status(),
            buffer: Bytes::from(response.into_body()),
            requested: Did::new_owned(did.as_str()).ok(),
        })
    }
}

impl DpopExt for Resolver {}

impl OAuthResolver for Resolver {}

/// 256 bits from the OS, hex-encoded. Not a password and never stored
/// anywhere but this process's memory, so there is nothing to hash.
fn random_token() -> String {
    use rand::rngs::OsRng;
    use rand::TryRngCore;
    let mut bytes = [0u8; 32];
    OsRng
        .try_fill_bytes(&mut bytes)
        .expect("the OS random source is available");
    hex::encode(bytes)
}

/// Whether `redirect` names a loopback address on the machine running the
/// command — the only place this server will hand a session it just minted.
///
/// A command line waiting on `http://127.0.0.1:<port>` is the case this
/// exists for. Anything else is somebody else's address, and sending an
/// operator session to it is the whole of an account takeover, so the test
/// is a allowlist of the three spellings of "here" rather than a search for
/// anything suspicious.
fn is_loopback_redirect(redirect: &str) -> bool {
    let Ok(url) = url::Url::parse(redirect) else {
        return false;
    };
    if url.scheme() != "http" {
        return false;
    }
    matches!(
        url.host_str(),
        Some("127.0.0.1") | Some("::1") | Some("[::1]") | Some("localhost")
    )
}

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

    /// A `did:web` carrying a port is read by this crate rather than by the
    /// library, which would paste the percent-encoded colon into a
    /// hostname. Everything else goes to the library.
    #[test]
    fn a_did_with_a_port_is_resolved_here_and_nothing_else_is() {
        let resolver = Resolver::new(didbot_http::client());
        assert_eq!(
            resolver
                .ported_document_url("did:web:localhost%3A3400")
                .as_deref(),
            Some("https://localhost:3400/.well-known/did.json")
        );
        assert_eq!(
            resolver.ported_document_url("did:web:kestrel.pds.example"),
            None
        );
        assert_eq!(
            resolver.ported_document_url("did:plc:ewvi7nxzyoun6zhxrhs64oiz"),
            None
        );
    }

    /// The allowlist is the security property: a sign-in that can be
    /// redirected to an attacker's address hands them an operator session,
    /// which is every operator control at once.
    ///
    /// Fails if the scheme check is dropped (the `https://evil` case reads
    /// as a host check alone), or if the host check is loosened to a
    /// substring or suffix match — which is what `127.0.0.1.evil.example`
    /// and `evil.example/127.0.0.1` are here to catch.
    #[test]
    fn only_a_loopback_address_may_receive_a_session() {
        for ok in [
            "http://127.0.0.1:1410/done",
            "http://localhost:9/done",
            "http://[::1]:1410/done",
        ] {
            assert!(is_loopback_redirect(ok), "{ok} is this machine");
        }
        for refused in [
            "https://evil.example/done",
            "http://evil.example/done",
            "http://127.0.0.1.evil.example/done",
            "http://evil.example/127.0.0.1",
            "http://evil.example#127.0.0.1",
            "http://user@evil.example/done",
            "ftp://127.0.0.1/done",
            "not a url at all",
            "",
        ] {
            assert!(
                !is_loopback_redirect(refused),
                "{refused} is not this machine"
            );
        }
    }
}