Public: anyone can read this; the crew can change it.
The role-aware manifest on a page lists only actions the caller can take, and a test compares it to the caller's permissions #13696
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13683-the-role-aware-manifest-on-a-page-lists → main 3 commits fork 4 threads · 4 unresolved
1 file
changed +124
−11
test/manifest-roles.test.ts +124 −11
| @@ -2,8 +2,11 @@ | ||
| 2 | 2 | * An agent that reads a page learns what it may do, cheaply (#13486): the |
| 3 | 3 | * manifest omits every tool its caller cannot call, and its size per role |
| 4 | 4 | * is held under a ceiling written here. Raise a ceiling only with a reason |
| 5 | * in the pull; the cheap answer is the point. It calls `manifestFor` directly: | |
| 6 | * the served route and the per-role lists are held by here-roles.test.ts. | |
| 5 | * in the pull; the cheap answer is the point. It calls `manifestFor`, then follows | |
| 6 | * every listed action over HTTP, one fresh forge per role, and holds that none is | |
| 7 | * refused, missing or broken. A compound route ("POST a, then POST b") is followed | |
| 8 | * only at its first step: a deliberate limit, the second needs the first's answer. | |
| 9 | * The served route and the per-role lists are held by here-roles.test.ts. | |
| 7 | 10 | */ |
| 8 | 11 | import { afterAll, beforeAll, expect, test } from "bun:test"; |
| 9 | 12 | import { mkdtemp, rm } from "node:fs/promises"; |
| @@ -14,6 +17,12 @@ import { manifestFor } from "../src/actions/here.ts"; | ||
| 14 | 17 | import { createApp, type App } from "../src/app.ts"; |
| 15 | 18 | import { createUser, type User } from "../src/core/users.ts"; |
| 16 | 19 | import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts"; |
| 20 | import { openIssue } from "../src/actions/issues.ts"; | |
| 21 | import { openPull } from "../src/actions/pulls.ts"; | |
| 22 | import { commitToBranch } from "../src/actions/repos.ts"; | |
| 23 | import { getRepo } from "../src/core/repos.ts"; | |
| 24 | import { createToken } from "../src/core/tokens.ts"; | |
| 25 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 17 | 26 | import { promote } from "./helpers/members.ts"; |
| 18 | 27 | |
| 19 | 28 | /** Characters of the manifest's JSON, per role, on one public app's page. */ |
| @@ -33,13 +42,29 @@ const MEMBER_ONLY = ["tell the crew", "approve a pull", "merge a pull"]; | ||
| 33 | 42 | const WRITER_MAY = new Set([...OUTSIDER_MAY, ...MEMBER_ONLY]); |
| 34 | 43 | const ADMIN_MAY = new Set([...WRITER_MAY, "change settings"]); |
| 35 | 44 | |
| 36 | let dataDir = ""; | |
| 37 | let app: App; | |
| 38 | const who: Record<string, User> = {}; | |
| 45 | interface Fixture { | |
| 46 | readonly app: App; | |
| 47 | readonly who: Record<string, User>; | |
| 48 | readonly dataDir: string; | |
| 49 | } | |
| 50 | interface World extends Fixture { | |
| 51 | readonly servers: Servers; | |
| 52 | readonly tokens: Record<string, string>; | |
| 53 | /** An open issue and an open pull on `acme/pub`, for the `{number}` routes. */ | |
| 54 | readonly issue: number; | |
| 55 | readonly pull: number; | |
| 56 | } | |
| 57 | const dirs: string[] = []; | |
| 58 | /** Every forge opened, closed in afterAll: a merge's fork-following runs on after the request. */ | |
| 59 | const apps: App[] = []; | |
| 39 | 60 | |
| 40 | beforeAll(async () => { | |
| 41 | dataDir = await mkdtemp(join(tmpdir(), "forge-manifest-roles-")); | |
| 42 | app = createApp({ dataDir, port: 0 }); | |
| 61 | /** One forge with four people and one public app, `acme/pub`: no server, no git history. */ | |
| 62 | async function fixture(): Promise<Fixture> { | |
| 63 | const dataDir = await mkdtemp(join(tmpdir(), "forge-manifest-roles-")); | |
| 64 | dirs.push(dataDir); | |
| 65 | const app = createApp({ dataDir, port: 0 }); | |
| 66 | apps.push(app); | |
| 67 | const who: Record<string, User> = {}; | |
| 43 | 68 | const mk = async (name: string, first = false) => { |
| 44 | 69 | const made = await createUser(app.db, { |
| 45 | 70 | origin: "seed", trusted: true, username: name, email: `${name}@forge.local`, |
| @@ -60,11 +85,38 @@ beforeAll(async () => { | ||
| 60 | 85 | addTeamMember(app.db, team.value, who["wes"]!.id); |
| 61 | 86 | const made = await newApp(app, who["wren"]!, { name: "pub", owner: "acme", visibility: "public" }); |
| 62 | 87 | if (!made.ok) throw new Error(String(made.error)); |
| 63 | }, 60_000); | |
| 88 | return { app, who, dataDir }; | |
| 89 | } | |
| 90 | ||
| 91 | /** The fixture with an issue, a pull, a listening server and a token each: what following needs. */ | |
| 92 | async function world(): Promise<World> { | |
| 93 | const { app, who, dataDir } = await fixture(); | |
| 94 | const repo = getRepo(app.db, "acme", "pub"); | |
| 95 | if (!repo) throw new Error("no repo"); | |
| 96 | const issue = openIssue(app, who["wren"]!, repo, { title: "A question" }); | |
| 97 | if (!issue.ok) throw new Error(String(issue.error)); | |
| 98 | const pushed = await commitToBranch(app, who["wren"]!, repo, { | |
| 99 | branch: "idea", message: "An idea", files: [{ path: "IDEA.md", content: "idea\n" }], | |
| 100 | }); | |
| 101 | if (!pushed.ok) throw new Error(JSON.stringify(pushed.error)); | |
| 102 | const pull = await openPull(app, who["wren"]!, repo, { title: "An idea", baseBranch: "main", headBranch: "idea" }); | |
| 103 | if (!pull.ok) throw new Error(String(pull.error)); | |
| 104 | const servers = await serve(app); | |
| 105 | const tokens: Record<string, string> = {}; | |
| 106 | for (const n of Object.keys(who)) tokens[n] = createToken(app.db, who[n]!.id, "t", "admin").token; | |
| 107 | return { app, servers, who, tokens, dataDir, issue: issue.value.number, pull: pull.value.number }; | |
| 108 | } | |
| 109 | ||
| 110 | let app: App; | |
| 111 | let who: Record<string, User>; | |
| 112 | ||
| 113 | beforeAll(async () => { | |
| 114 | ({ app, who } = await fixture()); | |
| 115 | }); | |
| 64 | 116 | |
| 65 | 117 | afterAll(async () => { |
| 66 | app.close(); | |
| 67 | await rm(dataDir, { recursive: true, force: true }); | |
| 118 | for (const a of apps) a.close(); | |
| 119 | for (const d of dirs) await rm(d, { recursive: true, force: true }); | |
| 68 | 120 | }); |
| 69 | 121 | |
| 70 | 122 | function manifest(viewer: User | undefined) { |
| @@ -102,3 +154,64 @@ test("the manifest stays under its ceiling for each role", () => { | ||
| 102 | 154 | `the ${role} manifest is ${sizes[role]} characters, over its ${CEILINGS[role]} ceiling`, |
| 103 | 155 | ).toBeLessThanOrEqual(CEILINGS[role]); |
| 104 | 156 | }); |
| 157 | ||
| 158 | /** | |
outdated
Remove 401 from ALLOWED: a listed action answering 401 is a refused caller and must fail the test. Keep only statuses that mean the caller was accepted (400/409/422 for the empty body, 2xx, 302). |
||
| 159 | * What following an action may answer: it ran, was queued, redirected, or the | |
| 160 | * route took the caller and then refused the empty body or a state the fresh | |
| 161 | * fixture is not in. Never 401 or 403 (refused the caller), 404 (the route is | |
| 162 | * gone or mistyped) or a 5xx. | |
| 163 | */ | |
| 164 | const ALLOWED = new Set([200, 201, 202, 204, 302, 400, 409, 422]); | |
| 165 | /** Actions with no HTTP route, by what the manifest says (the MCP-only ones). */ | |
| 166 | const MCP_ONLY = new Set<string>(["tell the crew"]); | |
| 167 | /** | |
| 168 | * The only 401s allowed: what an anonymous caller is offered marked | |
| 169 | * `account: true`, the manifest saying "sign in first". For these the 401 is the | |
| 170 | * promise kept, so it is required, not merely allowed; any other 401 fails. | |
| 171 | */ | |
| 172 | const ANONYMOUS_NEEDS_ACCOUNT = new Set<string>(["open an issue", "comment", "offer a change", "make it yours"]); | |
| 173 | ||
| 174 | test("no action a role is offered is refused when followed", async () => { | |
| 175 | const skipped = new Set<string>(); | |
| 176 | const accountFirst = new Set<string>(); | |
| 177 | // A fresh forge per role: following runs real mutations (forks, merges, | |
| 178 | // settings), so no role's result may depend on what another one did. | |
| 179 | for (const role of [undefined, "nina", "wes", "wren"]) { | |
| 180 | const w = await world(); | |
| 181 | const m = manifestFor(w.app, role === undefined ? undefined : w.who[role], undefined, "https://forge.test", "/acme/pub"); | |
| 182 | if (!m.ok) throw new Error("not_found"); | |
| 183 | for (const a of m.value.can) { | |
| 184 | if (a.http === undefined) { | |
| 185 | skipped.add(a.do); | |
| 186 | continue; | |
| 187 | } | |
| 188 | const [method, path] = a.http.split(", then ")[0]!.split(" ") as [string, string]; | |
| 189 | const headers: Record<string, string> = { origin: w.servers.url, "content-type": "application/json" }; | |
| 190 | if (role !== undefined) headers["authorization"] = `Bearer ${w.tokens[role]}`; | |
| 191 | const res = await fetch(`${w.servers.url}${path.replaceAll("{number}", String(path.includes("/issues/") ? w.issue : w.pull))}`, { | |
| 192 | method, | |
| 193 | headers, | |
| 194 | redirect: "manual", | |
| 195 | ...(method === "GET" ? {} : { body: "{}" }), | |
| 196 | }); | |
| 197 | await res.text(); | |
| 198 | const said = `${role ?? "anonymous"} was offered "${a.do}" (${a.http}) and got ${res.status}`; | |
| 199 | if (role === undefined && a.account === true) { | |
| 200 | accountFirst.add(a.do); | |
| 201 | expect(res.status, said).toBe(401); | |
| 202 | continue; | |
| 203 | } | |
| 204 | expect(ALLOWED.has(res.status), said).toBe(true); | |
| 205 | // the page itself must answer, whatever the app behind it is doing | |
| 206 | if (a.do === "read") expect(res.status, said).toBe(200); | |
| 207 | } | |
| 208 | w.servers.stop(); | |
| 209 | } | |
| 210 | expect([...skipped].sort()).toEqual([...MCP_ONLY].sort()); | |
| 211 | expect([...accountFirst].sort()).toEqual([...ANONYMOUS_NEEDS_ACCOUNT].sort()); | |
| 212 | }, 120_000); | |
| 213 | ||
| 214 | test("the four roles of one repository page are offered four different manifests", () => { | |
| 215 | const lists = [undefined, who["nina"], who["wes"], who["wren"]].map((v) => JSON.stringify(manifest(v).can)); | |
| 216 | expect(new Set(lists).size).toBe(4); | |
| 217 | }); |
new above
offline
Silent
continueskips actions without http (item 3). Assert the skipped ones are the expected set.