chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.4.0 Latest 5 packages
0
0
//! 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<String>,
}
impl Include {
/// Its permission: `include:<nsid>`, 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<Item = &str> {
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<String> {
if sets.is_empty() {
return None;
}
let mut tokens: Vec<String> = 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<String> {
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<String> {
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<Self>) {
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<String> = ["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());
}
}