~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
642 lines · 24.0 KB Raw History
//! Spaces' credentials, as `spec/SPACES-CREDENTIALS.md` says: the server as
//! a user's PDS mints delegation tokens (`getDelegationToken`); as a space
//! host, credentials for the spaces its accounts are the authority of,
//! registering the syncers that ask to be told of the space's updates
//! (`authorizeSpaceSync`); and as a repo host, it verifies the credentials
//! methods are called with (`verify_space_credential`), refusing those an
//! authority revoked (`notifyCredentialsRevoked`).
//!
//! Revocations are kept in `accounts.log`, an entry each, appended under the
//! revocations' lock and answered once on disk; each is forgotten once its
//! time has passed, in memory and when the log is replayed. Delegation
//! tokens and client attestations are spent through `single_use`.
//!
//! What a space is, and who may read it, are the policies' part: this part
//! asks them through `space_authz`'s `Lifecycle` and `Perimeter`. A
//! syncer's registration, and the space's revision, are the notifications'
//! (`space_notify`).

mod attestation;
pub(crate) mod issuers;
pub(crate) mod jwt;
#[cfg(test)]
pub(crate) mod tests;

use crate::oauth::space_scope::SpaceOp;
use crate::single_use::{Held, SingleUse};
use crate::space_authz::{Lifecycle, Perimeter, SpaceState};
use crate::space_notify::{self, Standing};
use crate::{
    Call, Handler, Resp, Service, Shared, Shown, XrpcError, durable, err, invalid, invalid_token,
    opt, read, required,
};
use axum::http::{HeaderMap, header};
use issuers::Unverified;
use jwt::Jwt;
use pds_repo::data::valid_did;
use pds_space::SpaceRef;
use pds_store::Wal;
use serde_json::{Map, Value as Json, json};
use sha2::{Digest, Sha256};
use std::sync::{Mutex, PoisonError};

/// The kind of `accounts.log` entry a revocation is kept in.
pub(crate) const ENTRY: &str = "revoked";

/// Each token's `typ`.
const DELEGATION_TYP: &str = "atproto-space-delegation+jwt";
const CREDENTIAL_TYP: &str = "atproto-space-credential+jwt";

/// How long a delegation token, and a credential, this server signs lives, in seconds.
const DELEGATION_LIFE: u64 = 60;
const CREDENTIAL_LIFE: u64 = 600;
/// No credential lives longer, in seconds.
const MAX_CREDENTIAL_LIFE: f64 = 3600.0;
/// How far clocks may differ, in seconds.
const SKEW: f64 = 5.0;
/// The furthest ahead of now a delegation token's `exp` may be, in seconds.
const MAX_AHEAD: f64 = 3600.0;
/// How long a revocation is kept after it was last received, in seconds: a
/// credential's longest life, and twice the skew.
const REVOCATION_KEPT: u64 = 3610;

/// The `Authorization` scheme a credential is presented with.
const SCHEME: &str = "Atproto-Space-Credential";

const NOTIFY: &str = "com.atproto.space.notifyCredentialsRevoked";

pub(crate) fn handler(nsid: &str) -> Option<Handler> {
    Some(match nsid {
        "com.atproto.space.getDelegationToken" => Handler::Query(get_delegation_token),
        "com.atproto.space.authorizeSpaceSync" => {
            Handler::Procedure(|s, b| Box::pin(authorize_space_sync(s, b)))
        }
        NOTIFY => Handler::Call(|s, call, m| Box::pin(notify_credentials_revoked(s, call, m))),
        _ => return None,
    })
}

/// The credentials' own state: revocations, and issuers' keys read.
#[derive(Default)]
pub(crate) struct Credentials {
    /// Each revoked credential, by the digest of its space and `jti`.
    revoked: Mutex<Held<[u8; 32]>>,
    keys: issuers::Keys,
}

/// A revocation's digest: SHA-256 of the space, a zero byte and the `jti`.
fn revocation(space: &str, jti: &str) -> [u8; 32] {
    Sha256::new()
        .chain_update(space.as_bytes())
        .chain_update([0])
        .chain_update(jti.as_bytes())
        .finalize()
        .into()
}

