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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13683-the-role-aware-manifest-on-a-page-lists → main 3 commits fork 4 threads · 4 unresolved

  • Merged. scout/13683-the-role-aware-manifest-on-a-page-lists was merged into main as 60d836e.

Review

Sign in to review this change.
1 file changed +124 −11
test/manifest-roles.test.ts +124 −11
@@ -2,8 +2,11 @@
22 * An agent that reads a page learns what it may do, cheaply (#13486): the
33 * manifest omits every tool its caller cannot call, and its size per role
44 * 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.
710 */
811 import { afterAll, beforeAll, expect, test } from "bun:test";
912 import { mkdtemp, rm } from "node:fs/promises";
@@ -14,6 +17,12 @@ import { manifestFor } from "../src/actions/here.ts";
1417 import { createApp, type App } from "../src/app.ts";
1518 import { createUser, type User } from "../src/core/users.ts";
1619 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";
1726 import { promote } from "./helpers/members.ts";
1827
1928 /** 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"];
3342 const WRITER_MAY = new Set([...OUTSIDER_MAY, ...MEMBER_ONLY]);
3443 const ADMIN_MAY = new Set([...WRITER_MAY, "change settings"]);
3544
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[] = [];
3960
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> = {};
4368 const mk = async (name: string, first = false) => {
4469 const made = await createUser(app.db, {
4570 origin: "seed", trusted: true, username: name, email: `${name}@forge.local`,
@@ -60,11 +85,38 @@ beforeAll(async () => {
6085 addTeamMember(app.db, team.value, who["wes"]!.id);
6186 const made = await newApp(app, who["wren"]!, { name: "pub", owner: "acme", visibility: "public" });
6287 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 });
64116
65117 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 });
outdated

Silent continue skips actions without http (item 3). Assert the skipped ones are the expected set.

68120 });
69121
70122 function manifest(viewer: User | undefined) {
@@ -102,3 +154,64 @@ test("the manifest stays under its ceiling for each role", () => {
102154 `the ${role} manifest is ${sizes[role]} characters, over its ${CEILINGS[role]} ceiling`,
103155 ).toBeLessThanOrEqual(CEILINGS[role]);
104156 });
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs