//! 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 { 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>, 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 { 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::>()?; 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, ) -> Result { 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 { 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) -> Result { 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) -> Result { 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() -> Result { err(400, "SpaceDeleted", "Space has been deleted") } fn space_not_found() -> Result { 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(name: &'static str, message: &str) -> Result { 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 { 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 { 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), 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") } } }