impl Credentials {
    fn revoked(&self) -> std::sync::MutexGuard<'_, Held<[u8; 32]>> {
        self.revoked.lock().unwrap_or_else(PoisonError::into_inner)
    }

    /// Revoke these credentials of `space` at `now`, until `REVOCATION_KEPT`
    /// after it, logging it in `log`; answers its frame. One the log could
    /// not take is not held.
    pub(crate) fn revoke(
        &self,
        log: &Wal,
        space: &str,
        jtis: &[&str],
        now: u64,
    ) -> std::io::Result<u64> {
        let until = now + REVOCATION_KEPT;
        let mut r = self.revoked();
        r.forget(now);
        let n = log.append(&[
            json!({ "t": ENTRY, "space": space, "credentials": jtis, "until": until }),
        ])?;
        for jti in jtis {
            r.hold(revocation(space, jti), until);
        }
        Ok(n)
    }

    fn is_revoked(&self, space: &str, jti: &str, now: u64) -> bool {
        self.revoked().holds(&revocation(space, jti), now)
    }

    /// Replay an entry `revoke` logged, at `now`: one whose time has passed is forgotten.
    pub fn replay(&self, e: &Json, now: u64) -> Result<(), String> {
        let (Some(space), Some(jtis), Some(until)) = (
            e["space"].as_str(),
            e["credentials"].as_array(),
            e["until"].as_u64(),
        ) else {
            return Err(format!(
                "a revocation with no space, credentials or until: {e}"
            ));
        };
        let jtis: Vec<&str> = jtis
            .iter()
            .map(|j| {
                j.as_str().ok_or_else(|| {
                    format!("a revocation of a credential that is not a string: {e}")
                })
            })
            .collect::<Result<_, _>>()?;
        if until > now {
            let mut r = self.revoked();
            for jti in jtis {
                r.hold(revocation(space, jti), until);
            }
        }
        Ok(())
    }

    /// Every revocation held at `now`, to compare across restarts.
    #[cfg(test)]
    pub fn snapshot(&self, now: u64) -> std::collections::BTreeMap<[u8; 32], u64> {
        self.revoked().snapshot(now)
    }
}

// ---- getDelegationToken ----------------------------------------------------

/// `getDelegationToken`: its `space` is checked before its token, and its
/// token's account's state after it.
fn get_delegation_token(
    s: &Service,
    call: &Call,
    _: &mut Shown,
    p: &Map<String, Json>,
) -> Result<Resp, XrpcError> {
    let space = required(p, "space")?;
    let Some(sr) = SpaceRef::parse(space) else {
        return invalid("space must be a valid space-ref");
    };
    let did = delegating_account(s, call, &sr)?;
    let Some(account) = s.account(&did) else {
        return invalid_token();
    };
    // Deactivated or taken down, as the space repo's writes answer it.
    crate::lifecycle::gate(s, "com.atproto.repo.createRecord", &did)?;
    let now = s.sessions.now();
    let payload = json!({
        "iss": did, "sub": space, "aud": format!("{}#atproto_pds", sr.authority),
        "iat": now, "exp": now + DELEGATION_LIFE, "jti": jwt::new_jti(),
    });
    let token = jwt::sign(&read(&account.store).repo, DELEGATION_TYP, &payload);
    Ok(Resp::Json(json!({ "token": token })))
}

/// The account a delegation token may be minted for: a full session's, not
/// an app password's; or an OAuth session's whose scope grants `read` of
/// the space (`spec/SPACES-CREDENTIALS.md`, "getDelegationToken";
/// `spec/OAUTH-SCOPES.md`, "What each method needs").
fn delegating_account(s: &Service, call: &Call, sr: &SpaceRef) -> Result<String, XrpcError> {
    if matches!(call.bearer, crate::sessions::Bearer::OAuth(_)) {
        let t = crate::sessions::access_token(s, call.bearer)?;
        crate::scopes::may_in(call.bearer, sr, SpaceOp::Read { whole: true })?;
        return Ok(t.did);
    }
    crate::sessions::full_access_token(s, call.bearer).map(|t| t.did)
}

// ---- authorizeSpaceSync ----------------------------------------------------

