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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14953-a-crew-approval-of-an-outside-agent-s-pu → main 1 commit fork
8 files
changed +100
−19
docs/THREATS.md +6
| @@ -349,6 +349,12 @@ Wants: accounts, spam, resources, or a way to exhaust the forge. | ||
| 349 | 349 | cell its check does not run unapproved either, and says the press that |
| 350 | 350 | lifts it. |
| 351 | 351 | 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` | |
| 352 | 358 | - A fork shares its parent's git objects, and git answers for any object a |
| 353 | 359 | store holds to whoever names it by id. So someone who reads a fork and may |
| 354 | 360 | 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 | ||
| 22 | 22 | - **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). |
| 23 | 23 | - **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. |
| 24 | 24 | |
| 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. | |
| 26 | 26 | |
| 27 | 27 | **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`. |
| 28 | 28 |
src/actions/pulls.ts +2 −1
| @@ -885,8 +885,9 @@ export async function submitReview( | ||
| 885 | 885 | announceTeamWaits(app, repo, { ...pull, headOid: status.headOid }, user.id); |
| 886 | 886 | // An approval of an outside agent's pull is the guest approval that releases its preview |
| 887 | 887 | // (`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. | |
| 888 | 889 | if (input.state === "approved" && fromOutsideAgent(pull)) |
| 889 | approveGuestPull(app, user, repo, pull); | |
| 890 | approveGuestPull(app, user, repo, { ...pull, headOid: status.headOid }); | |
| 890 | 891 | // The boxes the reviewer read at this head: only a crew reviewer's approval |
| 891 | 892 | // counts. A pull yet to land holds them for its landing, which applies them |
| 892 | 893 | // 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 @@ | ||
| 2 | 2 | * Whether a pull's preview may be deployed (#12102): the pull's code may run |
| 3 | 3 | * at its head (`core/pull_trust.ts`) and, for a branch an outside agent pushed |
| 4 | 4 | * 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. | |
| 6 | 6 | */ |
| 7 | 7 | import type { Database } from "bun:sqlite"; |
| 8 | 8 | import type { Pull } from "../core/pulls.ts"; |
| @@ -11,4 +11,4 @@ import type { Repo } from "../core/repos.ts"; | ||
| 11 | 11 | import { outsideAgentWaits } from "../origins/guest.ts"; |
| 12 | 12 | |
| 13 | 13 | 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 @@ | ||
| 6 | 6 | * pushed here with a contribute token. Its check and preview run without the |
| 7 | 7 | * repository's secrets, and the crew does not review it (but on an |
| 8 | 8 | * 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 | |
| 13 | 15 | * may run at all is still `core/pull_trust.ts`'s question, asked per head. |
| 14 | 16 | * Pure data. |
| 15 | 17 | */ |
| @@ -50,28 +52,40 @@ export const fromOutsideAgent = (pull: Pick<Pull, "crossRepo" | "headBranch">): | ||
| 50 | 52 | export const outsideAgentWaits = (db: Database, pull: Pull): boolean => |
| 51 | 53 | fromOutsideAgent(pull) && guestWaits(db, pull); |
| 52 | 54 | |
| 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 | */ | |
| 54 | 59 | export function guestApproval( |
| 55 | 60 | db: Database, |
| 56 | 61 | pullId: string, |
| 57 | ): { approvedBy: string; approvedAt: string } | undefined { | |
| 62 | ): { approvedBy: string; approvedAt: string; headOid: string | null } | undefined { | |
| 58 | 63 | 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", | |
| 61 | 66 | ) |
| 62 | 67 | .get(pullId); |
| 63 | 68 | return row === null |
| 64 | 69 | ? undefined |
| 65 | : { approvedBy: row.approved_by, approvedAt: row.approved_at }; | |
| 70 | : { approvedBy: row.approved_by, approvedAt: row.approved_at, headOid: row.head_oid }; | |
| 66 | 71 | } |
| 67 | 72 | |
| 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 | ||
| 68 | 82 | /** |
| 69 | 83 | * A guest nobody has approved yet: no secrets, no crew. A guest whose |
| 70 | 84 | * account is a trusted source on its forge (`pull_source`, #9011) does not |
| 71 | 85 | * wait: trust is that approval, for as long as it lasts. |
| 72 | 86 | */ |
| 73 | 87 | 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); | |
| 75 | 89 | } |
| 76 | 90 | |
| 77 | 91 | /** Whether `user` may approve a guest on `repo`: a person who can write it. */ |
| @@ -83,7 +97,8 @@ export const mayApproveGuest = ( | ||
| 83 | 97 | |
| 84 | 98 | /** |
| 85 | 99 | * 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). | |
| 87 | 102 | */ |
| 88 | 103 | const mayApprove = (db: Database, repo: Repo, pull: Pull, user: User | undefined): boolean => |
| 89 | 104 | mayApproveGuest(db, repo, user) || |
| @@ -91,7 +106,11 @@ const mayApprove = (db: Database, repo: Repo, pull: Pull, user: User | undefined | ||
| 91 | 106 | fromOutsideAgent(pull) && |
| 92 | 107 | crewRole(db, repo.id, user.id) === "reviewer"); |
| 93 | 108 | |
| 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 | */ | |
| 95 | 114 | export function approveGuest( |
| 96 | 115 | db: Database, |
| 97 | 116 | repo: Repo, |
| @@ -100,11 +119,17 @@ export function approveGuest( | ||
| 100 | 119 | ): Result<"approved" | "already", "forbidden" | "not_guest"> { |
| 101 | 120 | if (!mayApprove(db, repo, pull, user) || user === undefined) return err("forbidden"); |
| 102 | 121 | if (!isGuestPull(db, pull)) return err("not_guest"); |
| 122 | const head = mayApproveGuest(db, repo, user) ? null : pull.headOid; | |
| 103 | 123 | const changed = db |
| 104 | 124 | .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)`, | |
| 106 | 131 | ) |
| 107 | .run(pull.id, user.id).changes; | |
| 132 | .run(pull.id, user.id, head).changes; | |
| 108 | 133 | return ok(changed === 0 ? "already" : "approved"); |
| 109 | 134 | } |
| 110 | 135 |
test/outside-lane.test.ts +43 −1
| @@ -20,7 +20,7 @@ import type { Pull } from "../src/core/pulls.ts"; | ||
| 20 | 20 | import type { Repo } from "../src/core/repos.ts"; |
| 21 | 21 | import { cancelRun, createRun } from "../src/core/runs.ts"; |
| 22 | 22 | 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"; | |
| 24 | 24 | import { quietLogs } from "./helpers/globals.ts"; |
| 25 | 25 | |
| 26 | 26 | quietLogs(); |
| @@ -116,3 +116,45 @@ test("a crew reviewer's approval of a contrib pull is the guest approval and rel | ||
| 116 | 116 | expect(guestApproval(app.db, contrib.id)?.approvedBy).toBe(made.value.user.id); |
| 117 | 117 | expect(mayRun()).toBe(true); |
| 118 | 118 | }); |
| 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 | }); |
new above
offline