docs: document token scope roadmap for API token guardrails

Add roadmap documentation for fine-grained API token scopes across
the relevant source files. Scopes will enable read-only and
class-restricted tokens, providing server-side guardrails for MCP
and AI agent integrations without requiring MCP-layer changes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dnplkndll

docs/openapi.yaml

@@ -38,6 +38,13 @@ components:
         Workspace-scoped JWT. Payload: `{ account: AccountUuid, workspace: WorkspaceUuid, exp: number }`.
         Signed with `SERVER_SECRET` using HS256.
 
+        **Roadmap — Token Scopes:** Tokens currently grant full workspace access at the
+        user's role level. A future version will support an `extra.scopes` array in the JWT
+        payload to restrict tokens to specific operations and classes. Proposed scopes:
+        `read`, `write`, `read:<class>`, `write:<class>`, plus aliases like `read-only`.
+        This is the primary mechanism for guardrailing MCP and AI agent access.
+        See `server/account/src/types.ts` (ApiToken) for the full design.
+
     serverSecret:
       type: apiKey
       in: header

foundations/core/packages/token/src/token.ts

@@ -6,6 +6,9 @@ import serverPlugin from './plugin'
 
 /**
  * @public
+ *
+ * Roadmap: API token scopes will be carried in `extra.scopes` as a string array
+ * (e.g. `['read', 'write:tracker:*']`). See server/account/src/types.ts for design.
  */
 export interface Token {
   account: AccountUuid

pods/server/src/rpc.ts

@@ -167,6 +167,11 @@ export function registerRPC (app: Express, sessions: SessionManager, ctx: Measur
         return
       }
 
+      // Roadmap: enforce token scopes here. When ApiToken gains a scopes field
+      // (see server/account/src/types.ts), check decodedToken.extra?.scopes against
+      // the `method` parameter to reject disallowed operations (e.g. reject 'tx'
+      // for read-only tokens, filter find-all by allowed classes).
+
       let transactorRpc = rpcSessions.get(token)
 
       if (transactorRpc === undefined) {

server/account/src/operations.ts

@@ -2364,6 +2364,10 @@ async function deleteMailbox (
  * @returns Token ID, signed JWT, and expiration timestamp (ms)
  * @throws BadRequest if validation fails
  * @throws Forbidden if user lacks workspace access
+ *
+ * Roadmap: accept an optional `scopes` param and embed in the JWT via
+ * `generateToken(account, ws, { scopes }, undefined, { exp })`.
+ * See ApiToken type definition in types.ts for the proposed scope design.
  */
 async function createApiToken (
   ctx: MeasureContext,

server/account/src/types.ts

@@ -159,6 +159,45 @@ export interface WorkspaceJoinInfo {
 /**
  * Represents an API token record in the database.
  * Timestamps are in milliseconds since Unix epoch.
+ *
+ * ## Roadmap: Token Scopes
+ *
+ * Tokens currently grant full access at the user's workspace role level.
+ * A future `scopes` field would allow fine-grained access control:
+ *
+ * ```
+ * scopes?: ApiTokenScope[]
+ * ```
+ *
+ * ### Proposed scope format
+ *
+ * Scopes follow a `<permission>:<domain>` pattern:
+ *
+ * - **`read`** — find-all, load-model, account info (no mutations)
+ * - **`read:<class>`** — read restricted to a specific class
+ *   (e.g. `read:tracker:class:Issue`, `read:chunter:class:Channel`)
+ * - **`write`** — tx endpoint (create, update, remove)
+ * - **`write:<class>`** — mutations restricted to a specific class
+ *
+ * Convenience aliases:
+ * - **`read-only`** → `['read']` — safe default for MCP / AI agents
+ * - **`tracker`** → `['read:tracker:*', 'write:tracker:*']` — full tracker access
+ *
+ * ### Enforcement points
+ *
+ * 1. **JWT payload** — embed scopes in `extra.scopes` so they travel with the token
+ * 2. **REST middleware** (`pods/server/src/rpc.ts`) — reject `/tx` for read-only tokens;
+ *    filter `find-all` results by allowed classes
+ * 3. **Account service** — persist scopes in the `api_tokens` DB table
+ * 4. **UI** — scope picker in `ApiTokenCreatePopup.svelte`
+ *
+ * ### MCP integration
+ *
+ * Community MCP servers (e.g. dearlordylord/huly-mcp) pass the API token through
+ * to the same REST endpoints. Adding server-side scope enforcement here would
+ * automatically guardrail MCP tools without requiring MCP-layer changes. A read-only
+ * scoped token would let AI agents query freely but never mutate workspace data.
+ *
  * @public
  */
 export interface ApiToken {
@@ -171,6 +210,7 @@ export interface ApiToken {
   /** Milliseconds since epoch */
   expiresOn: number
   revoked: boolean
+  // Future: scopes?: ApiTokenScope[]
 }
 
 export interface Mailbox {