~ 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
140 lines · 16.6 KB Raw History

title: Sign-in section: HUD order: 6 summary: How HUD signs a person in with OAuth, and what a signed-in account adds to feeds, chats and procedures.

With sign-in on, HUD plays two OAuth roles, chained. To an MCP host it's the authorization server of its own /mcp. To the person's account server it's a confidential atproto OAuth client.

A signed-in call to /mcp acts as the account. That's what lets HUD write records, tell feeds what the person reads, go by saved feeds' names, open chats and call procedures.

The OAuth flow

HUD is the authorization server of its own /mcp, as MCP's authorization spec describes one. /.well-known/oauth-protected-resource/mcp names it, and /.well-known/oauth-authorization-server names its endpoints.

  1. A host names itself by a client ID metadata document (an https:// client_id, fetched and kept an hour). Or it registers at /oauth/register (public clients, https or loopback redirect URIs).
  2. The host sends the person to /oauth/authorize with PKCE (S256) and resource=<origin>/mcp.
  3. HUD's sign-in page names the client and asks for the person's handle. Some clients ask for the handle themselves and send it as login_hint, so HUD skips the page and goes straight to the account's server: HUD's own iOS app (/oauth/app-client.json), and an operator's app whose app file draws its own sign-in screen (signIn, the app's sign-in screen), for a client sent back to that app's domain or one under it over https (Grain's web app at next.grain.social), or to a loopback host where HUD_ALLOW_PRIVATE is on. If that fails (a handle that's no account, a server that refuses), HUD sends the person back to the client with error=access_denied and why in error_description, for its own screen to show. Any other client always gets the page, since it names the client and skipping it would let any client ride the consent the account's server remembers. A code sent back to an app's own domain reaches that app's server alone, which drew the screen that asked. HUD is a confidential atproto OAuth client to the account's server (/oauth/client-metadata.json, with its key at /oauth/jwks.json). It pushes the request (PAR, PKCE, DPoP, private_key_jwt) and sends the person there to sign in. The page also offers "Create one" for a person with no account (see creating an account).
  4. Back at /oauth/callback, HUD checks the answer's state and iss and exchanges the code. It checks the account is the one named (any account, for a new one) and resolves it again, since the authorization server of its PDS must be the one that answered. Then it keeps the session and sends the host its own code.
  5. The host exchanges that code at /oauth/token for HUD's tokens.

HUD's tokens are opaque. The access token lasts an hour and the refresh token 30 days, rotated at each use. If a replaced refresh token is used again, HUD ends the session. /oauth/revoke ends a session and revokes its atproto refresh token too. Deleting a person's HUD data ends every session of theirs the same way (deleting your data).

Creating an account

A person with no atproto account can make one. The workspace's dialog and the MCP sign-in page each offer "Create one". HUD pushes a request to the authorization server of the sign-up PDS (HUD_SIGN_UP_PDS, by default https://selfhosted.social) as it does for a sign-in, with prompt=create and no login_hint, and sends the person to that server's sign-up page. The account isn't known until the answer comes back: the callback takes the account the token answer names (sub), resolves it, and requires the authorization server of its PDS to be the one that answered. From there it's a sign-in like any other.

  • The workspace's dialog sends {"create": true} to POST /workspace/signin (details: the workspace).
  • The MCP sign-in page's "Create one" is a second submit button in its form (create=1).
  • A client that names the account itself (HUD's own app, an app's web client with its own sign-in screen) may send prompt=create to /oauth/authorize, and HUD skips its page, as it does for login_hint. If the sign-up PDS can't be used, HUD sends the person back saying why. Any other client's prompt=create is ignored, and it gets the page. HUD's iOS app doesn't offer it for now.

The sign-up PDS is run by others, under their own terms. HUD serves its own terms, privacy policy and community guidelines at /terms, /privacy and /guidelines, whether sign-in is on or off. The sign-in page, the dialog and the app link to them.

Calls made signed in

A call to /mcp with HUD's access token belongs to the account. Writes go to its PDS with its DPoP-bound token. HUD refreshes that token when it expires or is refused, one refresh at a time, and a refused refresh ends the session.

If a tool needs an account and is called without one, HUD answers HTTP 401 with WWW-Authenticate: Bearer resource_metadata="…", scope="hud". A token that no longer works gets error="invalid_token", so the host signs in. Tools that need no account answer as before.

Results made signed in say cacheScope: private.

What HUD asks for

HUD asks an account's server for what it does and no more, as atproto's permissions (never transition:generic). It reads the scope from the views it serves when it starts (hud_core::scope::asked). That's the operator's with the bundled ones, or the operator's alone with HUD_WORKSPACE=off (running HUD). So a view added asks for what it needs at once, and an instance that serves one app asks for that app's needs alone.

PermissionFor
repo:<collection>each collection a served view writes (an Action's create, a Compose's writes), and place.hud.theme where the workspace is served
repo:<collection>?action=deleteeach collection a served view's deletes names that no served view writes (Action)
blob:<type>the images a composer uploads (JPEG, PNG, WebP, HEIC), where a served Compose has a photos or card field
rpc?lxm=*&aud=<service>any method of each service a served view names, and each service an app file's push or refresh calls. Bluesky's AppView comes with saved feeds and interactions too.
rpc:app.bsky.actor.getPreferences?aud=*saved feeds, where a served view draws app.bsky.feed.getFeed or getFeedGenerators. The PDS answers it itself and checks it against whichever AppView it's set up with, so the audience is any.
rpc:app.bsky.feed.sendInteractions?aud=*telling a feed's generator what was read, whoever runs it, where a served view reports interactions
space:place.hud.workspace?…canvases in people's spaces, with HUD_SPACES=on (the workspace)

Grain's instance (next.grain.social) serves Grain's apps alone. Its views write ten social.grain.* collections, upload photos and call Grain's AppView, so what they do is exactly this:

atproto repo:social.grain.actor.profile repo:social.grain.comment repo:social.grain.favorite repo:social.grain.gallery repo:social.grain.gallery.item repo:social.grain.graph.block repo:social.grain.graph.follow repo:social.grain.photo repo:social.grain.photo.exif repo:social.grain.story blob:image/jpeg blob:image/png blob:image/webp blob:image/heic rpc?lxm=*&aud=did:web:grain.social%23grain_appview

A query to a service no served view names goes as no one, and a write of a collection none writes is refused (tools). /oauth/client-metadata.json declares the whole scope, with the permission sets below, since an authorization server refuses a sign-in asking for anything its client didn't declare. A PDS may keep a copy of that document for a few minutes, so sign-ins can fail with invalid_scope for a little while after a change that adds a permission.

Permission sets

A scope like that is fixed at sign-in. So every collection or method an app adds has everyone sign in again. An app file can name atproto permission sets instead (permissions, the operator's views). A permission set is a lexicon the app publishes, listing its collections and its methods. The account's server resolves it as the person signs in, and again as HUD refreshes their token. So a set that grows reaches people already signed in, within the day a server may keep its copy.

Where the served apps name sets, HUD asks for them first:

PermissionFor
include:<set>?aud=<service>each set an app file names, its methods called at the service it names
the rest of the table abovewhat no set can hold: pictures (blob:), collections outside the set's namespace, other services, and methods of the set's service outside its namespace (Grain's views report to Grain's AppView with com.atproto.moderation.createReport)

So Grain's instance asks for this, with groups left out of Grain's set until they work:

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

A server that doesn't know permission sets, or can't resolve one now, refuses that request with invalid_scope. HUD then pushes the request again, asking for what the views do (the scope above), and the sign-in is held to that. The reference PDS, pds.js and zds all refuse so at PAR. Tranquil resolves a set only at its consent page, so a set it can't resolve fails the sign-in there, and HUD can't tell.

HUD still holds its own writes and calls to what the views do, so it uses nothing a set grants beyond that. As HUD starts, it resolves each set and logs a warning for each collection or method a view needs that the set doesn't grant (a permission set does not grant what a view does).

A server expands a set into the permissions it lists when it grants a token, so the token's scope never holds the include:. The reference PDS resolves the set again on every refresh, keeping its copy five minutes, and tranquil keeps one a day. pds.js and zds keep the expansion made at sign-in until the person signs in again. So when a PDS refuses a call for want of scope, HUD refreshes the token and tries once more. A sign-in that asked for a set more than a day ago and is still refused signs in again, for the set as it is now.

Signing in again

HUD keeps what each sign-in asked for. One that asked for less than HUD asks for now (one made before a view was added, or with transition:generic) is behind. A sign-in made with permission sets is held to what HUD asks with them, so a collection added to a set leaves it current. One that asked for more (made before an instance stopped serving its workspace) isn't behind. When its PDS refuses a call for want of scope, HUD has a sign-in that's behind sign in again:

  • An MCP host gets the 401 challenge, so it signs in again.
  • The workspace's methods answer HUD asks for more now than when you signed in: sign in again to allow this. getWorkspace says signInAgain: true, and the page and the iOS app show a bar to sign in again until they do.

A sign-in that asked for everything but was granted less gets a tool error naming the permission (Your sign-in does not allow repo:…), since signing in again wouldn't change it.

Feed interactions

Signed in, a reporting feed view tells its feed what the person reads, as Bluesky's app does. It batches the items seen, the items opened and asks for more or less like an item, and sends them through send_interactions.

HUD reads the feed's generator from the AppView (app.bsky.feed.getFeedGenerator, through the account's PDS, kept an hour). If the generator takes interactions, HUD sends them through the account's PDS to the generator's own service (app.bsky.feed.sendInteractions, atproto-proxy: <did>#bsky_fg). A feed that takes none gets { sent: 0, reason }, so the view stops.

Saved feeds

Signed in, the account's saved feeds go by name. HUD reads them from its preferences (app.bsky.actor.getPreferences, which its PDS answers). It uses savedFeedsPrefV2, else the older savedFeedsPref. The AppView names them (app.bsky.feed.getFeedGenerators), and HUD keeps them five minutes.

query app.bsky.feed.getFeed takes params.feed as a feed's name where its at-uri goes. HUD matches the name ignoring case and spaces, else the one name that holds it. Otherwise it's a tool error listing the saved feeds, pinned first. following (or timeline, home) is the timeline, app.bsky.feed.getTimeline.

query app.bsky.feed.getFeedGenerators takes params.feeds as saved or pinned for the account's own feeds, in their order. views/bsky-feed-generators.json draws them, and each card opens its feed. Signed out, either query asks the host to sign in.

Chats

Signed in, Bluesky chats go through the account's PDS to Bluesky's chat service (atproto-proxy: did:web:api.bsky.chat#bsky_chat).

views/bsky-chats.json draws chat.bsky.convo.listConvos. Each row shows the chat's name or members, the last message and who sent it, and the unread count. Each chat in the list has Mark read, and each row opens views/bsky-chat.json.

views/bsky-chat.json draws chat.bsky.convo.getMessages with Messages. It shows bubbles with the oldest at the top and the newest at the foot. The person's own messages sit on the right, and others' sit beside their faces from the answer's relatedProfiles. Earlier messages load at the top, and a box at the foot sends.

Starting a chat

A person starts a chat from an account's profile. Its Message button opens views/bsky-chat-with.json, which calls chat.bsky.convo.getConvoForMembers (the one-to-one chat with them, made if there's none). It joins the latest 50 messages from getMessages and draws them as a conversation, with the box. It has no earlier pages, so open the chat from Chats for those.

The button is a bundled view's head profile section (profile: { head: true }). It's drawn under the profile's head, untitled, for any account but the person's own, signed in. views/bsky-chat-availability.json asks chat.bsky.convo.getConvoAvailability whether the two can chat. It draws the button (a Link with style: "button") only where they can. So there's none on one's own profile, or for someone who takes no messages from them.

Procedures

Writes beyond records are procedures that a trusted view (bundled, or the operator's) calls, and only those:

  • An Action's call (Mark read, chat.bsky.convo.updateRead, and Grain's Pin feed, social.grain.actor.setPreference).
  • A Messages' send (chat.bsky.convo.sendMessage).
  • A Toggle's or a Choice's call (a Grain setting, social.grain.actor.setPreference).
  • An operator's app file's push, as its clients register a device for push (Grain's social.grain.notification.registerPush, in Push).

Each is { method, service, input }. The input is a template of bindings: {"$root": path}, {"$now": true}, {"$strongRef": path}, {"$join": [values]}, an array's edits ($with, $without, $move, in Action), in send {"$text": true} (what the person wrote), in a Toggle's or Choice's call {"$on": true} (what they switched it to, or chose), and in a push {"$token": true}, {"$appId": true} and {"$platform": true} (the device's).

The server resolves it into the tree with the rest of the view (_meta.ui), from a trusted view only, and send only when signed in. The client stamps $now, $text and $on and calls call_procedure. That tool sends a method of a service only if a trusted view calls it, or an operator's app file pushes with it (view::bundled_call). So an inline view, the model or anyone else reaching the tool can't send anything more. An Action's or select's deletes comes the same way, drawn as a call of its query: the tool asks that query only if a trusted view deletes what it plans (view::bundled_deletes), then deletes the plan in the account's own repository, of collections HUD asks to write or delete alone (Action).

HUD checks the input against the procedure's lexicon. It bundles one for every procedure a bundled view calls (just lexicons reads views/). It sends the call through the PDS with atproto-proxy, checks the answer against the output, and hands it back. It logs neither.

A sent message shows at once, and HUD reads the conversation again so the message arrives as the view draws it. Messages are plain text only (no links or mentions detected).