//! `space:` permissions (`spec/OAUTH-SCOPES.md`, "Spaces"): a token read //! into its parameters, its defaults filled; a token as a session's scope //! keeps it, its declared collections and its `self` authority filled at //! the code grant and each refresh; what one allows; and the scope a //! refusal names. use percent_encoding::{AsciiSet, NON_ALPHANUMERIC, percent_decode_str, utf8_percent_encode}; use serde_json::Value as Json; use std::collections::HashMap; use std::sync::Arc; /// The actions, in the order a scope string writes them. pub(crate) const ACTIONS: [&str; 5] = ["read_self", "read", "create", "update", "delete"]; /// The actions a permission has when it names none. const DEFAULT_ACTIONS: [&str; 4] = ["read", "create", "update", "delete"]; /// The management operations, in the order a scope string writes them. pub(crate) const MANAGE: [&str; 3] = ["create", "update", "delete"]; /// What `encodeURIComponent` leaves as it is: letters, digits and `-_.!~*'()`. const COMPONENT: &AsciiSet = &NON_ALPHANUMERIC .remove(b'-') .remove(b'_') .remove(b'.') .remove(b'!') .remove(b'~') .remove(b'*') .remove(b'\'') .remove(b'(') .remove(b')'); /// What a form-encoded query leaves as it is: letters, digits and `*-._`. const FORM: &AsciiSet = &NON_ALPHANUMERIC .remove(b'*') .remove(b'-') .remove(b'.') .remove(b'_'); /// `%3A`, `%2F`, `%2B`, `%2C`, `%40` and `%25` turned back to what they encode. fn normalized(s: &str) -> String { let mut out = String::with_capacity(s.len()); let mut rest = s; while let Some(i) = rest.find('%') { out.push_str(&rest[..i]); let code = rest.get(i..i + 3).unwrap_or(&rest[i..]); let back = match code.to_ascii_uppercase().as_str() { "%3A" => Some(':'), "%2F" => Some('/'), "%2B" => Some('+'), "%2C" => Some(','), "%40" => Some('@'), "%25" => Some('%'), _ => None, }; match back { Some(c) => { out.push(c); rest = &rest[i + code.len()..]; } None => { out.push('%'); rest = &rest[i + 1..]; } } } out.push_str(rest); out } /// A value of a form-encoded query, as `URLSearchParams` writes it. fn form(v: &str) -> String { utf8_percent_encode(v, FORM).to_string().replace("%20", "+") } /// A `space` permission, its defaults filled. #[derive(Clone, Debug, PartialEq, Eq)] pub(crate) struct SpacePermission { pub space_type: String, /// A DID, `self` or `*`. pub authority: String, /// A record key or `*`. pub skey: String, /// None: no collection given, so no write is allowed. pub collections: Option>, pub actions: Vec, pub manage: Vec, } /// A space operation's kind (`spec/OAUTH-SCOPES.md`, "What it allows"). #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum SpaceOp<'a> { /// `read` or `read_self`. Read { whole: bool }, /// A write of `collection`: `create`, `update` or `delete`. Write { action: &'static str, collection: &'a str, }, /// Managing the space: `create`, `update` or `delete`. Manage(&'static str), } /// A space operation: the space, by its authority, type and key (each may /// be `*`, as `listSpaces` asks), and what is done. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct SpaceNeed<'a> { pub authority: &'a str, pub space_type: &'a str, pub skey: &'a str, pub op: SpaceOp<'a>, } impl SpacePermission { /// The `space` permission a token is, if it is one that parses /// (`super::scope::permission`). pub fn of(token: &str) -> Option { if !token.starts_with("space") || !super::scope::permission(token) { return None; } let (head, query) = token.split_once('?').unwrap_or((token, "")); let mut params: Vec<(String, String)> = Vec::new(); if let Some((_, p)) = head.split_once(':') { params.push(( "spaceType".into(), percent_decode_str(p).decode_utf8().ok()?.into_owned(), )); } params.extend( url::form_urlencoded::parse(query.as_bytes()) .map(|(k, v)| (k.into_owned(), v.into_owned())), ); let one = |k: &str| params.iter().find(|(n, _)| n == k).map(|(_, v)| v.clone()); let all = |k: &str| { let v: Vec = params .iter() .filter(|(n, _)| n == k) .map(|(_, v)| v.clone()) .collect(); (!v.is_empty()).then_some(v) }; Some(SpacePermission::new( one("spaceType")?, one("authority"), one("skey"), all("collection"), all("action"), all("manage"), )) } /// A permission of these parameters, each as given, its defaults filled /// where one is not: collections each once and sorted, or `*` alone; /// actions and management in the order a scope string writes them. pub fn new( space_type: String, authority: Option, skey: Option, collection: Option>, action: Option>, manage: Option>, ) -> SpacePermission { SpacePermission { space_type, authority: authority.unwrap_or_else(|| "self".into()), skey: skey.unwrap_or_else(|| "*".into()), collections: collection.map(|c| collections(&c)), actions: ordered( &ACTIONS, &action.unwrap_or_else(|| DEFAULT_ACTIONS.map(String::from).to_vec()), ), manage: ordered(&MANAGE, &manage.unwrap_or_default()), } } /// The scope string it is written as (`spec/OAUTH-SCOPES.md`, "The /// token's scope"). pub fn to_scope(&self) -> String { let mut q: Vec = Vec::new(); if self.authority != "self" { q.push(format!("authority={}", form(&self.authority))); } if self.skey != "*" { q.push(format!("skey={}", form(&self.skey))); } for c in self.collections.iter().flatten() { q.push(format!("collection={}", form(c))); } let default = self.actions.len() == DEFAULT_ACTIONS.len() && DEFAULT_ACTIONS .iter() .all(|a| self.actions.iter().any(|x| x == a)); if !default { q.extend(self.actions.iter().map(|a| format!("action={a}"))); } q.extend(self.manage.iter().map(|m| format!("manage={m}"))); let head = format!( "space:{}", normalized(&utf8_percent_encode(&self.space_type, COMPONENT).to_string()) ); if q.is_empty() { head } else { format!("{head}?{}", normalized(&q.join("&"))) } } /// Whether it allows `need`. pub fn allows(&self, need: &SpaceNeed) -> bool { let matches = |mine: &str, theirs: &str| mine == "*" || mine == theirs; if !matches(&self.space_type, need.space_type) || self.authority == "self" || !matches(&self.authority, need.authority) || !matches(&self.skey, need.skey) { return false; } let has = |a: &str| self.actions.iter().any(|x| x == a); match need.op { SpaceOp::Read { whole: true } => has("read"), SpaceOp::Read { whole: false } => has("read") || has("read_self"), SpaceOp::Write { action, collection } => { has(action) && self .collections .as_ref() .is_some_and(|c| c.iter().any(|c| c == "*" || c == collection)) } SpaceOp::Manage(m) => self.manage.iter().any(|x| x == m), } } } /// Collections as a scope string keeps them: several, each once and /// sorted, or `*` alone if one is `*`. fn collections(given: &[String]) -> Vec { if given.len() <= 1 { return given.to_vec(); } if given.iter().any(|c| c == "*") { return vec!["*".into()]; } let mut out = given.to_vec(); out.sort(); out.dedup(); out } /// Of `given`, those in `order`, in its order, each once. fn ordered(order: &[&str], given: &[String]) -> Vec { order .iter() .filter(|o| given.iter().any(|g| g == *o)) .map(|o| o.to_string()) .collect() } impl SpaceNeed<'_> { /// The scope a refusal names: the narrowest that would allow it. pub fn scope(&self) -> String { let (collections, actions, manage) = match self.op { SpaceOp::Manage(m) => (None, vec!["read_self".to_string()], vec![m.to_string()]), SpaceOp::Read { whole } => ( None, vec![if whole { "read" } else { "read_self" }.to_string()], vec![], ), SpaceOp::Write { action, collection } => ( Some(vec![collection.to_string()]), vec![action.to_string()], vec![], ), }; SpacePermission { space_type: self.space_type.to_string(), authority: self.authority.to_string(), skey: self.skey.to_string(), collections, actions, manage, } .to_scope() } } /// The space types `space:` tokens name, each once, but `*`. pub(crate) fn types<'a>(scope: impl IntoIterator) -> Vec { let mut out: Vec = Vec::new(); for p in scope.into_iter().filter_map(SpacePermission::of) { if p.space_type != "*" && !out.contains(&p.space_type) { out.push(p.space_type); } } out } /// The DIDs `space:` tokens name as their `authority`, each once, in the /// order first named: whose handles the authorization page verifies /// (`spec/OAUTH-SCOPES.md`, "On the authorization page"). pub(crate) fn authorities<'a>(scope: impl IntoIterator) -> Vec { let mut out: Vec = Vec::new(); for p in scope.into_iter().filter_map(SpacePermission::of) { if p.authority.starts_with("did:") && !out.contains(&p.authority) { out.push(p.authority); } } out } /// A token of a session's scope, as its tokens keep it /// (`spec/OAUTH-SCOPES.md`, "The token's scope"): a `space:` token with no /// collection gets its declaration's, and one of authority `self` gets /// `did`; one neither changes, and every other token, is as given. pub(crate) fn rewritten( token: &str, did: &str, declarations: &HashMap>, ) -> String { let Some(mut p) = SpacePermission::of(token) else { return token.to_string(); }; let mut changed = false; if p.collections.is_none() && p.space_type != "*" { let declared: Vec = declarations .get(&p.space_type) .and_then(|main| main["collections"].as_array()) .into_iter() .flatten() .filter_map(|c| c.as_str().map(str::to_string)) .collect(); if !declared.is_empty() { p.collections = Some(collections(&declared)); changed = true; } } if p.authority == "self" { p.authority = did.to_string(); changed = true; } if changed { p.to_scope() } else { token.to_string() } } #[cfg(test)] mod tests { use super::*; use serde_json::json; #[test] fn read_and_written() { let p = SpacePermission::of("space:com.example.forum").unwrap(); assert_eq!( (p.authority.as_str(), p.skey.as_str(), &p.collections), ("self", "*", &None) ); assert_eq!(p.actions, ["read", "create", "update", "delete"]); assert_eq!(p.to_scope(), "space:com.example.forum"); let p = SpacePermission::of( "space?spaceType=com.example.forum&action=delete&action=read_self&manage=delete&manage=create&collection=b.c.d&collection=a.b.c&collection=a.b.c", ) .unwrap(); assert_eq!( p.to_scope(), "space:com.example.forum?collection=a.b.c&collection=b.c.d&action=read_self&action=delete&manage=create&manage=delete" ); assert_eq!( SpacePermission::of("space:*?authority=*&collection=a.b.c&collection=*") .unwrap() .to_scope(), "space:*?authority=*&collection=*" ); assert!(SpacePermission::of("repo:*").is_none()); assert!(SpacePermission::of("space:com.example.forum?authority=me").is_none()); // The skey's `~` is percent-encoded, a DID's `:` and `%` are not. let need = SpaceNeed { authority: "did:web:localhost%3A1234", space_type: "com.example.forum", skey: "a~b", op: SpaceOp::Write { action: "create", collection: "com.example.post", }, }; assert_eq!( need.scope(), "space:com.example.forum?authority=did:web:localhost%3A1234&skey=a%7Eb&collection=com.example.post&action=create" ); } #[test] fn rewritten_at_the_grant() { let decl = HashMap::from([( "com.example.forum".to_string(), Arc::new( json!({ "type": "space", "collections": ["com.example.thread", "com.example.reply"] }), ), )]); let did = "did:plc:abc"; let r = |t: &str| rewritten(t, did, &decl); assert_eq!( r("space:com.example.forum"), "space:com.example.forum?authority=did:plc:abc&collection=com.example.reply&collection=com.example.thread" ); assert_eq!( r("space:com.example.forum?authority=did:plc:other&skey=*"), "space:com.example.forum?authority=did:plc:other&collection=com.example.reply&collection=com.example.thread" ); // Collections given, another authority: as given. let kept = "space:com.example.forum?authority=*&collection=x.y.z&skey=*"; assert_eq!(r(kept), kept); assert_eq!( r("space:*?action=read"), "space:*?authority=did:plc:abc&action=read" ); // An undeclared type, or one declaring none: no collections. assert_eq!( r("space:com.example.other"), "space:com.example.other?authority=did:plc:abc" ); assert_eq!(r("atproto"), "atproto"); assert_eq!( types([ "space:a.b.c", "space:*", "space:a.b.c?action=read", "repo:*" ]), ["a.b.c"] ); } #[test] fn what_it_allows() { let p = |t: &str| SpacePermission::of(t).unwrap(); let need = |op| SpaceNeed { authority: "did:plc:abc", space_type: "com.example.forum", skey: "main", op, }; let write = |action, collection| need(SpaceOp::Write { action, collection }); let granted = p("space:com.example.forum?authority=did:plc:abc&collection=com.example.post"); assert!(granted.allows(&write("create", "com.example.post"))); assert!(!granted.allows(&write("create", "com.example.other"))); assert!(granted.allows(&need(SpaceOp::Read { whole: true }))); assert!(!granted.allows(&need(SpaceOp::Manage("create")))); // `self` unresolved matches nothing; no collection allows no write. assert!(!p("space:com.example.forum").allows(&need(SpaceOp::Read { whole: false }))); assert!( !p("space:com.example.forum?authority=did:plc:abc") .allows(&write("create", "com.example.post")) ); let read_self = p("space:*?authority=*&action=read_self"); assert!(read_self.allows(&need(SpaceOp::Read { whole: false }))); assert!(!read_self.allows(&need(SpaceOp::Read { whole: true }))); assert!(read_self.allows(&SpaceNeed { authority: "*", space_type: "*", skey: "*", op: SpaceOp::Read { whole: false } })); // A grant of one type is no grant of every type. assert!(!granted.allows(&SpaceNeed { space_type: "*", ..need(SpaceOp::Read { whole: false }) })); let manage = p( "space:com.example.forum?authority=did:plc:abc&skey=main&manage=create&action=read_self", ); assert!(manage.allows(&need(SpaceOp::Manage("create")))); assert!(!manage.allows(&need(SpaceOp::Manage("delete")))); assert!( !p("space:com.example.forum?authority=did:plc:abc&skey=other&manage=create") .allows(&need(SpaceOp::Manage("create"))) ); assert_eq!( need(SpaceOp::Manage("create")).scope(), "space:com.example.forum?authority=did:plc:abc&skey=main&action=read_self&manage=create" ); assert_eq!( SpaceNeed { authority: "*", space_type: "*", skey: "*", op: SpaceOp::Read { whole: false } } .scope(), "space:*?authority=*&action=read_self" ); } }