chadtmiller.com/monolith
An atproto PDS
0
0
//! 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")
}
}
}