--- 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=/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](views.md#the-apps-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](#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](workspace.md#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](workspace.md#signing-in-to-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](views.md#the-operators-views) with the bundled ones, or the operator's alone with `HUD_WORKSPACE=off` ([running HUD](running.md#environment-variables)). 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. | Permission | For | | --- | --- | | `repo:` | each collection a served view writes (an `Action`'s `create`, a `Compose`'s `writes`), and `place.hud.theme` where the workspace is served | | `repo:?action=delete` | each collection a served view's `deletes` names that no served view writes ([Action](views.md#action)) | | `blob:` | the images a composer uploads (JPEG, PNG, WebP, HEIC), where a served `Compose` has a `photos` or `card` field | | `rpc?lxm=*&aud=` | 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](workspace.md#where-canvases-live)) | 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](tools.md#writes)). `/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](https://atproto.com/specs/permission#permission-sets) instead (`permissions`, [the operator's views](views.md#permission-sets)). 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: | Permission | For | | --- | --- | | `include:?aud=` | each set an app file names, its methods called at the `service` it names | | the rest of the table above | what 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: #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](views.md#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](views.md#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](views.md#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).