/// `authorizeSpaceSync`. Answered only once what it spent is on disk, so a
/// token spent stays spent, whatever is answered.
async fn authorize_space_sync(s: Shared, b: Map<String, Json>) -> Result<Resp, XrpcError> {
    let before = s.log.written();
    let out = authorize(&s, &b).await;
    let after = s.log.written();
    if after > before {
        durable(s.log.clone(), after).await?;
    }
    out
}

/// The steps of `authorizeSpaceSync` (`spec/SPACES-CREDENTIALS.md`,
/// "authorizeSpaceSync") after its input is checked against the lexicon,
/// in order.
async fn authorize(s: &Shared, b: &Map<String, Json>) -> Result<Resp, XrpcError> {
    let (space, key) = (required(b, "space")?, required(b, "credentialKey")?);
    let Some(sr) = SpaceRef::parse(space) else {
        return invalid("space must be a valid space-ref");
    };
    // 2. The key the credential is bound to.
    if pds_space::PublicKey::from_did_key(key).is_err() {
        return invalid("credentialKey must be a P-256 did:key");
    }
    let notify = b.get("notify").map(|n| {
        (
            n["endpoint"].as_str().unwrap_or_default(),
            n["token"].as_str().unwrap_or_default(),
        )
    });
    // 3. The authority here and active: a suspended space's authority signs
    // nothing, as `listWriters` refuses it. Nothing more is read.
    let Some(authority) = s.account(&sr.authority) else {
        return space_not_found();
    };
    crate::lifecycle::gate(s, "com.atproto.sync.getRepo", &sr.authority)?;
    // 4. Not deleted, whatever the token, the attestation and `notify`.
    if s.space_state(&sr) == SpaceState::Deleted {
        return space_deleted();
    }
    // 5–6. The user and the client; a token verified is spent from here on.
    let user = match opt(b, "delegationToken").filter(|t| !t.is_empty()) {
        None => None,
        Some(token) => match delegation(s, token).await {
            Some((user, sub)) if sub == space => Some(user),
            _ => return err(400, "InvalidDelegationToken", "Invalid delegation token"),
        },
    };
    let client = match opt(b, "clientAttestation").filter(|t| !t.is_empty()) {
        None => None,
        Some(token) => match attestation::verify(s, token, &sr.authority).await {
            Some(client) => Some(client),
            None => {
                return err(
                    400,
                    "InvalidClientAttestation",
                    "Invalid client attestation",
                );
            }
        },
    };
    // 7. A space the authority created.
    match s.space_state(&sr) {
        SpaceState::Live => {}
        SpaceState::Deleted => return space_deleted(),
        SpaceState::Unknown => return space_not_found(),
    }
    // 8–9. The user perimeter, then the app perimeter: a refusal withdraws
    // the registration `notify` names; a policy that cannot decide does not.
    let reads = s
        .authorize_read(&sr, user.as_deref(), client.as_deref())
        .await
        .or_else(crate::space_authz::Undecided::answer)?;
    if !reads || !s.authorize_app(&sr, client.as_deref()) {
        if let Some((endpoint, token)) = notify {
            space_notify::withdraw(&authority, &sr.uri(), endpoint, token).await?;
        }
        if !reads {
            return space_not_found();
        }
        return err(
            400,
            "AppNotAuthorized",
            "App is not authorized for this space",
        );
    }
    // 10. A registration not yet made, confirmed with its endpoint first.
    if let Some((endpoint, token)) = notify {
        let standing = read(&authority.store).notify.standing(
            &sr.uri(),
            endpoint,
            token,
            s.space_notify.now(),
        );
        match standing {
            Standing::Active | Standing::Lapsed => {}
            Standing::Full => return space_notify::too_many(),
            Standing::New => {
                if !space_notify::confirm(s, space, endpoint, token).await {
                    return err(
                        400,
                        "RegistrationNotConfirmed",
                        "The endpoint did not confirm the registration",
                    );
                }
            }
        }
    }
    // 11. The credential, and the registration made or renewed to lapse
    // when it expires; 12. the space's revision once it is made.
    let now = s.sessions.now();
    let exp = now + CREDENTIAL_LIFE;
    let payload = json!({
        "iss": sr.authority, "sub": space, "cnf": { "kid": key },
        "iat": now, "exp": exp, "jti": jwt::new_jti(),
    });
    let credential = jwt::sign(&read(&authority.store).repo, CREDENTIAL_TYP, &payload);
    let space_rev = match notify {
        Some((endpoint, token)) => {
            space_notify::register(s, &authority, &sr, endpoint, token, exp * 1000).await?
        }
        None => read(&authority.store)
            .authority
            .live(&sr.uri())
            .and_then(space_notify::revision)
            .map(str::to_string),
    };
    let mut out = json!({ "credential": credential });
    if let Some(rev) = space_rev {
        out["spaceRev"] = json!(rev);
    }
    Ok(Resp::Json(out))
}

