//! What HUD asks an account's server for, and no more (atproto's //! permissions, never `transition:generic`), read from the views the //! instance serves (`view::views()`: the operator's apps' with, where the //! workspace is served, the bundled ones): to call, as the account, any //! method of each service a view names, as the `query` tool may; to write //! each collection one writes, and to delete those a plan of one's deletes //! beyond them (`view::Plan`); to upload the images a composer of theirs //! takes; with a view drawing feeds by name, to read the account's Bluesky //! preferences, and with one reporting interactions, to tell feed //! generators what was read, each through the AppView. The workspace adds //! people's themes, and with spaces on, `config::SPACE_SCOPE`. So an //! instance serving its operator's apps alone asks for what those apps do, //! a view added asks at once for what it needs, and a sign-in made before //! is then behind it (`behind`): signing in again grants the rest. //! //! Where an app file names permission sets (`permissions`, `Include`), HUD //! asks for those first (`including`): each `include:`, which the account's //! server resolves from the set's published lexicon, and of the rest only //! what no set can hold (pictures, others' collections and services). A //! set grows as its app does, and reaches accounts signed in as their //! tokens are refreshed, so a view added asks for nothing new. What the //! views do (`asked`) stays what HUD holds its own writes and calls to, //! and what it asks a server that refuses the sets. Whether a set grants //! what the views do is checked as HUD starts (`ungranted`). use crate::config::SPACE_SCOPE; use crate::view::Views; use crate::{feeds, interactions, pds, theme}; use serde_json::Value; /// A permission set an operator's app file names (`permissions`): its /// NSID, and the service (`did:…#fragment`) its methods are called at, as /// the audience its `rpc` permissions inherit (`inheritAud`), if any. #[derive(Clone, Debug, PartialEq)] pub struct Include { pub nsid: String, pub service: Option, } impl Include { /// Its permission: `include:`, with `?aud=` its service, escaped /// as `call`'s is. pub fn token(&self) -> String { match &self.service { Some(s) => format!("include:{}?aud={}", self.nsid, aud(s)), None => format!("include:{}", self.nsid), } } /// The namespace the set may grant within: its NSID but the last /// segment, with its dot, as `social.grain.` of `social.grain.authFull`. fn group(&self) -> &str { let end = self.nsid.rfind('.').map_or(0, |i| i + 1); &self.nsid[..end] } /// Whether `nsid` is in the set's namespace: what it may grant. fn within(&self, nsid: &str) -> bool { nsid.len() > self.group().len() && nsid.starts_with(self.group()) } /// Whether the set could hold `token`, a permission of what the views /// do: to write or delete a collection in its namespace, or to call /// methods of its service. A set holds no `blob`, `account` or /// `identity` permission, nothing of another namespace, no audience but /// the one its include names, and no method but those it lists, which /// `ungranted` checks against what the views call. fn holds(&self, token: &str) -> bool { if let Some(c) = token.strip_prefix("repo:") { return self.within(c.split_once('?').map_or(c, |(c, _)| c)); } self.service.as_deref().is_some_and(|s| token == call(s)) } } /// The scope asked of accounts' servers by an instance serving `views`, /// with `workspace` the workspace's own (people's themes), and `spaces` the /// permission for its spaces too. pub fn asked(views: &Views, workspace: bool, spaces: bool) -> String { let mut tokens = vec!["atproto".to_string()]; let mut written = views.written(); if workspace { written.insert(theme::COLLECTION.to_string()); } tokens.extend(written.iter().map(|c| write(c))); let deleted = views.plan_collections(); tokens.extend( deleted .iter() .filter(|c| !written.contains(*c)) .map(|c| delete(c)), ); if views.uploads() { tokens.extend(pds::IMAGE_TYPES.map(|mime| format!("blob:{mime}"))); } let (named, sent) = (views.names_feeds(), views.sends_interactions()); let mut services = views.called(); // Feeds' generators are read from the AppView, as the account. if named || sent { services.insert(interactions::APPVIEW.to_string()); } tokens.extend(services.iter().map(|s| call(s))); // The PDS answers preferences itself, held to the AppView it is set up // with, which need not be Bluesky's; and a feed's generator is anyone's. if named { tokens.push(any_audience(feeds::GET_PREFERENCES)); } if sent { tokens.push(any_audience(interactions::SEND)); } if spaces { tokens.push(SPACE_SCOPE.to_string()); } tokens.join(" ") } /// The collections `scope` asks to write, in its order: not those it asks /// to delete alone. pub fn written(scope: &str) -> impl Iterator { scope .split_whitespace() .filter_map(|t| t.strip_prefix("repo:")) .filter(|c| !c.contains('?')) } /// The scope asked first of an instance whose apps name `sets`, `asked` /// what its `views` do: `atproto`, each set's `include:`, and what of /// `asked` no set holds; and for a service a set's methods are called at, /// each method the views call there outside the set's namespace, which /// it cannot list (Grain's views report to Grain's AppView with /// `com.atproto.moderation.createReport`). None where no app names a set. pub fn including(views: &Views, asked: &str, sets: &[Include]) -> Option { if sets.is_empty() { return None; } let mut tokens: Vec = vec!["atproto".to_string()]; tokens.extend(sets.iter().map(Include::token)); for t in asked.split_whitespace().filter(|t| *t != "atproto") { match sets.iter().find(|s| s.holds(t)) { None => tokens.push(t.to_string()), Some(s) if !t.starts_with("repo:") => { let service = s.service.as_deref().unwrap_or_default(); let outside = views.methods_of(service).into_iter(); let outside = outside.filter(|m| !s.within(m)); tokens.extend(outside.map(|m| format!("rpc:{m}?aud={}", aud(service)))); } Some(_) => {} } } Some(tokens.join(" ")) } /// Whether `scope` asks for a permission set. pub fn includes(scope: &str) -> bool { scope.split_whitespace().any(|t| t.starts_with("include:")) } /// What `asked`, what the views do, asks that `set` would hold /// (`Include::holds`) but its lexicon `doc` does not grant: each a line. /// A write is granted by a `repo` permission listing its collection with /// every action (none named is all), a delete by one with `delete`; a /// service's methods in the set's namespace, by an `rpc` permission /// inheriting the include's audience and listing each method the views /// call there (`Views::methods_of`). Those outside it are asked for /// directly (`including`). pub fn ungranted(views: &Views, asked: &str, set: &Include, doc: &Value) -> Vec { let main = &doc["defs"]["main"]; if main["type"] != "permission-set" { return vec![format!("{} is not a permission set", set.nsid)]; } let granted = main["permissions"] .as_array() .map_or(&[][..], Vec::as_slice); let listed = |v: &Value, x: &str| v.as_array().is_some_and(|a| a.iter().any(|i| i == x)); let repo = |collection: &str, action: &str| { granted.iter().any(|p| { p["resource"] == "repo" && listed(&p["collection"], collection) && (p["action"].is_null() || listed(&p["action"], action)) }) }; let rpc = |method: &str| { granted .iter() .any(|p| p["resource"] == "rpc" && p["inheritAud"] == true && listed(&p["lxm"], method)) }; let mut out = Vec::new(); for t in asked.split_whitespace().filter(|t| set.holds(t)) { let Some(c) = t.strip_prefix("repo:") else { let service = set.service.as_deref().unwrap_or_default(); let methods = views.methods_of(service).into_iter(); let missing = methods.filter(|m| set.within(m) && !rpc(m)); out.extend(missing.map(|m| format!("{} does not grant rpc:{m}", set.nsid))); continue; }; let (c, actions) = match c.split_once("?action=") { Some((c, a)) => (c, vec![a]), None => (c, vec!["create", "update", "delete"]), }; if !actions.iter().all(|a| repo(c, a)) { out.push(format!("{} does not grant {t}", set.nsid)); } } out } impl crate::Hud { /// What the views served do that the permission sets their apps name /// don't grant (`ungranted`), each a line, as each set resolves /// (`lexicon_doc`: kept a day, as an account's server keeps it); a set /// that resolves to nothing, said so. pub async fn sets_ungranted(&self) -> Vec { let views = crate::view::views(); let mut out = Vec::new(); for set in views.sets() { match self.lexicon_doc(&set.nsid).await { Some(doc) => out.extend(ungranted(views, &self.config.oauth_scope, set, &doc)), None => out.push(format!("{} does not resolve", set.nsid)), } } out } /// Each of `sets_ungranted`, logged as a warning: as HUD starts, so its /// operator hears what a view does that its app's set has yet to grant. pub async fn check_sets(self: std::sync::Arc) { for line in self.sets_ungranted().await { tracing::warn!(line, "a permission set does not grant what a view does"); } } } /// The permission to write `collection`'s records. fn write(collection: &str) -> String { format!("repo:{collection}") } /// The permission to delete `collection`'s records, and no more. fn delete(collection: &str) -> String { format!("repo:{collection}?action=delete") } /// Whether `scope` asks to delete `collection`'s records: to write them, /// or to delete them alone. pub fn deletes(scope: &str, collection: &str) -> bool { writes(scope, collection) || has(scope, &delete(collection)) } /// A service (`did:…#fragment`) as a permission's `aud`, a query /// parameter's value: a `did:web`'s own `%` (its port's `%3A`) escaped, as /// its `#` is. fn aud(service: &str) -> String { service.replace('%', "%25").replace('#', "%23") } /// The permission to call any method of `service` (`did:…#fragment`). fn call(service: &str) -> String { format!("rpc?lxm=*&aud={}", aud(service)) } /// The permission to call `method` of any service. fn any_audience(method: &str) -> String { format!("rpc:{method}?aud=*") } /// Whether `scope` asks to write `collection`'s records. pub fn writes(scope: &str, collection: &str) -> bool { has(scope, &write(collection)) } /// Whether `scope` asks to call `service` as the account. pub fn calls(scope: &str, service: &str) -> bool { has(scope, &call(service)) } /// Whether `scope` asks to tell feed generators what was read /// (`interactions`), as an instance whose views report interactions does. pub fn sends_interactions(scope: &str) -> bool { has(scope, &any_audience(interactions::SEND)) } fn has(scope: &str, token: &str) -> bool { scope.split_whitespace().any(|t| t == token) } /// Whether a sign-in that asked for `then` was asked for less than `now`, /// what HUD asks for now: some permission of `now` it did not ask for. /// Signing in again grants the rest. Compared with what was asked, not what /// was granted, as a PDS drops a permission it does not know (spaces). pub fn behind(then: &str, now: &str) -> bool { now.split_whitespace().any(|t| !has(then, t)) } #[cfg(test)] mod tests { use super::*; use crate::view; use std::path::Path; /// The scope of the instance the tests serve: the workspace, the /// bundled views and Grain's. fn full(spaces: bool) -> String { asked(view::views(), true, spaces) } /// Grain's apps (`view::GRAIN_APPS`) served alone, with no workspace. fn grain_alone() -> Views { crate::operator::load(Path::new(view::GRAIN_APPS), false) .unwrap() .views } #[test] fn asks_for_what_hud_does() { let s = full(false); assert!(s.starts_with("atproto ")); assert!(!s.contains("transition:")); assert!(writes(&s, "app.bsky.feed.like"), "an Action's create"); assert!( writes(&s, "social.grain.gallery.item"), "a Compose's writes" ); assert!(writes(&s, "place.hud.theme")); assert!(!writes(&s, "app.bsky.graph.follow"), "no view writes it"); assert!(calls(&s, "did:web:api.bsky.chat#bsky_chat")); assert!(calls(&s, "did:web:knotless.dev#knotless_appview")); assert!(!calls(&s, "did:web:elsewhere.example#svc")); assert!(has(&s, "rpc:app.bsky.actor.getPreferences?aud=*")); assert!(sends_interactions(&s)); assert!(has(&s, "blob:image/heic")); assert!(!s.contains("space:")); assert!(full(true).ends_with(&format!(" {SPACE_SCOPE}"))); let collections: Vec<&str> = written(&s).collect(); assert!(collections.contains(&"place.hud.theme")); assert!(collections.iter().all(|c| writes(&s, c))); } /// An instance serving Grain's apps alone asks for what they do: their /// collections, their service, the pictures their composers upload; /// no theme, nothing of Bluesky's, nothing of any audience. #[test] fn an_apps_instance_asks_for_its_apps_alone() { let views = grain_alone(); let s = asked(&views, false, false); let grain = [ "actor.profile", "comment", "favorite", "gallery", "gallery.item", "graph.block", "graph.follow", "photo", "photo.exif", "story", ] .map(|c| format!("repo:social.grain.{c}")); let blobs = pds::IMAGE_TYPES.map(|m| format!("blob:{m}")); let want: Vec = ["atproto".to_string()] .into_iter() .chain(grain) .chain(blobs) .chain(["rpc?lxm=*&aud=did:web:grain.social%23grain_appview".to_string()]) .collect(); assert_eq!(s, want.join(" ")); assert!(!s.contains("aud=*") && !s.contains("app.bsky") && !s.contains("place.hud")); assert!(!sends_interactions(&s)); // Delete account's collections are all written: nothing deleted // alone, its groups' records not asked for at all. assert!(!s.contains("?action=delete")); assert!(deletes(&s, "social.grain.photo") && !deletes(&s, "social.grain.group.item")); assert!(!deletes(&s, "app.bsky.feed.post")); // The workspace adds people's themes alone; spaces, theirs. let with = asked(&views, true, true); let more: Vec<&str> = with.split_whitespace().filter(|t| !has(&s, t)).collect(); assert_eq!(more, ["repo:place.hud.theme", SPACE_SCOPE]); assert!(!behind(&with, &s)); // Nothing served asks for nothing but to sign in. assert_eq!(asked(&Views::none(), false, false), "atproto"); } /// The bundled views of `ids` served alone. fn only(ids: &[&str]) -> Views { let all = Views::built_in(); let some = all.all().iter().filter(|b| ids.contains(&b.id.as_str())); Views::none().with(some.cloned().collect()) } /// A view that draws feeds by name brings the preferences' permission /// and the AppView's; one reporting interactions, theirs; a composer /// of pictures or a link's card, the pictures'. #[test] fn a_views_needs_bring_their_permissions() { let appview = "rpc?lxm=*&aud=did:web:api.bsky.app%23bsky_appview"; let feeds = asked(&only(&["bsky-feed-generators"]), false, false); assert_eq!( feeds, format!("atproto {appview} rpc:app.bsky.actor.getPreferences?aud=*") ); let feed = only(&["bsky-feed"]); assert!(feed.names_feeds() && feed.sends_interactions() && !feed.uploads()); let s = asked(&feed, false, false); assert!(sends_interactions(&s), "{s}"); assert!( s.ends_with(" rpc:app.bsky.feed.sendInteractions?aud=*"), "{s}" ); // Bluesky's app composes posts with pictures and a link's card. let app = only(&["bsky-app"]); assert!(app.uploads() && !app.names_feeds() && !app.sends_interactions()); let s = asked(&app, false, false); assert!(writes(&s, "app.bsky.feed.post") && has(&s, "blob:image/png")); assert!(!s.contains("aud=*"), "{s}"); } #[test] fn no_permission_calls_anything_anywhere() { // A PDS refuses an rpc permission whose method and audience are // both any. for t in full(true) .split_whitespace() .filter(|t| t.starts_with("rpc")) { let any_method = t.starts_with("rpc?lxm=*") || t.starts_with("rpc:*"); assert!(!(any_method && t.ends_with("aud=*")), "{t}"); } } #[test] fn a_did_web_with_a_port_is_escaped() { // As a PDS reads it back: did:web:localhost%3A2600#grain_appview, // not the did:web:localhost:2600 of a path. let s = call("did:web:localhost%3A2600#grain_appview"); assert_eq!( s, "rpc?lxm=*&aud=did:web:localhost%253A2600%23grain_appview" ); assert!(calls(&s, "did:web:localhost%3A2600#grain_appview")); } #[test] fn behind_what_is_asked_now() { let now = full(false); assert!(behind("atproto transition:generic", &now)); assert!(!behind(&now, &now)); let reordered: Vec<&str> = now.split_whitespace().rev().collect(); assert!(!behind(&reordered.join(" "), &now)); assert!(!behind(&full(true), &now), "asking for less is not behind"); assert!(behind(&now, &full(true))); // A sign-in made where the workspace was served is not behind an // instance serving its apps alone, which asks for less; the other // way, it is. let apps = asked(&grain_alone(), false, false); assert!(!behind(&now, &apps)); assert!(behind(&apps, &now)); } const GRAIN: &str = "did:web:grain.social#grain_appview"; /// Grain's set, as its app file names it. fn grain_set() -> Include { Include { nsid: "social.grain.authFull".into(), service: Some(GRAIN.into()), } } /// Grain's set as its lexicon has it: the copy beside Grain's apps. fn grain_doc() -> Value { let path = concat!( env!("CARGO_MANIFEST_DIR"), "/src/testdata/grain/social.grain.authFull.json" ); serde_json::from_slice(&std::fs::read(path).unwrap()).unwrap() } /// An instance serving Grain's apps alone asks for Grain's set, which /// holds its collections and its service's methods in its namespace, /// and directly for the pictures and the one method of another's its /// views call there, reporting; with the workspace, the rest of what /// it does too. With no set named, nothing is asked first. #[test] fn permission_sets_asked_first() { let views = grain_alone(); assert_eq!(views.sets(), [grain_set()]); let s = asked(&views, false, false); let first = including(&views, &s, views.sets()).unwrap(); assert_eq!( first, "atproto include:social.grain.authFull?aud=did:web:grain.social%23grain_appview \ blob:image/jpeg blob:image/png blob:image/webp blob:image/heic \ rpc:com.atproto.moderation.createReport?aud=did:web:grain.social%23grain_appview" ); assert!(includes(&first) && !includes(&s)); let all = asked(view::views(), true, false); let first = including(view::views(), &all, view::views().sets()).unwrap(); assert!( first.contains(" repo:app.bsky.feed.like ") && first.contains(" repo:place.hud.theme") ); assert!(!first.contains("repo:social.grain") && !first.contains(&call(GRAIN))); assert_eq!(including(&views, &s, &[]), None); // A set with no service holds no method; one holds nothing outside // its namespace, nor its namespace's own name. let bare = Include { nsid: "social.grain.authFull".into(), service: None, }; assert_eq!(bare.token(), "include:social.grain.authFull"); assert!(!bare.holds(&call(GRAIN)) && grain_set().holds(&call(GRAIN))); for t in [ "repo:social.grainy.photo", "repo:social.grain.", "blob:image/png", ] { assert!(!grain_set().holds(t), "{t}"); } assert!(grain_set().holds("repo:social.grain.group.item?action=delete")); } /// Grain's set grants what its views do; a set that grants less is /// said to, write by write, delete by delete and method by method. #[test] fn what_a_set_does_not_grant() { use serde_json::json; let views = grain_alone(); let s = asked(&views, false, false); let methods = views.methods_of(GRAIN); for m in [ "social.grain.feed.getFeed", "social.grain.notification.registerPush", "social.grain.sync.indexRecords", "social.grain.gallery.getDeletionPlan", "com.atproto.moderation.createReport", ] { assert!(methods.contains(m), "{m}"); } assert!(ungranted(&views, &s, &grain_set(), &grain_doc()).is_empty()); // A set that grants less: a write's every action, a delete, a method // listed with its audience inherited. let doc = json!({ "defs": { "main": { "type": "permission-set", "permissions": [ { "resource": "repo", "collection": ["social.grain.photo"], "action": ["create"] }, { "resource": "repo", "collection": ["social.grain.gallery"] }, { "resource": "repo", "collection": ["social.grain.story"], "action": ["delete"] }, { "resource": "rpc", "lxm": ["social.grain.feed.getFeed"] }, { "resource": "rpc", "inheritAud": true, "lxm": ["social.grain.actor.getProfile"] }, ] } } }); let deleting = format!( "{s} repo:social.grain.story?action=delete repo:social.grain.group.item?action=delete" ); let short = ungranted(&views, &deleting, &grain_set(), &doc); let says = |t: &str| short.contains(&format!("social.grain.authFull does not grant {t}")); assert!(says("repo:social.grain.photo") && !says("repo:social.grain.gallery")); assert!(says("repo:social.grain.group.item?action=delete")); assert!(!says("repo:social.grain.story?action=delete")); assert!( says("rpc:social.grain.feed.getFeed") && !says("rpc:social.grain.actor.getProfile") ); assert_eq!( ungranted( &views, &s, &grain_set(), &json!({ "defs": { "main": { "type": "query" } } }) ), ["social.grain.authFull is not a permission set"] ); let empty = json!({ "defs": { "main": { "type": "permission-set" } } }); assert!(ungranted(&views, &s, &grain_set(), &empty).len() > 3); } /// As HUD starts, each set named is resolved and held to the views; one /// that does not resolve is said to. #[tokio::test] async fn sets_checked_as_they_resolve() { use crate::net::tests::{Reply, fake_net}; let mut hud = crate::tests::hud_with("http://127.0.0.1:9", |_| {}); std::sync::Arc::get_mut(&mut hud).unwrap().net = fake_net(true, |_, _| Reply::NoSuchName).await; assert_eq!( hud.sets_ungranted().await, ["social.grain.authFull does not resolve"] ); hud.clone().check_sets().await; let doc = std::sync::Arc::new(grain_doc()); let day = std::time::Duration::from_secs(86_400); hud.lexicons .put("social.grain.authFull".into(), Some(doc), day); assert!(hud.sets_ungranted().await.is_empty()); } }