The OpenAPI description shows an anonymous reader only the routes it may call; admin routes appear only to an admin #11290

GET /contract/openapi.json (and /openapi.json, /api/v1/openapi.json) now lists only the routes the caller's role may call. A request with no credential gets the x-role: anonymous rows, a member's token or session adds the member rows, and a site admin gets all three. Before this, anyone could read all ~410 rows, 80 of them admin-only.

What changed

• src/contract/openapi.ts: openapi() takes a role and keeps only the rows that role may call. The tag list only includes tags that still have rows, so an anonymous reader doesn't see tags that only admin rows carry.
• src/contract/served.ts:

- The new roleOf() works out the role from the request's signed-in user. - The cache is keyed by (version, origin, role) for the whole document and by (version, origin, role, tag) for ?tag= slices. Each limit is three times what it was, one share per role. - The ETag hashes the role's own text, so it differs per role and an admin's tag never gets a 304 for an anonymous request. - Every response carries vary: accept-encoding, authorization, cookie. Only the anonymous answer is cache-control: public; the other two are private.

• docs/MCP.md: the Contract entry says the document is cut to the caller's role.

Tests

• New test/contract-openapi-roles.test.ts asks as anonymous, member and admin. It checks the row counts for each role, fails if any admin row or admin-only tag reaches the first two, and checks the per-role ETags, the 304, the cache headers and ?tag= slices per role. All three of its tests fail against the old code.
• I changed 15 existing test files whose expectations were right before and wrong now:

- In test/contract-openapi-tags.test.ts, a request with no credential is now compared with the anonymous cut instead of the whole document. - 14 suites fetched the document anonymously to check that a member or admin route is described. They now ask as a site admin through a new helper, test/helpers/openapi-doc.ts. The mcp test that checks the /api/v1/openapi.json redirect is unchanged.

Not done

• The /api page (src/web/pages/api.ts) and the terminal's API screen still call openapiText with its default role, admin, so /api still shows every row to anyone. Cutting it per role needs its own per-role cache; that's a follow-up issue.
• No new MCP tool.

Checks run

• bun scripts/gate.ts, bun x tsc --noEmit and bun test test/mcp-size.test.ts pass.
• bun scripts/fast.ts named 1,848 files, over its budget, so I picked the tests myself: every test file that mentions the OpenAPI document, 943 tests, all passing.
• I didn't run bun scripts/design-lint.ts, since nothing under src/web/ changed.

To try it: curl $ORIGIN/contract/openapi.json | jq '[.paths[][]."x-role"] | unique' should return ["anonymous"]. The same request with an admin's authorization: Bearer … header returns all three roles.

🤖 Generated with Claude Code

Closes #11286

GET /contract/openapi.json (and /openapi.json, /api/v1/openapi.json) now lists only the routes the caller's role may call. A request with no credential gets the x-role: anonymous rows, a member's token or session adds the member rows, and a site admin gets all three. Before this, anyone could read all ~410 rows, 80 of them admin-only.

What changed

• src/contract/openapi.ts: openapi() takes a role and keeps only the rows that role may call. The tag list only includes tags that still have rows, so an anonymous reader doesn't see tags that only admin rows carry.
• src/contract/served.ts:

- The new roleOf() works out the role from the request's signed-in user. - The cache is keyed by (version, origin, role) for the whole document and by (version, origin, role, tag) for ?tag= slices. Each limit is three times what it was, one share per role. - The ETag hashes the role's own text, so it differs per role and an admin's tag never gets a 304 for an anonymous request. - Every response carries vary: accept-encoding, authorization, cookie. Only the anonymous answer is cache-control: public; the other two are private.

• docs/MCP.md: the Contract entry says the document is cut to the caller's role.

Tests

• New test/contract-openapi-roles.test.ts asks as anonymous, member and admin. It checks the row counts for each role, fails if any admin row or admin-only tag reaches the first two, and checks the per-role ETags, the 304, the cache headers and ?tag= slices per role. All three of its tests fail against the old code.
• I changed 15 existing test files whose expectations were right before and wrong now:

- In test/contract-openapi-tags.test.ts, a request with no credential is now compared with the anonymous cut instead of the whole document. - 14 suites fetched the document anonymously to check that a member or admin route is described. They now ask as a site admin through a new helper, test/helpers/openapi-doc.ts. The mcp test that checks the /api/v1/openapi.json redirect is unchanged.

Not done

• The /api page (src/web/pages/api.ts) and the terminal's API screen still call openapiText with its default role, admin, so /api still shows every row to anyone. Cutting it per role needs its own per-role cache; that's a follow-up issue.
• No new MCP tool.

Checks run

• bun scripts/gate.ts, bun x tsc --noEmit and bun test test/mcp-size.test.ts pass.
• bun scripts/fast.ts named 1,848 files, over its budget, so I picked the tests myself: every test file that mentions the OpenAPI document, 943 tests, all passing.
• I didn't run bun scripts/design-lint.ts, since nothing under src/web/ changed.

To try it: curl $ORIGIN/contract/openapi.json | jq '[.paths[][]."x-role"] | unique' should return ["anonymous"]. The same request with an admin's authorization: Bearer … header returns all three roles.

🤖 Generated with Claude Code

The OpenAPI document is now cut to the reader's role wherever it is shown, not only at /contract/openapi.json. A signed-out reader sees only the routes open to anyone, a member also sees member routes, and admin routes appear only to an admin.

What changed

• No default role. openapi, openapiText and openapiSliceText (in src/contract/openapi.ts and src/contract/served.ts) now take the role as a required argument, so every caller has to choose one. Before, the default was admin, which is how the next two callers leaked every row. Tests that want the whole document now pass "admin" explicitly; that is most of the files in this diff.
• The /api page (src/web/pages/api.ts) now reads the document as roleOf(ctx.auth). Its cache keeps one copy per role, so the three roles don't overwrite each other's cache entry.
• The terminal's API screen (src/tui/screens/api.ts) now reads the document as roleOf(session). A guest gets the anonymous rows, the same as a signed-out page.

Tests

• test/api-reference.test.ts:

- /api signed out lists every anonymous route and no admin or member route. - The "every route appears" check now signs in as an admin. - The terminal screen counts only the anonymous operations for a guest and every operation for an admin.

• test/contract-openapi-roles.test.ts: real HTTP requests with minted bearer tokens, not a faked ctx.auth.

- A member's token gets private caching and the anonymous plus member rows. - An admin's token gets every row. - With no token, the answer is public and has only the anonymous rows.

About the preview returning public, max-age=300: I think that was correct. The preview runs as its own forge with its own accounts, so a token issued by forge.open-platform.sh matches no account there and the caller is treated as anonymous. The token test above shows that a token the serving forge does know reaches roleOf with the user set.

Checks run: bun x tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts are clean. scripts/fast.ts named 1853 files, too many to run here, so I ran 40 files myself and all pass: every changed test file, all openapi* and contract-openapi* tests, mcp, api-page*, and the suites that request /api.

Try it: open /api signed out and look for any /api/v1/admin/… route; there should be none. Sign in as a site admin and every operation is back.

🤖 Generated with Claude Code