fn space_deleted<T>() -> Result<T, XrpcError> {
    err(400, "SpaceDeleted", "Space has been deleted")
}

fn space_not_found<T>() -> Result<T, XrpcError> {
    err(400, "SpaceNotFound", "Space not found")
}

/// The user a delegation token speaks for, and the space it names; None if
/// it fails ("Verifying a delegation token"). It is spent if it passes.
async fn delegation(s: &Shared, token: &str) -> Option<(String, String)> {
    let jwt = Jwt::parse(token)?;
    let present = |k: &str| jwt.payload.get(k).is_some_and(|v| !v.is_null());
    let shaped = jwt.signature.is_some()
        && jwt.header("typ") == Some(DELEGATION_TYP)
        && jwt.alg().is_some()
        && jwt.header("kid") == Some("#atproto")
        && ["iss", "sub", "aud"].iter().all(|k| present(k))
        && jwt.claim("jti").is_some_and(|j| !j.is_empty());
    let exp = jwt.number("exp")?;
    let (iss, sub, jti) = (jwt.claim("iss")?, jwt.claim("sub")?, jwt.claim("jti")?);
    let now = s.sessions.now() as f64;
    if !shaped || now - SKEW >= exp || exp - now > MAX_AHEAD || !valid_did(iss) {
        return None;
    }
    let sr = SpaceRef::parse(sub)?;
    if jwt.claim("aud") != Some(format!("{}#atproto_pds", sr.authority).as_str()) {
        return None;
    }
    issuers::verify_issuer(s, iss, &jwt, false).await.ok()?;
    // Kept until 5 seconds after its `exp`, while it could still be taken.
    let until = (exp + SKEW).ceil().clamp(0.0, u64::MAX as f64) as u64;
    s.check_and_record(&format!("delegation {iss} {jti}"), until)
        .then(|| (iss.to_string(), sub.to_string()))
}

// ---- Verifying a credential ------------------------------------------------

/// A credential verified: its space (its `sub`, a `space-ref`), its `jti`,
/// and the key it is bound to (its `cnf.kid`).
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct SpaceCredential {
    pub space: String,
    pub jti: String,
    pub kid: String,
}

/// A header's value, as text.
fn header_text(headers: &HeaderMap, name: impl header::AsHeaderName) -> Option<&str> {
    headers.get(name).and_then(|v| v.to_str().ok())
}

/// Whether a request presents a space credential: its `Authorization`
/// scheme is `Atproto-Space-Credential`, in any case.
pub(crate) fn presents_credential(headers: &HeaderMap) -> bool {
    header_text(headers, header::AUTHORIZATION)
        .and_then(|h| h.split(' ').next())
        .is_some_and(|scheme| scheme.eq_ignore_ascii_case(SCHEME))
}

fn refused<T>(name: &'static str, message: &str) -> Result<T, XrpcError> {
    err(401, name, message)
}

