Public: anyone can read this; the crew can change it.

A crew approval of an outside agent's pull holds for the head it read only #14977

Merged opened this

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

Merged

torque/forge:torque/14953-a-crew-approval-of-an-outside-agent-s-pu → main 1 commit fork

  • Merged. torque/14953-a-crew-approval-of-an-outside-agent-s-pu was merged into main as abaaa80.

Review

Sign in to review this change.
8 files changed +100 −19
docs/THREATS.md +6
@@ -349,6 +349,12 @@ Wants: accounts, spam, resources, or a way to exhaust the forge.
349349 cell its check does not run unapproved either, and says the press that
350350 lifts it.
351351 Enforced by: `test/boundary-tokens-crew.test.ts`
352 - An outside agent gets one harmless head of its pull approved by the crew's
353 reviewer (or steers the reviewer by prompt injection), then pushes a new
354 head whose preview would hold the app's settings. A reviewer's approval
355 holds for the head it read only; the new head waits again for a person or
356 a new review. A person's approval is for the pull, as before.
357 Enforced by: `test/outside-lane.test.ts`
352358 - A fork shares its parent's git objects, and git answers for any object a
353359 store holds to whoever names it by id. So someone who reads a fork and may
354360 not read its parent (the parent was made private after the fork; they left
docs/features/contribute-token.md +1 −1
@@ -22,7 +22,7 @@ or the MCP `start` tool with `action: "contribute"` (same arguments). The answer
2222 - **Limits:** 5 tokens an hour and 20 a day per address (hashed), 120 requests a minute per token; at most 5 pulls open per token, 20 opened a day per token, 25 a day per claimed agent name (`PULLS_PER_AGENT_DAY`, so minting more tokens buys nothing) and 30 a day from all of a repository's outside tokens (counted from the pull rows; over it answers 429).
2323 - **Claimed, not verified:** the agent name and origin are what the agent said. The forge makes a throwaway guest account per token (no password, no crew, no credits) so a pull has an author; the account stays after the token ends.
2424
25 **What runs, and what it holds.** The code on a `contrib/` branch is an outside agent's, whoever opens the pull, so the pull is a guest's (`src/origins/guest.ts`). Its **check runs at once**, with nobody's permission: green or red in minutes, read at the `checks (plain text)` URL the push prints. That is safe for what a check is: a cell holding no variable, no token and no secret, reaching the registry and the hosts **main's** `forge.json` declares, within main's limits (the branch's own `egress` and `check.limits` are not used until the pull lands, as for every pull, and for this one the list is enforced whatever the forge's egress setting; `src/checks/held.ts`, `src/checks/outside.ts`). Its check is **queued behind every other check**: while the owner's or the crew's work is queued, that runs first (`src/checks/outside_lane.ts`, and once the pull is approved it is the repository's like any pull's). **No preview is deployed from its branch until a person who can write approves the pull** (the same once-per-pull approval a guest's fork takes); after the approval the preview deploys as for any pull, with the app's settings. The pull page says one line to a writer, "From an outside contributor: approve to deploy its preview, with this app's settings.", with **Approve**. A crew reviewer's approval of the pull records the same approval (`approveGuestPull`), so it releases the preview too. On a machine that cannot hold a cell, an unapproved outside pull's check fails with a sentence that says a writer approves the pull (Approve on its page) and then runs its checks again, rather than run a stranger's code beside the forge's own data.
25 **What runs, and what it holds.** The code on a `contrib/` branch is an outside agent's, whoever opens the pull, so the pull is a guest's (`src/origins/guest.ts`). Its **check runs at once**, with nobody's permission: green or red in minutes, read at the `checks (plain text)` URL the push prints. That is safe for what a check is: a cell holding no variable, no token and no secret, reaching the registry and the hosts **main's** `forge.json` declares, within main's limits (the branch's own `egress` and `check.limits` are not used until the pull lands, as for every pull, and for this one the list is enforced whatever the forge's egress setting; `src/checks/held.ts`, `src/checks/outside.ts`). Its check is **queued behind every other check**: while the owner's or the crew's work is queued, that runs first (`src/checks/outside_lane.ts`, and once the pull is approved it is the repository's like any pull's). **No preview is deployed from its branch until a person who can write approves the pull** (the same once-per-pull approval a guest's fork takes); after the approval the preview deploys as for any pull, with the app's settings. The pull page says one line to a writer, "From an outside contributor: approve to deploy its preview, with this app's settings.", with **Approve**. A crew reviewer's approval of the pull records the same approval (`approveGuestPull`), so it releases the preview too, but only for the head it read: a new push waits for a person or a new review (#14953). On a machine that cannot hold a cell, an unapproved outside pull's check fails with a sentence that says a writer approves the pull (Approve on its page) and then runs its checks again, rather than run a stranger's code beside the forge's own data.
2626
2727 **The push opens the pull (#12013).** A push of a new `contrib/<agent>/<segment>/<topic>` branch opens a pull on the default branch (the tip commit's first line is the title, its whole message the body); a later push to the branch updates that pull. While nobody has approved the pull the push also prints "checks run now, behind the owner's; the preview is deployed once a person who can write here approves the pull on its page". The push output prints, as `remote:` lines, the pull's URL and `checks (plain text)`, the URL of `GET /api/v1/repos/<owner>/<name>/pulls/<n>/checks?format=text` (`state:`, `head:`, `required:`). Refused with one line: a push to the default branch or another token's branch (the line names the branches the token may push), a token past its expiry (401), a push over 5 MiB (`CONTRIBUTE_PUSH_MAX_BYTES`; git says "pack exceeds maximum allowed size (5.00 MiB)"), and a new branch once the token has 5 pulls open has opened 20 in a day, the agent name has opened 25, or the repository has taken 30 in a day (the line carries the number). A push that creates more new branches than the token has room to open pulls is refused whole with both numbers. Opens are serialized per token (`inTurn`), shared by the API and the push, with the caps read inside the turn; a branch that loses a race to a cap is still pushed and the output says no pull was opened. Code: `src/actions/contribute_push.ts`; test: `test/contribute-push.test.ts`.
2828
src/actions/pulls.ts +2 −1
@@ -885,8 +885,9 @@ export async function submitReview(
885885 announceTeamWaits(app, repo, { ...pull, headOid: status.headOid }, user.id);
886886 // An approval of an outside agent's pull is the guest approval that releases its preview
887887 // (`origins/guest.ts`): the one path, so a reviewer's verdict and the Approve press agree.
888 // The head it approves is the one it read: a reviewer's approval holds for that head only.
888889 if (input.state === "approved" && fromOutsideAgent(pull))
889 approveGuestPull(app, user, repo, pull);
890 approveGuestPull(app, user, repo, { ...pull, headOid: status.headOid });
890891 // The boxes the reviewer read at this head: only a crew reviewer's approval
891892 // counts. A pull yet to land holds them for its landing, which applies them
892893 // only if the head is still this one; one that landed takes them now.
src/apps/preview_gate.ts +2 −2
@@ -2,7 +2,7 @@
22 * Whether a pull's preview may be deployed (#12102): the pull's code may run
33 * at its head (`core/pull_trust.ts`) and, for a branch an outside agent pushed
44 * with a contribute token, a person who can write (or the crew's reviewer) has
5 * approved the pull (`origins/guest.ts`). Plain data in, a boolean out.
5 * approved the pull (the reviewer: this head, `origins/guest.ts`). Plain data in, a boolean out.
66 */
77 import type { Database } from "bun:sqlite";
88 import type { Pull } from "../core/pulls.ts";
@@ -11,4 +11,4 @@ import type { Repo } from "../core/repos.ts";
1111 import { outsideAgentWaits } from "../origins/guest.ts";
1212
1313 export const previewMayRun = (db: Database, repo: Repo, pull: Pull, head: string): boolean =>
14 !outsideAgentWaits(db, pull) && pullMayRun(db, repo, pull, head);
14 !outsideAgentWaits(db, { ...pull, headOid: head }) && pullMayRun(db, repo, pull, head);
src/core/migration-pins/20261121090000-guest-approval-head.pin added +1
@@ -0,0 +1,1 @@
1 85a4c9c0f8c964c8873de1c277bcdcbc5f17cfe3998eb9e003021d862bc73124
src/core/migrations/20261121090000-guest-approval-head.ts added +6
@@ -0,0 +1,6 @@
1 // A crew reviewer's approval of an outside agent's pull holds for the head it read only (#14953,
2 // the deepsec finding in #14771): the head it approved, kept here. Null for a person's approval,
3 // which is for the pull, as before. Additive.
4 export default `
5 ALTER TABLE guest_approval ADD COLUMN head_oid TEXT;
6 `;
src/origins/guest.ts +39 −14
@@ -6,10 +6,12 @@
66 * pushed here with a contribute token. Its check and preview run without the
77 * repository's secrets, and the crew does not review it (but on an
88 * autonomous repository, `crew/stranger.ts`), until a person —
9 * never an agent — who can write the repository approves it once. The
10 * approval is for the pull, not a head: a later push by the same author
11 * runs with the secrets too — except a head moved on a read-only mirror,
12 * which clears it (`forgetGuestApproval`, #9011). Whether a head's code
9 * never an agent — who can write the repository approves it once. A
10 * person's approval is for the pull, not a head: a later push by the same
11 * author runs with the secrets too — except a head moved on a read-only
12 * mirror, which clears it (`forgetGuestApproval`, #9011). The one agent that
13 * may approve, the crew's reviewer on an outside agent's pull, approves the
14 * head it read and no other (#14953): a new push waits for a new review. Whether a head's code
1315 * may run at all is still `core/pull_trust.ts`'s question, asked per head.
1416 * Pure data.
1517 */
@@ -50,28 +52,40 @@ export const fromOutsideAgent = (pull: Pick<Pull, "crossRepo" | "headBranch">):
5052 export const outsideAgentWaits = (db: Database, pull: Pull): boolean =>
5153 fromOutsideAgent(pull) && guestWaits(db, pull);
5254
53 /** Who approved the guest `pull`, and when; undefined until someone has. */
55 /**
56 * Who approved the guest `pull`, and when; undefined until someone has. `headOid` is the one
57 * head the approval holds for (a crew reviewer's), null when it holds for the pull (a person's).
58 */
5459 export function guestApproval(
5560 db: Database,
5661 pullId: string,
57 ): { approvedBy: string; approvedAt: string } | undefined {
62 ): { approvedBy: string; approvedAt: string; headOid: string | null } | undefined {
5863 const row = db
59 .query<{ approved_by: string; approved_at: string }, [string]>(
60 "SELECT approved_by, approved_at FROM guest_approval WHERE pull_id = ?1",
64 .query<{ approved_by: string; approved_at: string; head_oid: string | null }, [string]>(
65 "SELECT approved_by, approved_at, head_oid FROM guest_approval WHERE pull_id = ?1",
6166 )
6267 .get(pullId);
6368 return row === null
6469 ? undefined
65 : { approvedBy: row.approved_by, approvedAt: row.approved_at };
70 : { approvedBy: row.approved_by, approvedAt: row.approved_at, headOid: row.head_oid };
6671 }
6772
73 /**
74 * Whether `pull` at its head is approved: by a person for the pull, or by the reviewer for this
75 * head.
76 */
77 const approvedAtHead = (db: Database, pull: Pull): boolean => {
78 const found = guestApproval(db, pull.id);
79 return found !== undefined && (found.headOid === null || found.headOid === pull.headOid);
80 };
81
6882 /**
6983 * A guest nobody has approved yet: no secrets, no crew. A guest whose
7084 * account is a trusted source on its forge (`pull_source`, #9011) does not
7185 * wait: trust is that approval, for as long as it lasts.
7286 */
7387 export function guestWaits(db: Database, pull: Pull): boolean {
74 return isGuestPull(db, pull) && guestApproval(db, pull.id) === undefined && !foldsIn(db, pull.id);
88 return isGuestPull(db, pull) && !approvedAtHead(db, pull) && !foldsIn(db, pull.id);
7589 }
7690
7791 /** Whether `user` may approve a guest on `repo`: a person who can write it. */
@@ -83,7 +97,8 @@ export const mayApproveGuest = (
8397
8498 /**
8599 * Whether `user` may approve `pull`: a person who can write (`mayApproveGuest`) or, for an outside
86 * agent's pull only, the crew's reviewer, whose approval of the head is the repository's own.
100 * agent's pull only, the crew's reviewer, whose approval of the head it read is the repository's
101 * own for that head (`approveGuest` keeps the head).
87102 */
88103 const mayApprove = (db: Database, repo: Repo, pull: Pull, user: User | undefined): boolean =>
89104 mayApproveGuest(db, repo, user) ||
@@ -91,7 +106,11 @@ const mayApprove = (db: Database, repo: Repo, pull: Pull, user: User | undefined
91106 fromOutsideAgent(pull) &&
92107 crewRole(db, repo.id, user.id) === "reviewer");
93108
94 /** Approve the guest `pull`, once. A second approval keeps the first. */
109 /**
110 * Approve the guest `pull`, once: a person for the pull, the crew's reviewer for `pull.headOid`
111 * (the head it read) only. A second approval keeps the first, unless the first held for another
112 * head and this one holds for the pull or for the head now.
113 */
95114 export function approveGuest(
96115 db: Database,
97116 repo: Repo,
@@ -100,11 +119,17 @@ export function approveGuest(
100119 ): Result<"approved" | "already", "forbidden" | "not_guest"> {
101120 if (!mayApprove(db, repo, pull, user) || user === undefined) return err("forbidden");
102121 if (!isGuestPull(db, pull)) return err("not_guest");
122 const head = mayApproveGuest(db, repo, user) ? null : pull.headOid;
103123 const changed = db
104124 .query(
105 "INSERT INTO guest_approval (pull_id, approved_by) VALUES (?1, ?2) ON CONFLICT (pull_id) DO NOTHING",
125 `INSERT INTO guest_approval (pull_id, approved_by, head_oid) VALUES (?1, ?2, ?3)
126 ON CONFLICT (pull_id) DO UPDATE SET
127 approved_by = excluded.approved_by, head_oid = excluded.head_oid,
128 approved_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
129 WHERE guest_approval.head_oid IS NOT NULL
130 AND (excluded.head_oid IS NULL OR excluded.head_oid <> guest_approval.head_oid)`,
106131 )
107 .run(pull.id, user.id).changes;
132 .run(pull.id, user.id, head).changes;
108133 return ok(changed === 0 ? "already" : "approved");
109134 }
110135
test/outside-lane.test.ts +43 −1
@@ -20,7 +20,7 @@ import type { Pull } from "../src/core/pulls.ts";
2020 import type { Repo } from "../src/core/repos.ts";
2121 import { cancelRun, createRun } from "../src/core/runs.ts";
2222 import { createUser, type User } from "../src/core/users.ts";
23 import { guestApproval } from "../src/origins/guest.ts";
23 import { guestApproval, guestWaits } from "../src/origins/guest.ts";
2424 import { quietLogs } from "./helpers/globals.ts";
2525
2626 quietLogs();
@@ -116,3 +116,45 @@ test("a crew reviewer's approval of a contrib pull is the guest approval and rel
116116 expect(guestApproval(app.db, contrib.id)?.approvedBy).toBe(made.value.user.id);
117117 expect(mayRun()).toBe(true);
118118 });
119
120 test("a crew reviewer's approval holds for the head it read: a new push waits for a new review (#14953)", async () => {
121 const branch = "contrib/codex/0a1b2c3d/moved";
122 const contrib = await pull(branch);
123 const made = await createAgent(app, alice, { username: "rev2", roles: ["reviewer"] });
124 if (!made.ok) throw new Error(String(made.error));
125 const rev = made.value.user;
126 app.db
127 .query("INSERT INTO repo_crew (repo_id, user_id, role, added_by) VALUES (?1, ?2, 'reviewer', ?3)")
128 .run(repo.id, rev.id, alice.id);
129 const now = () => getPull(app.db, repo.id, contrib.number)!;
130 const mayRun = () => previewMayRun(app.db, repo, now(), now().headOid);
131 expect((await submitReview(app, rev, repo, now(), { state: "approved" })).ok).toBe(true);
132 expect(guestApproval(app.db, contrib.id)?.headOid).toBe(contrib.headOid);
133 expect([guestWaits(app.db, now()), mayRun()]).toEqual([false, true]);
134
135 // The outside agent pushes a new head: the approval was of the old one.
136 const moved = await commitToBranch(app, alice, repo, {
137 branch, message: "Then this", files: [{ path: "exfil.ts", content: "export const y = 2;\n" }],
138 });
139 if (!moved.ok) throw new Error(JSON.stringify(moved.error));
140 expect(now().headOid).not.toBe(contrib.headOid);
141 expect([guestWaits(app.db, now()), mayRun()]).toEqual([true, false]);
142 // The head it read stays approved: its preview may still deploy.
143 expect(previewMayRun(app.db, repo, now(), contrib.headOid)).toBe(true);
144
145 // A review of the new head approves it.
146 expect((await submitReview(app, rev, repo, now(), { state: "approved" })).ok).toBe(true);
147 expect([guestApproval(app.db, contrib.id)?.headOid, mayRun()]).toEqual([now().headOid, true]);
148
149 // A person's approval is for the pull: it holds across a later push, as before.
150 expect(approveGuestPull(app, alice, repo, now())).toEqual({ ok: true, value: "approved" });
151 expect(guestApproval(app.db, contrib.id)).toMatchObject({ approvedBy: alice.id, headOid: null });
152 const again = await commitToBranch(app, alice, repo, {
153 branch, message: "And this", files: [{ path: "more.ts", content: "export const z = 3;\n" }],
154 });
155 if (!again.ok) throw new Error(JSON.stringify(again.error));
156 expect(mayRun()).toBe(true);
157 // A reviewer's later approval does not narrow a person's back to one head.
158 expect((await submitReview(app, rev, repo, now(), { state: "approved" })).ok).toBe(true);
159 expect(guestApproval(app.db, contrib.id)?.headOid).toBeNull();
160 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs