~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
590 lines · 24.3 KB Raw History
//! 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());
    }
}