/// Verify the space credential a request presents, for `audience`
/// (`spec/SPACES-CREDENTIALS.md`, "Verifying a credential"): its checks in
/// order, the first that fails answering. The caller then compares the
/// space with the one its request names. The call pays its rate limits
/// once the checks before its issuer's document is read have passed, and
/// before it is read (`spec/LIMITS.md`, "Rate limits").
pub(crate) async fn verify_space_credential(
    s: &Shared,
    call: &Call<'_>,
    audience: &str,
) -> Result<SpaceCredential, XrpcError> {
    let headers = call.headers;
    let Some(authorization) = header_text(headers, header::AUTHORIZATION) else {
        return err(401, "AuthMissing", "Authentication Required");
    };
    let mut words = authorization.split(' ');
    let (Some(scheme), Some(token), None) = (words.next(), words.next(), words.next()) else {
        return invalid_token();
    };
    if token.is_empty() || !scheme.eq_ignore_ascii_case(SCHEME) {
        return invalid_token();
    }
    // 1–3: its form and header.
    let Some(jwt) = Jwt::parse(token).filter(|j| j.signature.is_some()) else {
        return refused("BadJwt", "Malformed credential");
    };
    if jwt.header("typ") != Some(CREDENTIAL_TYP) {
        return refused("BadJwtType", "Invalid credential type");
    }
    if jwt.alg().is_none() || jwt.header("kid") != Some("#atproto") {
        return refused("BadJwt", "Malformed credential header");
    }
    // 4–8: its claims.
    let present = |k: &str| jwt.payload.get(k).is_some_and(|v| !v.is_null() && v != "");
    if !present("iss") {
        return refused("BadJwtIss", "Credential has no iss");
    }
    if !present("sub") {
        return refused("BadJwtSub", "Credential has no sub");
    }
    let Some(exp) = jwt.number("exp") else {
        return refused("BadJwt", "Credential exp is not a number");
    };
    let Some(kid) = jwt
        .payload
        .get("cnf")
        .and_then(|c| c.get("kid"))
        .and_then(Json::as_str)
        .filter(|k| valid_did(k))
    else {
        return refused("BadJwtCnf", "Credential cnf.kid is not a DID");
    };
    let Some(jti) = jwt.claim("jti").filter(|j| !j.is_empty()) else {
        return refused("BadJwt", "Credential has no jti");
    };
    // 9–11: its life.
    let Some(iat) = jwt
        .number("iat")
        .filter(|iat| exp > *iat && exp - iat <= MAX_CREDENTIAL_LIFE)
    else {
        return refused("BadJwt", "Credential lifetime is invalid");
    };
    let now = s.sessions.now() as f64;
    if iat > now + SKEW {
        return refused("BadJwt", "Credential issued in the future");
    }
    if now - SKEW >= exp {
        return refused("JwtExpired", "Credential has expired");
    }
    // 12–16: its issuer, signature and space.
    let Some(iss) = jwt.claim("iss").filter(|i| valid_did(i)) else {
        return refused("BadJwt", "Credential iss is not a DID");
    };
    crate::limits::charge(s, call, None, None)?;
    match issuers::verify_issuer(s, iss, &jwt, false).await {
        Ok(()) => {}
        Err(Unverified::NoKey) => {
            return refused("BadJwtIss", "Could not resolve the credential's issuer key");
        }
        Err(Unverified::Signature) => {
            return refused("BadJwtSignature", "Credential signature is invalid");
        }
    }
    let Some(sr) = jwt.claim("sub").and_then(SpaceRef::parse) else {
        return refused("BadJwtSub", "Credential sub is not a space");
    };
    if sr.authority != iss {
        return refused("BadJwtIss", "Credential iss is not the space's authority");
    }
    // 17–18: the request's HTTP Message Signature.
    let presented = header_text(headers, "atproto-space-audience");
    if !presented.is_some_and(valid_did) {
        return refused(
            "BadSpaceSignature",
            "Atproto-Space-Audience is missing or not a DID",
        );
    }
    let signed = pds_space::signature::Headers {
        authorization: Some(authorization),
        audience: presented,
        signature_input: header_text(headers, "signature-input"),
        signature: header_text(headers, "signature"),
    };
    if let Err(why) = pds_space::signature::verify(&signed, kid) {
        return refused(
            "BadSpaceSignature",
            &format!("Request signature is invalid: {why}"),
        );
    }
    // 19–20: revocation, then the audience.
    let space = jwt.claim("sub").unwrap_or_default();
    if s.space_credentials.is_revoked(space, jti, s.sessions.now()) {
        return refused("CredentialRevoked", "Credential has been revoked");
    }
    if presented != Some(audience) {
        return refused("BadSpaceAudience", "Request is signed for another audience");
    }
    Ok(SpaceCredential {
        space: space.to_string(),
        jti: jti.to_string(),
        kid: kid.to_string(),
    })
}

// ---- notifyCredentialsRevoked ----------------------------------------------

