Something went wrong. Try again.
A lexicon-driven AppView for ATProto.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571use sha2::{Digest, Sha256};
use crate::db::{DatabaseBackend, adapt_sql};use crate::error::AppError;
/// Resolved API client identity for DPoP operations.pub struct ResolvedClient { pub id: String, pub client_key: String, pub client_type: String, pub scopes: String, pub allowed_origins: Option<Vec<String>>,}
/// Authenticate a confidential client using client_key + client_secret.pub async fn authenticate_confidential( pool: &sqlx::AnyPool, backend: DatabaseBackend, client_key: &str, client_secret: &str,) -> Result<ResolvedClient, AppError> { let secret_hash = hex::encode(Sha256::digest(client_secret.as_bytes()));
let sql = adapt_sql( "SELECT id, client_key, client_type, scopes, allowed_origins, client_secret_hash FROM happyview_api_clients WHERE client_key = ? AND is_active = 1", backend, );
let row: Option<(String, String, String, String, Option<String>, String)> = crate::db::query_as(&sql) .bind(client_key) .fetch_optional(pool) .await .map_err(|e| AppError::Internal(format!("client lookup failed: {e}")))?;
let (id, key, client_type, scopes, origins_json, stored_hash) = row.ok_or_else(|| AppError::Auth("invalid client credentials".into()))?;
if !crate::constant_time::ct_eq_str(&stored_hash, &secret_hash) { return Err(AppError::Auth("invalid client credentials".into())); }
if client_type != "confidential" { return Err(AppError::Auth( "this endpoint requires confidential client authentication".into(), )); }
let allowed_origins = origins_json.map(|json| serde_json::from_str::<Vec<String>>(&json).unwrap_or_default());
Ok(ResolvedClient { id, client_key: key, client_type, scopes, allowed_origins, })}
/// Authenticate a public client using client_key + origin validation./// Returns the client but does NOT verify PKCE — that's done at session registration.pub async fn authenticate_public( pool: &sqlx::AnyPool, backend: DatabaseBackend, client_key: &str, origin: Option<&str>,) -> Result<ResolvedClient, AppError> { let sql = adapt_sql( "SELECT id, client_key, client_type, scopes, allowed_origins FROM happyview_api_clients WHERE client_key = ? AND is_active = 1", backend, );
let row: Option<(String, String, String, String, Option<String>)> = crate::db::query_as(&sql) .bind(client_key) .fetch_optional(pool) .await .map_err(|e| AppError::Internal(format!("client lookup failed: {e}")))?;
let (id, key, client_type, scopes, origins_json) = row.ok_or_else(|| AppError::Auth("unknown client".into()))?;
if client_type != "public" { return Err(AppError::Auth( "this client is not registered as a public client".into(), )); }
// Validate origin if the client has allowed_origins configured if let Some(ref origins_str) = origins_json { let allowed: Vec<String> = serde_json::from_str(origins_str).unwrap_or_default(); if !allowed.is_empty() { match origin { Some(o) if allowed.iter().any(|a| a == o) => {} Some(o) => { tracing::warn!(client_key, origin = o, "Origin mismatch for public client"); return Err(AppError::Auth("origin not allowed for this client".into())); } None => { tracing::warn!(client_key, "No Origin header for public client"); return Err(AppError::Auth( "Origin header required for public clients".into(), )); } } } }
let allowed_origins = origins_json.map(|json| serde_json::from_str::<Vec<String>>(&json).unwrap_or_default());
Ok(ResolvedClient { id, client_key: key, client_type, scopes, allowed_origins, })}
/// Resolve an API client by client_key only (no secret verification)./// Used when the caller has already been authenticated by other means (e.g. DPoP proof).pub async fn resolve_client_by_key( pool: &sqlx::AnyPool, backend: DatabaseBackend, client_key: &str,) -> Result<ResolvedClient, AppError> { let sql = adapt_sql( "SELECT id, client_key, client_type, scopes, allowed_origins FROM happyview_api_clients WHERE client_key = ? AND is_active = 1", backend, );
let row: Option<(String, String, String, String, Option<String>)> = crate::db::query_as(&sql) .bind(client_key) .fetch_optional(pool) .await .map_err(|e| AppError::Internal(format!("client lookup failed: {e}")))?;
let (id, key, client_type, scopes, origins_json) = row.ok_or_else(|| AppError::Auth("unknown client".into()))?;
let allowed_origins = origins_json.map(|json| serde_json::from_str::<Vec<String>>(&json).unwrap_or_default());
Ok(ResolvedClient { id, client_key: key, client_type, scopes, allowed_origins, })}
/// Validate that token scopes are allowed by the client's registered scopes.////// Rules:/// - `atproto` must be present in token scopes (always implicitly allowed)/// - Every non-`atproto` scope in the token must appear in the client's registered scopes/// - `include:X` client scopes are expanded by looking up the permission set/// lexicon `X` and extracting its `rpc:` and `repo:` permissions/// - `repo?collection=X&collection=Y` scopes (PDS-granted) are allowed if the/// client has `transition:generic` or has collection-level permissions from/// expanded `include:` scopespub async fn validate_scopes( token_scopes: &str, client_scopes: &str, lexicons: &crate::lexicon::LexiconRegistry,) -> Result<(), AppError> { let token_set: std::collections::HashSet<&str> = token_scopes.split_whitespace().collect(); let mut client_set: std::collections::HashSet<String> = std::collections::HashSet::new();
for scope in client_scopes.split_whitespace() { if let Some(perm_set_id) = scope.strip_prefix("include:") { expand_permission_set(perm_set_id, lexicons, &mut client_set).await; } client_set.insert(scope.to_string()); }
if !token_set.contains("atproto") { return Err(AppError::BadRequest( "token must include the 'atproto' scope".into(), )); }
let has_generic = client_set.contains("transition:generic");
for scope in &token_set { if *scope == "atproto" { continue; } if client_set.contains(*scope) { continue; }
// The PDS grants `repo?collection=X&collection=Y` to restrict which // collections the token can access. Allow if the client has broad // access (`transition:generic`) or has matching collection-level // permissions from expanded `include:` scopes. if let Some(query) = scope.strip_prefix("repo?") { if has_generic { continue; } let all_allowed = query.split('&').all(|param| { let Some(col) = param.strip_prefix("collection=") else { return true; }; let prefix = format!("repo:{}?", col); client_set.iter().any(|cs| cs.starts_with(&prefix)) }); if all_allowed { continue; } }
// The PDS also grants bare `repo:COLLECTION` scopes (without // `?action=`). Match if the expanded client set has any // `repo:COLLECTION?action=...` entry for that collection. if let Some(collection) = scope.strip_prefix("repo:") { let prefix = format!("repo:{}?", collection); if client_set.iter().any(|cs| cs.starts_with(&prefix)) { continue; } }
return Err(AppError::BadRequest(format!( "scope '{}' is not allowed for this client", scope ))); }
Ok(())}
/// Expand a permission set lexicon into individual `rpc:` and `repo:` scopes.async fn expand_permission_set( nsid: &str, lexicons: &crate::lexicon::LexiconRegistry, out: &mut std::collections::HashSet<String>,) { let lexicon = match lexicons.get(nsid).await { Some(l) => l, None => { tracing::warn!(nsid = %nsid, "permission set lexicon not found in registry"); return; } };
let permissions = match lexicon .raw .get("defs") .and_then(|d| d.get("main")) .and_then(|m| m.get("permissions")) .and_then(|p| p.as_array()) { Some(p) => p, None => return, };
for perm in permissions { let resource = perm.get("resource").and_then(|r| r.as_str()).unwrap_or(""); match resource { "rpc" => { if let Some(lxms) = perm.get("lxm").and_then(|l| l.as_array()) { for lxm in lxms { if let Some(s) = lxm.as_str() { out.insert(format!("rpc:{s}")); } } } } "repo" => { if let Some(collections) = perm.get("collection").and_then(|c| c.as_array()) { for col in collections { if let Some(s) = col.as_str() { out.insert(format!("repo:{s}?action=create")); out.insert(format!("repo:{s}?action=update")); out.insert(format!("repo:{s}?action=delete")); } } } } _ => {} } }}
/// Verify a PKCE challenge against a verifier.pub fn verify_pkce(challenge: &str, verifier: &str) -> bool { use base64::Engine; use base64::engine::general_purpose::URL_SAFE_NO_PAD; let hash = Sha256::digest(verifier.as_bytes()); let computed = URL_SAFE_NO_PAD.encode(hash); crate::constant_time::ct_eq_str(&computed, challenge)}
#[cfg(test)]mod tests { use super::*;
fn empty_registry() -> crate::lexicon::LexiconRegistry { crate::lexicon::LexiconRegistry::new() }
#[tokio::test] async fn validate_scopes_requires_atproto() { let reg = empty_registry(); let result = validate_scopes("transition:generic", "atproto transition:generic", ®).await; assert!(result.is_err()); }
#[tokio::test] async fn validate_scopes_atproto_only_always_passes() { let reg = empty_registry(); let result = validate_scopes("atproto", "com.example.whatever", ®).await; assert!(result.is_ok()); }
#[tokio::test] async fn validate_scopes_subset_passes() { let reg = empty_registry(); let result = validate_scopes( "atproto com.example.basic", "atproto com.example.basic com.example.advanced", ®, ) .await; assert!(result.is_ok()); }
#[tokio::test] async fn validate_scopes_excess_scope_fails() { let reg = empty_registry(); let result = validate_scopes( "atproto com.example.basic com.example.advanced", "atproto com.example.basic", ®, ) .await; assert!(result.is_err()); }
#[tokio::test] async fn validate_scopes_transition_generic_requires_registration() { let reg = empty_registry(); let result = validate_scopes("atproto transition:generic", "atproto", ®).await; assert!(result.is_err());
let result = validate_scopes( "atproto transition:generic", "atproto transition:generic", ®, ) .await; assert!(result.is_ok()); }
#[tokio::test] async fn validate_scopes_expands_include_permission_set() { let reg = empty_registry(); let raw = serde_json::json!({ "lexicon": 1, "id": "com.example.authBasic", "defs": { "main": { "type": "permission-set", "permissions": [ { "type": "permission", "resource": "rpc", "lxm": ["com.example.getProfile", "com.example.putProfile"] }, { "type": "permission", "resource": "repo", "collection": ["com.example.profile"] } ] } } }); let parsed = crate::lexicon::ParsedLexicon::parse( raw, 1, None, crate::lexicon::ProcedureAction::Upsert, None, ) .unwrap(); reg.upsert(parsed).await;
let result = validate_scopes( "atproto rpc:com.example.getProfile repo:com.example.profile?action=create", "atproto include:com.example.authBasic", ®, ) .await; assert!(result.is_ok());
let result = validate_scopes( "atproto rpc:com.example.notAllowed", "atproto include:com.example.authBasic", ®, ) .await; assert!(result.is_err()); }
#[tokio::test] async fn validate_scopes_repo_collection_allowed_with_transition_generic() { let reg = empty_registry(); let result = validate_scopes( "atproto transition:generic repo?collection=com.example.profile&collection=com.example.post", "atproto transition:generic", ®, ) .await; assert!(result.is_ok()); }
#[tokio::test] async fn validate_scopes_repo_collection_allowed_with_expanded_permissions() { let reg = empty_registry(); let raw = serde_json::json!({ "lexicon": 1, "id": "com.example.authBasic", "defs": { "main": { "type": "permission-set", "permissions": [ { "type": "permission", "resource": "repo", "collection": ["com.example.profile", "com.example.post"] } ] } } }); let parsed = crate::lexicon::ParsedLexicon::parse( raw, 1, None, crate::lexicon::ProcedureAction::Upsert, None, ) .unwrap(); reg.upsert(parsed).await;
let result = validate_scopes( "atproto repo?collection=com.example.profile&collection=com.example.post", "atproto include:com.example.authBasic", ®, ) .await; assert!(result.is_ok()); }
#[tokio::test] async fn validate_scopes_repo_collection_rejected_without_permission() { let reg = empty_registry(); let result = validate_scopes( "atproto repo?collection=com.example.profile", "atproto", ®, ) .await; assert!(result.is_err()); }
#[tokio::test] async fn validate_scopes_repo_collection_rejected_partial_match() { let reg = empty_registry(); let raw = serde_json::json!({ "lexicon": 1, "id": "com.example.authBasic", "defs": { "main": { "type": "permission-set", "permissions": [ { "type": "permission", "resource": "repo", "collection": ["com.example.profile"] } ] } } }); let parsed = crate::lexicon::ParsedLexicon::parse( raw, 1, None, crate::lexicon::ProcedureAction::Upsert, None, ) .unwrap(); reg.upsert(parsed).await;
let result = validate_scopes( "atproto repo?collection=com.example.profile&collection=com.example.secret", "atproto include:com.example.authBasic", ®, ) .await; assert!(result.is_err()); }
#[tokio::test] async fn validate_scopes_bare_repo_collection_allowed_with_expanded_permissions() { let reg = empty_registry(); let raw = serde_json::json!({ "lexicon": 1, "id": "com.example.authBasic", "defs": { "main": { "type": "permission-set", "permissions": [ { "type": "permission", "resource": "repo", "collection": ["com.example.profile", "com.example.post"] } ] } } }); let parsed = crate::lexicon::ParsedLexicon::parse( raw, 1, None, crate::lexicon::ProcedureAction::Upsert, None, ) .unwrap(); reg.upsert(parsed).await;
let result = validate_scopes( "atproto repo:com.example.profile", "atproto include:com.example.authBasic", ®, ) .await; assert!(result.is_ok()); }
#[tokio::test] async fn validate_scopes_bare_repo_collection_rejected_without_permission() { let reg = empty_registry(); let result = validate_scopes("atproto repo:com.example.secret", "atproto", ®).await; assert!(result.is_err()); }
#[test] fn verify_pkce_valid() { use base64::Engine; use base64::engine::general_purpose::URL_SAFE_NO_PAD;
let verifier = "test-verifier-string-12345678901234567890"; let hash = sha2::Sha256::digest(verifier.as_bytes()); let challenge = URL_SAFE_NO_PAD.encode(hash);
assert!(verify_pkce(&challenge, verifier)); }
#[test] fn verify_pkce_invalid() { assert!(!verify_pkce("wrong-challenge", "some-verifier")); }}