/// `notifyCredentialsRevoked`: its service auth, then its input.
async fn notify_credentials_revoked(
    s: &Shared,
    call: &Call<'_>,
    m: &'static pds_lexicon::Method,
) -> Result<Resp, XrpcError> {
    let (iss, aud) = service_auth(s, call, NOTIFY).await?;
    let b = crate::input(call, m)?;
    crate::limits::guard(s, call, None, Some(&b))?;
    let space = required(&b, "space")?;
    let Some(sr) = SpaceRef::parse(space) else {
        return invalid("space must be a valid space-ref");
    };
    if iss != sr.authority {
        return err(
            403,
            "Forbidden",
            "Only the space's authority may revoke its credentials",
        );
    }
    if !aud
        .as_deref()
        .is_some_and(|aud| valid_did(aud) && s.account(aud).is_some())
    {
        return err(
            403,
            "Forbidden",
            "The token is not addressed to an account here",
        );
    }
    let jtis: Vec<&str> = b["credentials"]
        .as_array()
        .into_iter()
        .flatten()
        .filter_map(Json::as_str)
        .collect();
    let n = s
        .space_credentials
        .revoke(&s.log, space, &jtis, s.sessions.now())
        .or_else(|e| {
            crate::ops::failed("logging a revocation failed", e);
            crate::internal()
        })?;
    durable(s.log.clone(), n).await?;
    Ok(Resp::Nothing)
}

/// Service auth for method `lxm` (`atproto/xrpc.md`, "Inter-Service
/// Authentication"), as `notifyCredentialsRevoked` takes it: answers its
/// `iss` and its `aud`, if a string. The call pays its rate limits once
/// the checks before its issuer's document is read have passed, and before
/// it is read (`spec/LIMITS.md`, "Rate limits").
pub(crate) async fn service_auth(
    s: &Shared,
    call: &Call<'_>,
    lxm: &str,
) -> Result<(String, Option<String>), XrpcError> {
    let headers = call.headers;
    let missing = || refused("MissingJwt", "Missing jwt");
    // An empty header is as none.
    let Some(authorization) = headers.get(header::AUTHORIZATION).filter(|h| !h.is_empty()) else {
        return missing();
    };
    let mut words = authorization.to_str().unwrap_or_default().split(' ');
    let (Some(scheme), Some(token), None) = (words.next(), words.next(), words.next()) else {
        return invalid_token();
    };
    if scheme.is_empty() || token.is_empty() {
        return invalid_token();
    }
    if ["Basic", "DPoP", SCHEME]
        .iter()
        .any(|s| scheme.eq_ignore_ascii_case(s))
    {
        return missing();
    }
    if !scheme.eq_ignore_ascii_case("Bearer") {
        return invalid_token();
    }
    let jwt = match Jwt::parse(token) {
        Some(jwt) if jwt.header("alg").is_some() && jwt.number("exp").is_some() => jwt,
        _ => return refused("BadJwt", "Poorly formatted jwt"),
    };
    if ["at+jwt", "refresh+jwt", "dpop+jwt"].contains(&jwt.header("typ").unwrap_or_default()) {
        return refused("BadJwtType", "Invalid jwt type");
    }
    if s.sessions.now() as f64 > jwt.number("exp").unwrap_or_default() {
        return refused("JwtExpired", "jwt expired");
    }
    if jwt.claim("lxm") != Some(lxm) {
        return refused("BadJwtLexiconMethod", "Bad jwt lexicon method (\"lxm\")");
    }
    // A DID, or a DID and a `#` fragment: its key is the DID's; `iss` is answered as written.
    let Some(iss) = jwt.claim("iss") else {
        return refused("BadJwtIss", "Bad jwt iss");
    };
    let did = iss.split_once('#').map_or(iss, |(did, _)| did);
    if !valid_did(did) {
        return refused("BadJwtIss", "Bad jwt iss");
    }
    crate::limits::charge(s, call, None, None)?;
    match issuers::verify_issuer(s, did, &jwt, true).await {
        Ok(()) => Ok((iss.to_string(), jwt.claim("aud").map(str::to_string))),
        Err(Unverified::NoKey) => refused(
            "AuthenticationRequired",
            "Could not resolve the issuer's signing key",
        ),
        Err(Unverified::Signature) => {
            refused("BadJwtSignature", "jwt signature does not match jwt issuer")
        }
    }
}