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

Each threat section of docs/THREATS.md lives in its own file under docs/threats/, so security pulls stop colliding on one 523-line document #15022

Merged opened this

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

Merged

mason/forge:mason/15005-each-threat-section-of-docs-threats-md-l → main 2 commits fork

  • Merged. mason/15005-each-threat-section-of-docs-threats-md-l was merged into main as c7357bd.

Review

Sign in to review this change.
17 files changed +679 −576
AGENTS.md +1 −1
@@ -2,7 +2,7 @@
22
33 Read `CLAUDE.md` first: it is the rulebook for agents editing this repo.
44
5 Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`). The section list of `docs/DESIGN.md` is built the same way: a section file under `docs/design/sections/` opens with `order:` and `nest:` front matter and its first heading is its title (#14354, `test/design-spine.test.ts`).
5 Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`). The section list of `docs/DESIGN.md` is built the same way: a section file under `docs/design/sections/` opens with `order:` and `nest:` front matter and its first heading is its title (#14354, `test/design-spine.test.ts`). `docs/THREATS.md` is an index: each adversary's `## ` section is a file in `docs/threats/`, linked from the index in order; a new protection goes in its adversary's file, a new adversary is a new file and a new link. `readThreats` in `src/core/threats.ts` puts them back together for the Resilience page, `/docs/THREATS.md` and the tests (#15005, `test/threats-sections-linked.test.ts`).
66
77 A maintenance duty is a file in `src/maintain/duties/` that exports `duty`; `src/maintain/registry.ts` builds the roster from that directory, never edit a list by hand (#14355, `test/duty-roster.test.ts`).
88
docs/THREATS.md +12 −560
@@ -13,564 +13,16 @@ a named path that does not exist, and prints how many rows say `none yet`. A
1313 protection nothing enforces is a gap, not a secret: the count is the to-do
1414 list, and only editing a row lowers it.
1515
16 ## A snooper on the network
16 Each section below is its own file in `docs/threats/`, so a change to one
17 adversary's protections touches only that file; the Resilience page, the
18 served document and `test/threats-enforced.test.ts` read the sections in
19 this order, as one document.
1720
18 Wants: session cookies, tokens and pushed code in transit, or to learn who
19 talks to whom.
20
21 - Sessions are HttpOnly cookies, `Secure` when the request came over https, so
22 script cannot read one and a plain-http hop does not carry it.
23 Enforced by: `test/own-session.test.ts`
24 - Tokens are shown once; the database keeps only their sha256, so a copy of the
25 index does not replay as a login.
26 Enforced by: `test/tokens.test.ts`
27 - TLS is terminated by the edge in front of the forge, and certificates are
28 issued only for names the forge vouches for (`on_demand_tls` ask).
29 Enforced by: none yet
30 - Between the edge and the forge process, and between forge and cell, traffic is
31 plain HTTP on one machine or a pod network. Nothing encrypts it.
32 Enforced by: none yet
33
34 ## A stolen token
35
36 Wants: to act as the person or agent it was issued to, for as long as it works.
37
38 - Tokens carry a scope and an optional expiry; a narrower token cannot do what a
39 wider one can.
40 Enforced by: `test/tokens.test.ts`
41 - A crew run's secrets are named in the brief, opened per run, redacted from the
42 log, and released when the run ends.
43 Enforced by: `test/run-secrets.test.ts`
44 - The model credential in a crew run's environment is held for redaction like a
45 granted secret, from before the agent starts until the run ends: a run that
46 says it leaves `[redacted]` in its log, its summary and every event. The
47 two other children the forge starts with that credential, a one-shot and a
48 conversation turn, are held the same way.
49 Enforced by: `test/boundary-secrets-run.test.ts`
50 - A passport (`fp1.…`) is bound to one audience and scope set and dies in
51 minutes, so a copy lifted from a run is useful to one door briefly.
52 Enforced by: `test/passport.test.ts`
53 - Sign-in attempts are throttled per client, with a whole-forge cap beside it; eight wrong passwords at one account from one client in ten minutes shut that pair until the window passes (`src/core/signin-window.ts`, #14373).
54 Enforced by: `test/signin-throttle.test.ts`
55 - Stored provider tokens (origins) are sealed under a key in `secret.key`, never
56 returned by any route.
57 Enforced by: `test/origins-security-auth.test.ts`
58 - The operator's GitHub application (`FORGE_GITHUB_CLIENT_ID`, `_SECRET`) is
59 github.com's alone: a host a member calls GitHub Enterprise gets no app, and
60 the secret is withheld from every other host at the device poll, the
61 refresh and the revoke, whatever registration carries it (#14757).
62 Enforced by: `test/origins-github-secret.test.ts`
63 - The SSH host key and the database files are created 0600; a host key group-
64 or world-readable is refused, and a database file found too open is a
65 degraded finding naming the chmod, never a silent change and never a stop.
66 Enforced by: `test/file-modes.test.ts`
67 - The files a forge's family keeps keys in (`parent.json`: the heartbeat key, a
68 proposal token, a read credential offered and not yet sealed; the parent's
69 `spawn/<name>.json`: the status token and the heartbeat key) are written 0600
70 (`writePrivate`), and one found wider is narrowed at boot and said once.
71 Enforced by: `test/boundary-tokens-follow.test.ts`
72 - A token bound to one repository (a run's, a child's, an outside agent's, an
73 app's) is refused on every route of every other repository before the
74 route's handler runs, and ends with its repository: it never becomes an
75 unbound one.
76 Enforced by: `test/boundary-tokens-gates.test.ts`
77 - Every such token is minted with an end, read on every use, and its own
78 revoke ends it at the next request, with no restart and no wait. A
79 repository's admin sees and ends every child's read of it, whoever it was
80 minted as; a suspended account's tokens stop with it.
81 Enforced by: `test/boundary-tokens-gates.test.ts`
82 - A crew run's git offers its token to this forge's two addresses and to no
83 other host it talks to, and the token ends with the run.
84 Enforced by: `test/boundary-tokens-crew.test.ts`
85 - The credential a child holds to read a private app is minted for that one
86 repository and kept by the parent as a hash; the child seals it with its own
87 key and keeps it in no file, config or address. It lives a week at a time,
88 renewed while the child follows, and ends when the child is removed, refuses
89 the offer or is revoked; no log line or event on either forge carries it.
90 Enforced by: `test/boundary-tokens-follow.test.ts`
91 - A child's tokens and an outside agent's contribute token never enter an app
92 at its own host, whoever's account they ride on. The token a preview's own
93 process holds reaches its repository, its timers and its printer, and
94 nothing else of its owner's.
95 Enforced by: `test/boundary-tokens-apphost.test.ts`
96 - Only a forge admin sets or removes a secret, and nothing is opened for
97 anyone else. An open leaves one `secret.read` per name opened; no event
98 carries a value, plain or sealed; the data browser shows no sealed column.
99 The key file is 32 bytes only its owner reads, and one that others can read
100 is refused by name. A lost key costs the values and nothing else. Deleting a
101 repository removes the secrets scoped to it.
102 Enforced by: `test/boundary-secrets-store.test.ts`
103 - A secret kept for the forge or an organization reaches a repository's app
104 and its crew's runs only after a forge admin granted that name to that
105 repository; a repository's own secrets need no grant. A name a run declares
106 and nobody granted is never opened: the run goes on without it and says so
107 in its log and once on its issue, with the link that grants it.
108 Enforced by: `test/boundary-secrets-store.test.ts`
109 - A production app's `FORGE_TOKEN` is its owner's read-only token: the app's
110 code and what it depends on read everything its owner reads, every private
111 repository included. A preview's is bound to the app's one repository;
112 production's is not, because reading the whole forge from an app is a
113 documented feature (`docs/APPS.md`, `examples/forge-live`). Binding it too
114 waits for the owner's word: it needs a per-app grant the owner sees listed,
115 and until that grant is given it stops an app that reads its owner's other
116 repositories on purpose.
117 Enforced by: none yet
118 - Revoking every token of one account at once, and telling its owner a token was
119 used from somewhere new.
120 Enforced by: none yet
121
122 ## A compromised vendor
123
124 Wants: to run its code on the forge or in an app through something the forge
125 trusts: a package, a model provider, a hosting provider, an origin it syncs from.
126
127 - The forge has no runtime dependencies, so there is no package to poison in the
128 forge itself.
129 Enforced by: `test/deps.test.ts`
130 - An app's code runs in a cell: read-only machine, empty data directory and
131 home, own pid and network namespaces, memory, CPU and disk watched. A
132 dependency an app pulls in gets no more than the app does.
133 Enforced by: `test/contain.test.ts`
134 - A cell binds each directory it may write once, nothing inside one by name,
135 and only a directory that is there itself: a link its code leaves where its
136 home goes is never mounted. What it hides (the forge's data, home and temp)
137 is covered under the name it really has as well as the one it was given,
138 before its own directory is bound back, and no neighbour's directory is
139 ever shown.
140 Enforced by: `test/boundary-tenancy-cell.test.ts`
141 - What a cell prints costs the forge one line at most, however long it goes
142 without a newline: an app's or a step's line is cut at 64 KiB as it arrives
143 and says so, a hosted forge's at 500 characters. That text is held in the
144 forge's own memory, outside the cell's cap.
145 Enforced by: `test/boundary-tenancy-limits.test.ts`
146 - A cell's disk is counted to the end or the cell is over it: the walk goes as
147 far as the cell's own limit of files (as many as its disk has 4 KiB blocks,
148 a million at least), and a cell that reaches it is stopped and told so,
149 never counted as the part that was seen.
150 Enforced by: `test/boundary-tenancy-limits.test.ts`
151 - Outside Kubernetes a cell sees the machine's mounts minus the ones that may
152 carry a secret (every tmpfs, everything under `/run`): a second mount of the
153 data volume, an env file or a backup volume bound in at another path is
154 readable in every cell. `FORGE_CELL_MOUNTS=allow-list` closes it; it is not
155 yet the default wherever the forge runs in a container.
156 Enforced by: none yet
157 - A preview's copy of production's data is taken while production runs and
158 can swap any entry for a link to a host path (`secret.key`, `forge.db`,
159 another tenant's data): the forge walks it through held directory
160 descriptors with `O_NOFOLLOW`, copies a link as a link and never what it
161 points at, and checkpoints SQLite only in the copy it alone writes, where
162 `quick_check` refuses a database torn by a write mid-copy (copied again,
163 five times at most, then the seed fails); a log is copied before its
164 database and its shared-memory index never. An app's backup seals such a
165 snapshot, never the live directory.
166 Enforced by: `test/apps-data-symlink-race.test.ts`
167 - An app that prints the variables, identity key or forge token it was handed
168 leaves `[redacted]` in its deploy's log, plain or encoded, so a careless
169 dependency does not publish them to everyone who can read the runs.
170 Enforced by: `test/boundary-secrets-process.test.ts`
171 - The only way out of a cell is the egress proxy, which reaches the hosts the
172 repository declared and refuses names that resolve to private, loopback or
173 metadata addresses.
174 Enforced by: `test/apps-adversarial.test.ts`
175 - The website-spec check the forge runs from its own process against a live
176 preview fetches only the preview's own origin: an icon, manifest or
177 stylesheet the app's HTML names on another host (metadata, a private or
178 tailnet address, another app's loopback port) is reported as off-origin and
179 never fetched, and no request follows a redirect (#14755).
180 Enforced by: `test/webspec.test.ts`
181 - A connected origin's replies are validated at the boundary and not trusted for
182 identity.
183 Enforced by: `test/origins-security-provider.test.ts`
184 - A push to an origin is vetted like a fetch from one: a name that resolves
185 to a private, loopback, link-local, tailnet or metadata address is refused
186 before git starts, in the fetch's words; git dials the address that was
187 judged and follows no redirect. A hosted forge's proposal to its parent
188 trusts the parent's host by name for that one push.
189 Enforced by: `test/mirror-outbound-push.test.ts`
190 - A migration from a connected origin clones only from that origin's own host,
191 whatever `clone_url` its reply names, and that address is vetted and pinned
192 like a pasted one: a private, loopback, link-local or metadata answer is
193 refused before git starts (#14756).
194 Enforced by: `test/migrate.test.ts`
195 - Pushes from an origin cannot rewrite what the forge protects.
196 Enforced by: `test/origins-security-push.test.ts`
197 - Backups are encrypted before they leave the machine.
198 Enforced by: `test/snapshot-store.test.ts`
199 - A review of lockfile changes (`bun.lock`) before they reach an app's cell.
200 Enforced by: none yet
201
202 ## A hostile agent inside a run
203
204 Wants: to read what it was not given, reach what it may not, or land code no
205 person approved.
206
207 - The agent's shell may reach only the forge, the package registry and its
208 own repository's app (production and each open pull's preview), by exact
209 host, and never another repository's app. The
210 forge's repositories, index, key and every other agent's clone are denied by
211 name and by allow-list, and a listing that fails refuses the run.
212 Enforced by: `test/crew-sandbox.test.ts`
213 - No name a tenant chose is allowed whole, since the tenant can point its
214 DNS at loopback, a private network or the metadata address. An app is
215 reached at the slug host the forge serves, never at its verified custom
216 domain. A member's model gateway must be a public dotted name (no IP
217 literal, `localhost`, single label or private suffix), and the run's shell
218 is never allowed the gateway's name. A row saved before the rule is never
219 picked and never dialled (#14750).
220 Enforced by: `test/crew-sandbox-tenant-hosts.test.ts`
221 - A member's gateway name can still be repointed after it is saved, so
222 nothing dials it unjudged: Claude Code, for a run and for the usage check,
223 is pointed at the forge's loopback door (`crew/gateway_door.ts`), which
224 sends each request through `outboundFetch` — resolved, every address
225 judged, dialled at the judged address — and the run's shell is allowed only
226 that door's port (#14750).
227 Enforced by: `test/crew-gateway-door.test.ts`
228 - The one place a run writes beside its clone and temp directory is its
229 repository's bun install cache (`crew/.cache/<repo id>/bun`), which every
230 run on that repository can write: a run can poison what the next run on the
231 same repository installs. It is per repository: the cache root is denied whole
232 and only this repository's directory re-allowed, so a cache made later is
233 denied too, and deleting the repository removes it.
234 Enforced by: `test/crew-install-cache.test.ts`
235 - The crew's dependency install runs on the host, in a clone the repository
236 and earlier runs filled: a lockfile, `package.json`, `node_modules` or
237 `node_modules/.forge-lock-hash` that is a link (to `forge.db`,
238 `secret.key`, `/dev/zero`, another repository's directory) is refused or
239 replaced, never read or written through (#14751). A link that names
240 nothing counts as present and is refused, never read as absent. The
241 lockfile and mark are read on the open file (`O_NOFOLLOW`, then `fstat`),
242 so nothing can be swapped in between a check and a read. One window
243 remains, and it is stated here: `node_modules` is checked with `lstat`
244 before `bun install` runs and again just before the mark is written, but
245 `bun install` itself and the mark's rename go by name. Swapping a path in
246 that window needs something running in the clone at the same time, and
247 nothing in this run is: the install runs in the run's setup, before its
248 agent session starts (`src/crew/runner.ts`), and `--ignore-scripts` runs
249 no code from the repository. Two runs sharing one clone at once would
250 reopen the window; that is not what this item covers.
251 Enforced by: `test/install-links.test.ts`
252 - A check's cache fill reads the pull's `bun.lock` and `package.json` on the
253 host only as regular files of at most 64 MB, opened without following a
254 link and never waiting on a pipe or device: a committed link to a host
255 file leaks none of it into the check log, and one to `/dev/zero` cannot
256 hold the forge (#14751).
257 Enforced by: `test/install-links.test.ts`
258 - A check's cell reads its repository's shared bun cache
259 (`check-install/<repo id>/bun`) through a read-only bind and cannot write
260 it, so one pull cannot plant a package the gate on main installs. The
261 forge fills it on the host with `--ignore-scripts`, and reads no
262 `bunfig.toml` or `.npmrc` of the pull's.
263 Enforced by: `test/check-install.test.ts`
264 - An app environment's cell reads that same cache read-only and
265 copies from it, so a preview cannot plant a package production installs;
266 the forge fills it through the same lockfile rule as a check's.
267 Enforced by: `test/app-install-cache.test.ts`
268 - The forge fills that cache only from a lockfile whose every package is a
269 registry `name@version` with a sha512 integrity (`checks/fillable.ts`):
270 the host never fetches a URL a pull chose and reads no file, link or
271 workspace a pull points at, an override's or resolution's included.
272 Enforced by: `test/check-fillable.test.ts`
273 - A locked tarball URL is "" or exactly the registry's tarball of that
274 entry's `name@version`, so a pull cannot lock another package's tarball
275 (even one on the registry, with its own integrity) under a name and
276 version and plant it in the shared cache, where bun does not re-check it
277 on a hit (#14761): the test "a tarball url of another package on the
278 registry cannot be locked under this name@version".
279 Enforced by: `test/check-fillable.test.ts`
280 - The same policy holds against a real bubblewrap, not only as a string.
281 Enforced by: `test/crew-sandbox-real.test.ts`
282 - The OpenAI-compatible runner's Bash is held to the same policy: every
283 denied path is covered in its bubblewrap (the key, the index, the
284 repositories, every other agent's directory), only the clone, its temp
285 directory and its install cache are writable, and its network namespace's
286 one way out is the forge's egress proxy, which passes the policy's hosts
287 alone and refuses loopback, private addresses and the metadata service.
288 Enforced by: `test/openai-runner-escape.test.ts`
289 - That runner's file tools refuse a path through a link to nothing (one the
290 shell planted, or a checkout made), and write with `O_NOFOLLOW`, so Write
291 cannot create a file outside the clone with the forge's own rights.
292 Enforced by: `test/openai-runner-escape.test.ts`
293 - That runner takes its endpoint, key and model from the forge's own
294 environment, never the run's: a granted secret cannot name the URL the
295 operator's key is sent to, a secret cannot be named `OPENAI_*`, and the
296 endpoint's redirects are refused.
297 Enforced by: `test/openai-runner-escape.test.ts`
298 - Git the forge runs on the host in a crew clone (the wrap-up's status, add,
299 commit and push, a kept clone's fetch, reset and checkout, the leak scan)
300 runs nothing the agent planted there: every call goes through
301 `crew/clone_git.ts`, which refuses a `.git` that is a link, a gitfile or
302 borrows another repository, names `--git-dir` and `--work-tree` (so
303 `core.worktree` points nowhere), and pins hooks, `core.fsmonitor`, every
304 filter and diff driver the clone's config names, ssh and every transport
305 but http(s) off on the command line, above the clone's own config. The
306 forge's commit passes `--no-verify` (#14747).
307 Enforced by: `test/crew-clone-git.test.ts`
308 - The stale-clone sweep's git in an idle clone (`crew/orphans.ts`) runs the
309 same way, with the git environment and not the forge's, so a planted
310 `core.fsmonitor` neither runs nor sees a forge secret (#14747).
311 Enforced by: `test/crew-clone-git.test.ts`
312 - Under the OpenAI-compatible runner the clone's `.git/config` and
313 `.git/hooks` are bound read-only in the shell's bubblewrap, as in the
314 Claude runner's sandbox, and its Write and Edit tools refuse any path in
315 `.git`, by name or through a link (#14747).
316 Enforced by: `test/crew-clone-git.test.ts`
317 - A pull's check and its preview reach the hosts, and run at the limits, that
318 its base branch's `forge.json` declares, never the ones its own asks for,
319 until the pull lands: code on a branch, the crew's as much as a guest's,
320 cannot widen where its own check and preview send what they hold. The
321 pull's page and the top of its logs say in one line what it asked for and
322 that it applies when the pull lands.
323 Enforced by: `test/boundary-pull-egress.test.ts`
324 - An agent cannot push to the default branch or merge; a person merges.
325 Enforced by: `test/protection.test.ts`
326 - An outside agent that drives a person's account cannot push past the pulls
327 either: a protected default takes a push from its admins only, so every
328 other writer lands through a pull, its gate and its review.
329 Enforced by: `test/protected-default-push.test.ts`
330 - A variable set with no scope named is production's alone: a pull's preview,
331 which runs code nobody has landed, reads a variable only when its owner
332 chose "Also in previews" or set one for previews.
333 Enforced by: `test/app-env.test.ts`
334 - Merge gates (checks, review) are enforced in the merge path, not by convention.
335 Enforced by: `test/security-merge.test.ts`
336 - Spend, time and turns per run are limited.
337 Enforced by: `test/crew-limits.test.ts`
338 - Rendered output escapes everything an agent wrote.
339 Enforced by: `test/security-xss.test.ts`
340
341 ## An automated attacker at scale
342
343 Wants: accounts, spam, resources, or a way to exhaust the forge.
344
345 - Request bodies are capped at the boundary.
346 Enforced by: `test/body-limits.test.ts`
347 - Parsers survive generated hostile input.
348 Enforced by: `test/fuzz-parsers.test.ts`
349 - Anonymous spawn is rate limited per client address.
350 Enforced by: `test/spawn-anon.test.ts`
351 - Every door a stranger can reach that costs (API reads, clones, code
352 search on the page, the API and the terminal's guest palette, event
353 streams, spawn plans) is limited per address and for every stranger
354 together (`src/http/strangers.ts`, docs/ARCHITECTURE.md, concurrency
355 invariant 7); a signed-in push keeps its share of the pool.
356 Enforced by: `test/strangers.test.ts`
357 - The client address is the socket's peer unless that peer is a configured
358 trusted proxy; `X-Forwarded-For` is read from the right, past trusted hops.
359 Enforced by: `test/client-address.test.ts`
360 - A new-account guard can refuse repository creation and forks for young
361 accounts.
362 Enforced by: `test/guard-new-accounts.test.ts`
363 - Sign-up has a ceiling per address and for the whole forge, per minute and per
364 hour, and an admin can close it at once.
365 Enforced by: `test/guest-contribute.test.ts`
366 - A guest owns only a contribution fork of a public repository. It holds no
367 settings, secrets or app, nothing runs for it, and its storage, forks and
368 pulls are limited (`docs/ROLES.md`).
369 Enforced by: `test/guest-contribute.test.ts`
370 - An outside agent with a contribute token (no account) pushes its branch into
371 the repository itself, so where a head lives says nothing about who wrote it:
372 a `contrib/<agent>/<segment>/…` head is a guest's. Its check runs with
373 nobody's permission, behind the owner's and the crew's work, in a cell that
374 holds no variable, token or secret and is held to the hosts and limits the
375 base branch declares; nothing from its branch is previewed, and the crew
376 leaves it, until a writer approves the pull once. On a machine with no
377 cell its check does not run unapproved either, and says the press that
378 lifts it.
379 Enforced by: `test/boundary-tokens-crew.test.ts`
380 - An outside agent gets one harmless head of its pull approved by the crew's
381 reviewer (or steers the reviewer by prompt injection), then pushes a new
382 head whose preview would hold the app's settings. A reviewer's approval
383 holds for the head it read only; the new head waits again for a person or
384 a new review. A person's approval is for the pull, as before.
385 Enforced by: `test/outside-lane.test.ts`
386 - A fork shares its parent's git objects, and git answers for any object a
387 store holds to whoever names it by id. So someone who reads a fork and may
388 not read its parent (the parent was made private after the fork; they left
389 its organisation or its crew) is held to what the fork's own refs reach: at
390 the git door over protocol v2 and v0, for a commit, a tree or a file, and at
391 the fork's pages, API, tools and terminal by a full id or a short one,
392 answered exactly as an id nothing holds. A `shallow <id>` line is held like a
393 want, for a held reader and a runner's job token alike, when the fetch
394 deepens without a bound: `deepen 0`, `deepen 2147483647` (what
395 `--unshallow` sends), any `deepen` git would not read as a plain depth, and
396 `deepen-relative` at any depth. Git would unshallow such an id from the
397 shared store and send its parents. Every `shallow` id is held too while
398 the first flush has not arrived, so a request cut off before it is held
399 as one that deepens without a bound. A finite `deepen`, `deepen-since` and
400 `deepen-not` walk only from the wants, which are held, so their `shallow`
401 lines are not: git sends no `unshallow` for them and no object of them,
402 and a runner's kept shallow clone still fetches. Still open (#14850): a
403 `have` the lender holds is ACKed and a `shallow` naming a lender's tree
404 makes git die, so someone with a full id can learn it exists, though not
405 what it holds. A parent that is not public no
406 longer moves a public fork, and a push into such a fork must carry every new
407 object it names. Everyone else fetches as before, partial clones included.
408 What a fork's own refs already held stays the fork's: the read-only
409 `forks-beyond-parent` script lists the forks to look at.
410 Enforced by: `test/boundary-fork-objects.test.ts`
411 - A pull whose head lives in a fork, here or on the origin, and a child's
412 proposal run nothing until a person who can write the repository approves
413 that exact head, and the crew never lands one.
414 Enforced by: `test/guest-contribute.test.ts`
415 - A branch in the repository itself was put there by someone who may write it
416 (on a mirror, by someone its origin lets write), so its check and preview
417 run at once. When its author is a guest from the origin, its preview and
418 that preview's terminal still hold none of the app's variables, no forge
419 token and no copy of production's data until a writer approves the pull.
420 Enforced by: `test/boundary-secrets-process.test.ts`
421 - Every limit is a setting with its reason, changed by an admin only.
422 Enforced by: `test/limits.test.ts`
423 - Distributed attacks across many addresses: only the whole-forge caps stand
424 here.
425 Enforced by: none yet
426
427 ## Internal calls
428
429 `FORGE_SELF_SWAP=1` binds the web port with SO_REUSEPORT so a release can share
430 it, which also lets any process running as the forge's user join the listener
431 and take a share of its connections, login posts included. It assumes nothing
432 else runs as that user on the host network (agents and apps are sandboxed or in
433 cells). Only one swap is made per process, so two landings never leave two
434 releases serving. The swap is refused unless `net.ipv4.tcp_migrate_req=1`, for
435 without it the old listener closing resets queued connections.
436 Enforced by: `test/release-swap.test.ts`
437
438 How each part proves itself to the next, today.
439
440 | Call | Authenticated by | Enforced by |
441 | --- | --- | --- |
442 | runner → forge | the run's scoped token (`FORGE_TOKEN`) and a few-minute passport (`FORGE_PASSPORT`) | `test/passport-edge.test.ts` |
443 | git hook → forge | per-boot secret in `x-forge-hook-secret` on the internal listener; a call without it is refused and counted | `test/crew-sandbox.test.ts` |
444 | cell → proxy | the proxy's Unix socket bound into the cell's own network namespace; no credential, the namespace is the identity | `test/contain.test.ts` |
445 | host → cell | the relay carrying a visitor to an app dials the cell's `in.sock` by the inode it opened with `O_PATH \| O_NOFOLLOW` and checked (a socket, the cell's uid, one name), through `/proc/self/fd/N`, so a symlink or hard link the cell plants there reaches no host socket, and the refusal is a line in the owner's log; the uid check holds because a cell runs as the forge's own uid (`--unshare-user` with no `--uid`/`--gid`, `cellNamespaces`) (#14752) | `test/cell-socket-pin.test.ts` |
446 | edge → pod | `X-Plat-Edge-Token` equal to `FORGE_EDGE_TOKEN`, compared as fixed-width digests; without it `X-Plat-User` is ignored; the `signin.edge` setting (admin, refused for an admin with no password or passkey) turns the edge's identity off on every door | `test/edge-auth.test.ts` |
447 | child → parent | a heartbeat and a brokered sign-in are signed (HMAC) with the key spawn gave both sides, looked up by the name inside the signed body, so the door a call arrives on says nothing about whose it is; the lent model by a bearer whose hash the parent keeps; a child's door answers those routes and nothing else. Code is pulled over public git, and the claim link (sha256 kept, 24 hours, single use) hands the child to its person | `test/boundary-tenancy-cell.test.ts` |
448
449 Gaps: edge → pod and runner → forge ride a shared secret, not a per-call
450 signature.
451
452 ## A child forge running its own code (#11144)
453
454 A cell child's owner may switch it from the parent's code to its own `<org>/forge` main (`spawn/own_code.ts`). The code is then the child's author's, so treat it as hostile code in a cell, the same as any app.
455
456 What it cannot reach: the cell's memory, CPU, disk and I/O limits, its sandbox and its egress list are the same as with the parent's code, and nothing in the child's repository is read to make them. The parent's data, home and temporary directory are hidden; only the parent's code and the one checkout (a tree, with no `.git`) are revealed, read-only. Its `forge.json` is not run by the parent: the parent finds the repository only as a directory of the child's own (never through a link), refuses a repository or tree over 256 MB or 50,000 files and any symbolic link in either, checks that `src/main.ts` parses and `forge.json` is JSON, and never executes the child's code outside the cell. What the parent records about a failed start is fixed wording: one of a list of the parent's own sentences. Nothing the child wrote or printed reaches the ledger, the rollback row or the `forge.rolled_back` event; its last lines go to the parent's log.
457
458 What it can reach: everything a child forge can reach, no more: its own data directory, the parent's heartbeat door and public address, the hosts the admin allowed for models, registry, payment and origins (the public git hosts and the forges its parent holds beside it), and the sign-ins its parent brokers for it. It can lie in what it serves and in its heartbeat, and can break itself: a start that fails to answer within the deadline rolls back to the last commit that came up, then to the parent's code, and the owner's `/forges` page shows a Rolled back row saying so. A commit that failed is not tried again until main moves. A child that comes up and breaks later is not rolled back; the owner switches it off. Hosted children run inside the parent's process and cannot turn this on.
459
460 - The cell limits, sandbox, egress list and hidden parent paths are built by the
461 parent from outside, never read from the child's repository, so a child's own
462 code is held exactly like any app.
463 Enforced by: `test/own-code.test.ts`
464 - A forge made in a cell stays a cell child. A cell that does not start
465 leaves it stopped, its address and its host's forges page saying why and
466 when the host tries again; it is not opened in the parent's process for
467 that, since its directory (its repositories' hooks and git config included)
468 is the child's to write. Only a host that holds no cell at all runs a child
469 in its own process, and never one that has run code of its own.
470 Enforced by: `test/spawn-cell-stays.test.ts`
471 - A forge that still runs inside its parent's process (made before cells, or
472 put there by an older release) is moved into a cell of its own, by an
473 admin's button or by the forge's own pass at boot and when one sleeps; a
474 move that does not prove itself is put back (the sizes it is given are held
475 by `test/spawn-move-cell-sizes.test.ts`).
476 Enforced by: `test/spawn-move-cell.test.ts`
477 - Before such a forge leaves its parent's process its repositories are read,
478 running nothing, for what that process may have executed while it had no
479 wall: hooks beyond the forge's own stubs and config keys that make git run
480 a command, reported by name and never by content.
481 Enforced by: `test/spawn-move-scan.test.ts`
482 - A host that holds every forge in a cell seals: it opens no forge in its
483 own process again whatever a ledger says, never moves a cell child into
484 its process because its own probe of cells failed, and places a new forge
485 in a cell or not at all.
486 Enforced by: `test/spawn-sealed-host.test.ts`
487 - The parent asks a child's database (is this session the child's, is its
488 crew at work, its public apps) off its serving thread, with a deadline, and
489 only of plain tables: a view of the same name is never run, and a statement
490 that does not end costs that child one answer of "unknown" and nobody else
491 anything.
492 Enforced by: `test/child-db-off-thread.test.ts`
493 - What the parent writes and reads in a child's directory from outside its
494 cell (the stop note, the plan notice, the credit, the app links, the starts
495 ledger, the key file) follows no link the child left there: one writer that
496 makes its own file and moves it into place, one reader that takes a regular
497 file or nothing and never waits on a pipe. A link under the key's name is a
498 refusal, never read through and never minted over.
499 Enforced by: `test/boundary-tenancy-files.test.ts`
500 - A child's own code is found and copied only from a repository in its own
501 directory with no link in it, and what is recorded when its start fails is a
502 sentence from the parent's list, whatever was handed in.
503 Enforced by: `test/boundary-tenancy-files.test.ts`
504 - Side by side, one child's cell has namespaces of its own for users,
505 processes, network, IPC and hostname; its way out reaches its own door on
506 the parent by that exact port and refuses a neighbour's door, a neighbour's
507 port and the parent's own port on loopback; and a heartbeat or a model
508 bearer made with one child's key opens nothing of another's.
509 Enforced by: `test/boundary-tenancy-cell.test.ts`
510 - A child is held to its size by the kernel where the forge has a delegated
511 cgroup: memory (no swap, the whole cell killed together), cores, processes
512 and disk bandwidth, at a tenth of the forge's own weight. Where it has
513 none, the hold changes hands and is said: a pin and pausing for cores, the
514 watch for memory and processes.
515 Enforced by: `test/boundary-tenancy-limits.test.ts`
516 - The forge keeps memory for itself that the cells together cannot take: a
517 floor on its own cgroup where that is delegated (`memory.min` and
518 `memory.low`, a limit an admin sets), and every cell's and crew run's first
519 process raises its own `oom_score_adj` above the forge's, so short of memory
520 the kernel chooses a cell first. No hosted forge is refused a start for
521 memory: when the sizes together pass the machine, /forges and the forge's
522 needs say so in one line. Proven as the files written and the argv a cell
523 starts as, not as the kernel's behaviour; a cell that sets out to can lower
524 its figure back to the forge's own, never below it.
525 Enforced by: `test/boundary-tenancy-limits.test.ts`
526 - Beyond its parent, a hosted forge's cell reaches only what the parent's
527 settings name, each on 443: the model, registry and payment hosts, the
528 public git hosts, and the forges its parent holds beside it (one name ending
529 in `--<parent's host>`). No other name under the parent's domain opens, and
530 the list never holds a wildcard on a domain: under a shared suffix that
531 would be everyone's host there.
532 Enforced by: `test/spawn-cell.test.ts`
533 - A name on a cell's list is still held to every address it resolves to: one
534 private, loopback, link-local, tailnet or metadata answer among public ones
535 refuses it, in every spelling, whichever entry named it. A name that is not
536 on the list is refused before it is looked up, and nothing is dialled.
537 Enforced by: `test/boundary-outbound.test.ts`
538 - A name an admin allows a hosted forge beyond that list is one public host
539 name on 443, for that forge alone or for every one: never an address, a
540 wildcard, another port or a name that is private by its shape, whether the
541 forge asked for it or the admin typed it, and a name that resolves inside a
542 network is not taken as an ask. A granted name is still judged by every
543 address it resolves to. Only a person who is a site admin answers, from the
544 parent's own pages; a form sent from another site changes nothing. What the
545 hosted forge says about who asked and why is cleaned and only ever shown.
546 Enforced by: `test/ask-to-reach.test.ts`
547 - A sign-in the parent brokers for a hosted forge hands the token over once,
548 inside a minute, to the forge that began it and to no other, and what the
549 parent keeps is an event naming the forge, the host and the account: never
550 a token or a code. Before the provider is asked anything, the parent shows
551 the person one page that names the hosted forge, from the parent's own
552 ledger, and the provider, with one way on: the provider's own consent names
553 the parent's application and may ask nothing.
554 Enforced by: `test/origin-broker.test.ts`
555 - A token a brokered sign-in sealed is deleted after its minute across a
556 restart too: the broker's rows are swept as the forge boots.
557 Enforced by: `test/origin-broker-boot.test.ts`
558
559 - The repository a child's proposal credential is bound to is the parent's to say: the
560 template repository its own ledger names, else its own code, as it forked the child. A
561 child that writes another repository into its `parent.json` is refused and the refusal
562 logged; no token is minted for the repository it named (#14759).
563 Enforced by: `test/proposal-handout.test.ts`
564
565 ## Honeypots (later)
566
567 A `kind: "honeypot"` app, a decoy that records what touches it, is not built.
568 `forge.json` accepts `web` and `service` only. Before one may exist:
569
570 - the cell must hold (above), since the point is to run hostile traffic next to
571 real apps;
572 - its egress must be none, not declared hosts;
573 - it must carry no secret, no token and no data from any real app;
574 - what it records must be bounded and escaped like any other input.
575
576 Until then, nothing here claims one.
21 - [A snooper on the network](threats/snooper.md)
22 - [A stolen token](threats/stolen-token.md)
23 - [A compromised vendor](threats/compromised-vendor.md)
24 - [A hostile agent inside a run](threats/hostile-agent.md)
25 - [An automated attacker at scale](threats/automated-attacker.md)
26 - [Internal calls](threats/internal-calls.md)
27 - [A child forge running its own code (#11144)](threats/child-forge.md)
28 - [Honeypots (later)](threats/honeypots.md)
docs/threats/automated-attacker.md added +85
@@ -0,0 +1,85 @@
1 ## An automated attacker at scale
2
3 Wants: accounts, spam, resources, or a way to exhaust the forge.
4
5 - Request bodies are capped at the boundary.
6 Enforced by: `test/body-limits.test.ts`
7 - Parsers survive generated hostile input.
8 Enforced by: `test/fuzz-parsers.test.ts`
9 - Anonymous spawn is rate limited per client address.
10 Enforced by: `test/spawn-anon.test.ts`
11 - Every door a stranger can reach that costs (API reads, clones, code
12 search on the page, the API and the terminal's guest palette, event
13 streams, spawn plans) is limited per address and for every stranger
14 together (`src/http/strangers.ts`, docs/ARCHITECTURE.md, concurrency
15 invariant 7); a signed-in push keeps its share of the pool.
16 Enforced by: `test/strangers.test.ts`
17 - The client address is the socket's peer unless that peer is a configured
18 trusted proxy; `X-Forwarded-For` is read from the right, past trusted hops.
19 Enforced by: `test/client-address.test.ts`
20 - A new-account guard can refuse repository creation and forks for young
21 accounts.
22 Enforced by: `test/guard-new-accounts.test.ts`
23 - Sign-up has a ceiling per address and for the whole forge, per minute and per
24 hour, and an admin can close it at once.
25 Enforced by: `test/guest-contribute.test.ts`
26 - A guest owns only a contribution fork of a public repository. It holds no
27 settings, secrets or app, nothing runs for it, and its storage, forks and
28 pulls are limited (`docs/ROLES.md`).
29 Enforced by: `test/guest-contribute.test.ts`
30 - An outside agent with a contribute token (no account) pushes its branch into
31 the repository itself, so where a head lives says nothing about who wrote it:
32 a `contrib/<agent>/<segment>/…` head is a guest's. Its check runs with
33 nobody's permission, behind the owner's and the crew's work, in a cell that
34 holds no variable, token or secret and is held to the hosts and limits the
35 base branch declares; nothing from its branch is previewed, and the crew
36 leaves it, until a writer approves the pull once. On a machine with no
37 cell its check does not run unapproved either, and says the press that
38 lifts it.
39 Enforced by: `test/boundary-tokens-crew.test.ts`
40 - An outside agent gets one harmless head of its pull approved by the crew's
41 reviewer (or steers the reviewer by prompt injection), then pushes a new
42 head whose preview would hold the app's settings. A reviewer's approval
43 holds for the head it read only; the new head waits again for a person or
44 a new review. A person's approval is for the pull, as before.
45 Enforced by: `test/outside-lane.test.ts`
46 - A fork shares its parent's git objects, and git answers for any object a
47 store holds to whoever names it by id. So someone who reads a fork and may
48 not read its parent (the parent was made private after the fork; they left
49 its organisation or its crew) is held to what the fork's own refs reach: at
50 the git door over protocol v2 and v0, for a commit, a tree or a file, and at
51 the fork's pages, API, tools and terminal by a full id or a short one,
52 answered exactly as an id nothing holds. A `shallow <id>` line is held like a
53 want, for a held reader and a runner's job token alike, when the fetch
54 deepens without a bound: `deepen 0`, `deepen 2147483647` (what
55 `--unshallow` sends), any `deepen` git would not read as a plain depth, and
56 `deepen-relative` at any depth. Git would unshallow such an id from the
57 shared store and send its parents. Every `shallow` id is held too while
58 the first flush has not arrived, so a request cut off before it is held
59 as one that deepens without a bound. A finite `deepen`, `deepen-since` and
60 `deepen-not` walk only from the wants, which are held, so their `shallow`
61 lines are not: git sends no `unshallow` for them and no object of them,
62 and a runner's kept shallow clone still fetches. Still open (#14850): a
63 `have` the lender holds is ACKed and a `shallow` naming a lender's tree
64 makes git die, so someone with a full id can learn it exists, though not
65 what it holds. A parent that is not public no
66 longer moves a public fork, and a push into such a fork must carry every new
67 object it names. Everyone else fetches as before, partial clones included.
68 What a fork's own refs already held stays the fork's: the read-only
69 `forks-beyond-parent` script lists the forks to look at.
70 Enforced by: `test/boundary-fork-objects.test.ts`
71 - A pull whose head lives in a fork, here or on the origin, and a child's
72 proposal run nothing until a person who can write the repository approves
73 that exact head, and the crew never lands one.
74 Enforced by: `test/guest-contribute.test.ts`
75 - A branch in the repository itself was put there by someone who may write it
76 (on a mirror, by someone its origin lets write), so its check and preview
77 run at once. When its author is a guest from the origin, its preview and
78 that preview's terminal still hold none of the app's variables, no forge
79 token and no copy of production's data until a writer approves the pull.
80 Enforced by: `test/boundary-secrets-process.test.ts`
81 - Every limit is a setting with its reason, changed by an admin only.
82 Enforced by: `test/limits.test.ts`
83 - Distributed attacks across many addresses: only the whole-forge caps stand
84 here.
85 Enforced by: none yet
docs/threats/child-forge.md added +112
@@ -0,0 +1,112 @@
1 ## A child forge running its own code (#11144)
2
3 A cell child's owner may switch it from the parent's code to its own `<org>/forge` main (`spawn/own_code.ts`). The code is then the child's author's, so treat it as hostile code in a cell, the same as any app.
4
5 What it cannot reach: the cell's memory, CPU, disk and I/O limits, its sandbox and its egress list are the same as with the parent's code, and nothing in the child's repository is read to make them. The parent's data, home and temporary directory are hidden; only the parent's code and the one checkout (a tree, with no `.git`) are revealed, read-only. Its `forge.json` is not run by the parent: the parent finds the repository only as a directory of the child's own (never through a link), refuses a repository or tree over 256 MB or 50,000 files and any symbolic link in either, checks that `src/main.ts` parses and `forge.json` is JSON, and never executes the child's code outside the cell. What the parent records about a failed start is fixed wording: one of a list of the parent's own sentences. Nothing the child wrote or printed reaches the ledger, the rollback row or the `forge.rolled_back` event; its last lines go to the parent's log.
6
7 What it can reach: everything a child forge can reach, no more: its own data directory, the parent's heartbeat door and public address, the hosts the admin allowed for models, registry, payment and origins (the public git hosts and the forges its parent holds beside it), and the sign-ins its parent brokers for it. It can lie in what it serves and in its heartbeat, and can break itself: a start that fails to answer within the deadline rolls back to the last commit that came up, then to the parent's code, and the owner's `/forges` page shows a Rolled back row saying so. A commit that failed is not tried again until main moves. A child that comes up and breaks later is not rolled back; the owner switches it off. Hosted children run inside the parent's process and cannot turn this on.
8
9 - The cell limits, sandbox, egress list and hidden parent paths are built by the
10 parent from outside, never read from the child's repository, so a child's own
11 code is held exactly like any app.
12 Enforced by: `test/own-code.test.ts`
13 - A forge made in a cell stays a cell child. A cell that does not start
14 leaves it stopped, its address and its host's forges page saying why and
15 when the host tries again; it is not opened in the parent's process for
16 that, since its directory (its repositories' hooks and git config included)
17 is the child's to write. Only a host that holds no cell at all runs a child
18 in its own process, and never one that has run code of its own.
19 Enforced by: `test/spawn-cell-stays.test.ts`
20 - A forge that still runs inside its parent's process (made before cells, or
21 put there by an older release) is moved into a cell of its own, by an
22 admin's button or by the forge's own pass at boot and when one sleeps; a
23 move that does not prove itself is put back (the sizes it is given are held
24 by `test/spawn-move-cell-sizes.test.ts`).
25 Enforced by: `test/spawn-move-cell.test.ts`
26 - Before such a forge leaves its parent's process its repositories are read,
27 running nothing, for what that process may have executed while it had no
28 wall: hooks beyond the forge's own stubs and config keys that make git run
29 a command, reported by name and never by content.
30 Enforced by: `test/spawn-move-scan.test.ts`
31 - A host that holds every forge in a cell seals: it opens no forge in its
32 own process again whatever a ledger says, never moves a cell child into
33 its process because its own probe of cells failed, and places a new forge
34 in a cell or not at all.
35 Enforced by: `test/spawn-sealed-host.test.ts`
36 - The parent asks a child's database (is this session the child's, is its
37 crew at work, its public apps) off its serving thread, with a deadline, and
38 only of plain tables: a view of the same name is never run, and a statement
39 that does not end costs that child one answer of "unknown" and nobody else
40 anything.
41 Enforced by: `test/child-db-off-thread.test.ts`
42 - What the parent writes and reads in a child's directory from outside its
43 cell (the stop note, the plan notice, the credit, the app links, the starts
44 ledger, the key file) follows no link the child left there: one writer that
45 makes its own file and moves it into place, one reader that takes a regular
46 file or nothing and never waits on a pipe. A link under the key's name is a
47 refusal, never read through and never minted over.
48 Enforced by: `test/boundary-tenancy-files.test.ts`
49 - A child's own code is found and copied only from a repository in its own
50 directory with no link in it, and what is recorded when its start fails is a
51 sentence from the parent's list, whatever was handed in.
52 Enforced by: `test/boundary-tenancy-files.test.ts`
53 - Side by side, one child's cell has namespaces of its own for users,
54 processes, network, IPC and hostname; its way out reaches its own door on
55 the parent by that exact port and refuses a neighbour's door, a neighbour's
56 port and the parent's own port on loopback; and a heartbeat or a model
57 bearer made with one child's key opens nothing of another's.
58 Enforced by: `test/boundary-tenancy-cell.test.ts`
59 - A child is held to its size by the kernel where the forge has a delegated
60 cgroup: memory (no swap, the whole cell killed together), cores, processes
61 and disk bandwidth, at a tenth of the forge's own weight. Where it has
62 none, the hold changes hands and is said: a pin and pausing for cores, the
63 watch for memory and processes.
64 Enforced by: `test/boundary-tenancy-limits.test.ts`
65 - The forge keeps memory for itself that the cells together cannot take: a
66 floor on its own cgroup where that is delegated (`memory.min` and
67 `memory.low`, a limit an admin sets), and every cell's and crew run's first
68 process raises its own `oom_score_adj` above the forge's, so short of memory
69 the kernel chooses a cell first. No hosted forge is refused a start for
70 memory: when the sizes together pass the machine, /forges and the forge's
71 needs say so in one line. Proven as the files written and the argv a cell
72 starts as, not as the kernel's behaviour; a cell that sets out to can lower
73 its figure back to the forge's own, never below it.
74 Enforced by: `test/boundary-tenancy-limits.test.ts`
75 - Beyond its parent, a hosted forge's cell reaches only what the parent's
76 settings name, each on 443: the model, registry and payment hosts, the
77 public git hosts, and the forges its parent holds beside it (one name ending
78 in `--<parent's host>`). No other name under the parent's domain opens, and
79 the list never holds a wildcard on a domain: under a shared suffix that
80 would be everyone's host there.
81 Enforced by: `test/spawn-cell.test.ts`
82 - A name on a cell's list is still held to every address it resolves to: one
83 private, loopback, link-local, tailnet or metadata answer among public ones
84 refuses it, in every spelling, whichever entry named it. A name that is not
85 on the list is refused before it is looked up, and nothing is dialled.
86 Enforced by: `test/boundary-outbound.test.ts`
87 - A name an admin allows a hosted forge beyond that list is one public host
88 name on 443, for that forge alone or for every one: never an address, a
89 wildcard, another port or a name that is private by its shape, whether the
90 forge asked for it or the admin typed it, and a name that resolves inside a
91 network is not taken as an ask. A granted name is still judged by every
92 address it resolves to. Only a person who is a site admin answers, from the
93 parent's own pages; a form sent from another site changes nothing. What the
94 hosted forge says about who asked and why is cleaned and only ever shown.
95 Enforced by: `test/ask-to-reach.test.ts`
96 - A sign-in the parent brokers for a hosted forge hands the token over once,
97 inside a minute, to the forge that began it and to no other, and what the
98 parent keeps is an event naming the forge, the host and the account: never
99 a token or a code. Before the provider is asked anything, the parent shows
100 the person one page that names the hosted forge, from the parent's own
101 ledger, and the provider, with one way on: the provider's own consent names
102 the parent's application and may ask nothing.
103 Enforced by: `test/origin-broker.test.ts`
104 - A token a brokered sign-in sealed is deleted after its minute across a
105 restart too: the broker's rows are swept as the forge boots.
106 Enforced by: `test/origin-broker-boot.test.ts`
107
108 - The repository a child's proposal credential is bound to is the parent's to say: the
109 template repository its own ledger names, else its own code, as it forked the child. A
110 child that writes another repository into its `parent.json` is refused and the refusal
111 logged; no token is minted for the repository it named (#14759).
112 Enforced by: `test/proposal-handout.test.ts`
docs/threats/compromised-vendor.md added +79
@@ -0,0 +1,79 @@
1 ## A compromised vendor
2
3 Wants: to run its code on the forge or in an app through something the forge
4 trusts: a package, a model provider, a hosting provider, an origin it syncs from.
5
6 - The forge has no runtime dependencies, so there is no package to poison in the
7 forge itself.
8 Enforced by: `test/deps.test.ts`
9 - An app's code runs in a cell: read-only machine, empty data directory and
10 home, own pid and network namespaces, memory, CPU and disk watched. A
11 dependency an app pulls in gets no more than the app does.
12 Enforced by: `test/contain.test.ts`
13 - A cell binds each directory it may write once, nothing inside one by name,
14 and only a directory that is there itself: a link its code leaves where its
15 home goes is never mounted. What it hides (the forge's data, home and temp)
16 is covered under the name it really has as well as the one it was given,
17 before its own directory is bound back, and no neighbour's directory is
18 ever shown.
19 Enforced by: `test/boundary-tenancy-cell.test.ts`
20 - What a cell prints costs the forge one line at most, however long it goes
21 without a newline: an app's or a step's line is cut at 64 KiB as it arrives
22 and says so, a hosted forge's at 500 characters. That text is held in the
23 forge's own memory, outside the cell's cap.
24 Enforced by: `test/boundary-tenancy-limits.test.ts`
25 - A cell's disk is counted to the end or the cell is over it: the walk goes as
26 far as the cell's own limit of files (as many as its disk has 4 KiB blocks,
27 a million at least), and a cell that reaches it is stopped and told so,
28 never counted as the part that was seen.
29 Enforced by: `test/boundary-tenancy-limits.test.ts`
30 - Outside Kubernetes a cell sees the machine's mounts minus the ones that may
31 carry a secret (every tmpfs, everything under `/run`): a second mount of the
32 data volume, an env file or a backup volume bound in at another path is
33 readable in every cell. `FORGE_CELL_MOUNTS=allow-list` closes it; it is not
34 yet the default wherever the forge runs in a container.
35 Enforced by: none yet
36 - A preview's copy of production's data is taken while production runs and
37 can swap any entry for a link to a host path (`secret.key`, `forge.db`,
38 another tenant's data): the forge walks it through held directory
39 descriptors with `O_NOFOLLOW`, copies a link as a link and never what it
40 points at, and checkpoints SQLite only in the copy it alone writes, where
41 `quick_check` refuses a database torn by a write mid-copy (copied again,
42 five times at most, then the seed fails); a log is copied before its
43 database and its shared-memory index never. An app's backup seals such a
44 snapshot, never the live directory.
45 Enforced by: `test/apps-data-symlink-race.test.ts`
46 - An app that prints the variables, identity key or forge token it was handed
47 leaves `[redacted]` in its deploy's log, plain or encoded, so a careless
48 dependency does not publish them to everyone who can read the runs.
49 Enforced by: `test/boundary-secrets-process.test.ts`
50 - The only way out of a cell is the egress proxy, which reaches the hosts the
51 repository declared and refuses names that resolve to private, loopback or
52 metadata addresses.
53 Enforced by: `test/apps-adversarial.test.ts`
54 - The website-spec check the forge runs from its own process against a live
55 preview fetches only the preview's own origin: an icon, manifest or
56 stylesheet the app's HTML names on another host (metadata, a private or
57 tailnet address, another app's loopback port) is reported as off-origin and
58 never fetched, and no request follows a redirect (#14755).
59 Enforced by: `test/webspec.test.ts`
60 - A connected origin's replies are validated at the boundary and not trusted for
61 identity.
62 Enforced by: `test/origins-security-provider.test.ts`
63 - A push to an origin is vetted like a fetch from one: a name that resolves
64 to a private, loopback, link-local, tailnet or metadata address is refused
65 before git starts, in the fetch's words; git dials the address that was
66 judged and follows no redirect. A hosted forge's proposal to its parent
67 trusts the parent's host by name for that one push.
68 Enforced by: `test/mirror-outbound-push.test.ts`
69 - A migration from a connected origin clones only from that origin's own host,
70 whatever `clone_url` its reply names, and that address is vetted and pinned
71 like a pasted one: a private, loopback, link-local or metadata answer is
72 refused before git starts (#14756).
73 Enforced by: `test/migrate.test.ts`
74 - Pushes from an origin cannot rewrite what the forge protects.
75 Enforced by: `test/origins-security-push.test.ts`
76 - Backups are encrypted before they leave the machine.
77 Enforced by: `test/snapshot-store.test.ts`
78 - A review of lockfile changes (`bun.lock`) before they reach an app's cell.
79 Enforced by: none yet
docs/threats/honeypots.md added +12
@@ -0,0 +1,12 @@
1 ## Honeypots (later)
2
3 A `kind: "honeypot"` app, a decoy that records what touches it, is not built.
4 `forge.json` accepts `web` and `service` only. Before one may exist:
5
6 - the cell must hold (above), since the point is to run hostile traffic next to
7 real apps;
8 - its egress must be none, not declared hosts;
9 - it must carry no secret, no token and no data from any real app;
10 - what it records must be bounded and escaped like any other input.
11
12 Until then, nothing here claims one.
docs/threats/hostile-agent.md added +138
@@ -0,0 +1,138 @@
1 ## A hostile agent inside a run
2
3 Wants: to read what it was not given, reach what it may not, or land code no
4 person approved.
5
6 - The agent's shell may reach only the forge, the package registry and its
7 own repository's app (production and each open pull's preview), by exact
8 host, and never another repository's app. The
9 forge's repositories, index, key and every other agent's clone are denied by
10 name and by allow-list, and a listing that fails refuses the run.
11 Enforced by: `test/crew-sandbox.test.ts`
12 - No name a tenant chose is allowed whole, since the tenant can point its
13 DNS at loopback, a private network or the metadata address. An app is
14 reached at the slug host the forge serves, never at its verified custom
15 domain. A member's model gateway must be a public dotted name (no IP
16 literal, `localhost`, single label or private suffix), and the run's shell
17 is never allowed the gateway's name. A row saved before the rule is never
18 picked and never dialled (#14750).
19 Enforced by: `test/crew-sandbox-tenant-hosts.test.ts`
20 - A member's gateway name can still be repointed after it is saved, so
21 nothing dials it unjudged: Claude Code, for a run and for the usage check,
22 is pointed at the forge's loopback door (`crew/gateway_door.ts`), which
23 sends each request through `outboundFetch` — resolved, every address
24 judged, dialled at the judged address — and the run's shell is allowed only
25 that door's port (#14750).
26 Enforced by: `test/crew-gateway-door.test.ts`
27 - The one place a run writes beside its clone and temp directory is its
28 repository's bun install cache (`crew/.cache/<repo id>/bun`), which every
29 run on that repository can write: a run can poison what the next run on the
30 same repository installs. It is per repository: the cache root is denied whole
31 and only this repository's directory re-allowed, so a cache made later is
32 denied too, and deleting the repository removes it.
33 Enforced by: `test/crew-install-cache.test.ts`
34 - The crew's dependency install runs on the host, in a clone the repository
35 and earlier runs filled: a lockfile, `package.json`, `node_modules` or
36 `node_modules/.forge-lock-hash` that is a link (to `forge.db`,
37 `secret.key`, `/dev/zero`, another repository's directory) is refused or
38 replaced, never read or written through (#14751). A link that names
39 nothing counts as present and is refused, never read as absent. The
40 lockfile and mark are read on the open file (`O_NOFOLLOW`, then `fstat`),
41 so nothing can be swapped in between a check and a read. One window
42 remains, and it is stated here: `node_modules` is checked with `lstat`
43 before `bun install` runs and again just before the mark is written, but
44 `bun install` itself and the mark's rename go by name. Swapping a path in
45 that window needs something running in the clone at the same time, and
46 nothing in this run is: the install runs in the run's setup, before its
47 agent session starts (`src/crew/runner.ts`), and `--ignore-scripts` runs
48 no code from the repository. Two runs sharing one clone at once would
49 reopen the window; that is not what this item covers.
50 Enforced by: `test/install-links.test.ts`
51 - A check's cache fill reads the pull's `bun.lock` and `package.json` on the
52 host only as regular files of at most 64 MB, opened without following a
53 link and never waiting on a pipe or device: a committed link to a host
54 file leaks none of it into the check log, and one to `/dev/zero` cannot
55 hold the forge (#14751).
56 Enforced by: `test/install-links.test.ts`
57 - A check's cell reads its repository's shared bun cache
58 (`check-install/<repo id>/bun`) through a read-only bind and cannot write
59 it, so one pull cannot plant a package the gate on main installs. The
60 forge fills it on the host with `--ignore-scripts`, and reads no
61 `bunfig.toml` or `.npmrc` of the pull's.
62 Enforced by: `test/check-install.test.ts`
63 - An app environment's cell reads that same cache read-only and
64 copies from it, so a preview cannot plant a package production installs;
65 the forge fills it through the same lockfile rule as a check's.
66 Enforced by: `test/app-install-cache.test.ts`
67 - The forge fills that cache only from a lockfile whose every package is a
68 registry `name@version` with a sha512 integrity (`checks/fillable.ts`):
69 the host never fetches a URL a pull chose and reads no file, link or
70 workspace a pull points at, an override's or resolution's included.
71 Enforced by: `test/check-fillable.test.ts`
72 - A locked tarball URL is "" or exactly the registry's tarball of that
73 entry's `name@version`, so a pull cannot lock another package's tarball
74 (even one on the registry, with its own integrity) under a name and
75 version and plant it in the shared cache, where bun does not re-check it
76 on a hit (#14761): the test "a tarball url of another package on the
77 registry cannot be locked under this name@version".
78 Enforced by: `test/check-fillable.test.ts`
79 - The same policy holds against a real bubblewrap, not only as a string.
80 Enforced by: `test/crew-sandbox-real.test.ts`
81 - The OpenAI-compatible runner's Bash is held to the same policy: every
82 denied path is covered in its bubblewrap (the key, the index, the
83 repositories, every other agent's directory), only the clone, its temp
84 directory and its install cache are writable, and its network namespace's
85 one way out is the forge's egress proxy, which passes the policy's hosts
86 alone and refuses loopback, private addresses and the metadata service.
87 Enforced by: `test/openai-runner-escape.test.ts`
88 - That runner's file tools refuse a path through a link to nothing (one the
89 shell planted, or a checkout made), and write with `O_NOFOLLOW`, so Write
90 cannot create a file outside the clone with the forge's own rights.
91 Enforced by: `test/openai-runner-escape.test.ts`
92 - That runner takes its endpoint, key and model from the forge's own
93 environment, never the run's: a granted secret cannot name the URL the
94 operator's key is sent to, a secret cannot be named `OPENAI_*`, and the
95 endpoint's redirects are refused.
96 Enforced by: `test/openai-runner-escape.test.ts`
97 - Git the forge runs on the host in a crew clone (the wrap-up's status, add,
98 commit and push, a kept clone's fetch, reset and checkout, the leak scan)
99 runs nothing the agent planted there: every call goes through
100 `crew/clone_git.ts`, which refuses a `.git` that is a link, a gitfile or
101 borrows another repository, names `--git-dir` and `--work-tree` (so
102 `core.worktree` points nowhere), and pins hooks, `core.fsmonitor`, every
103 filter and diff driver the clone's config names, ssh and every transport
104 but http(s) off on the command line, above the clone's own config. The
105 forge's commit passes `--no-verify` (#14747).
106 Enforced by: `test/crew-clone-git.test.ts`
107 - The stale-clone sweep's git in an idle clone (`crew/orphans.ts`) runs the
108 same way, with the git environment and not the forge's, so a planted
109 `core.fsmonitor` neither runs nor sees a forge secret (#14747).
110 Enforced by: `test/crew-clone-git.test.ts`
111 - Under the OpenAI-compatible runner the clone's `.git/config` and
112 `.git/hooks` are bound read-only in the shell's bubblewrap, as in the
113 Claude runner's sandbox, and its Write and Edit tools refuse any path in
114 `.git`, by name or through a link (#14747).
115 Enforced by: `test/crew-clone-git.test.ts`
116 - A pull's check and its preview reach the hosts, and run at the limits, that
117 its base branch's `forge.json` declares, never the ones its own asks for,
118 until the pull lands: code on a branch, the crew's as much as a guest's,
119 cannot widen where its own check and preview send what they hold. The
120 pull's page and the top of its logs say in one line what it asked for and
121 that it applies when the pull lands.
122 Enforced by: `test/boundary-pull-egress.test.ts`
123 - An agent cannot push to the default branch or merge; a person merges.
124 Enforced by: `test/protection.test.ts`
125 - An outside agent that drives a person's account cannot push past the pulls
126 either: a protected default takes a push from its admins only, so every
127 other writer lands through a pull, its gate and its review.
128 Enforced by: `test/protected-default-push.test.ts`
129 - A variable set with no scope named is production's alone: a pull's preview,
130 which runs code nobody has landed, reads a variable only when its owner
131 chose "Also in previews" or set one for previews.
132 Enforced by: `test/app-env.test.ts`
133 - Merge gates (checks, review) are enforced in the merge path, not by convention.
134 Enforced by: `test/security-merge.test.ts`
135 - Spend, time and turns per run are limited.
136 Enforced by: `test/crew-limits.test.ts`
137 - Rendered output escapes everything an agent wrote.
138 Enforced by: `test/security-xss.test.ts`
docs/threats/internal-calls.md added +24
@@ -0,0 +1,24 @@
1 ## Internal calls
2
3 `FORGE_SELF_SWAP=1` binds the web port with SO_REUSEPORT so a release can share
4 it, which also lets any process running as the forge's user join the listener
5 and take a share of its connections, login posts included. It assumes nothing
6 else runs as that user on the host network (agents and apps are sandboxed or in
7 cells). Only one swap is made per process, so two landings never leave two
8 releases serving. The swap is refused unless `net.ipv4.tcp_migrate_req=1`, for
9 without it the old listener closing resets queued connections.
10 Enforced by: `test/release-swap.test.ts`
11
12 How each part proves itself to the next, today.
13
14 | Call | Authenticated by | Enforced by |
15 | --- | --- | --- |
16 | runner → forge | the run's scoped token (`FORGE_TOKEN`) and a few-minute passport (`FORGE_PASSPORT`) | `test/passport-edge.test.ts` |
17 | git hook → forge | per-boot secret in `x-forge-hook-secret` on the internal listener; a call without it is refused and counted | `test/crew-sandbox.test.ts` |
18 | cell → proxy | the proxy's Unix socket bound into the cell's own network namespace; no credential, the namespace is the identity | `test/contain.test.ts` |
19 | host → cell | the relay carrying a visitor to an app dials the cell's `in.sock` by the inode it opened with `O_PATH \| O_NOFOLLOW` and checked (a socket, the cell's uid, one name), through `/proc/self/fd/N`, so a symlink or hard link the cell plants there reaches no host socket, and the refusal is a line in the owner's log; the uid check holds because a cell runs as the forge's own uid (`--unshare-user` with no `--uid`/`--gid`, `cellNamespaces`) (#14752) | `test/cell-socket-pin.test.ts` |
20 | edge → pod | `X-Plat-Edge-Token` equal to `FORGE_EDGE_TOKEN`, compared as fixed-width digests; without it `X-Plat-User` is ignored; the `signin.edge` setting (admin, refused for an admin with no password or passkey) turns the edge's identity off on every door | `test/edge-auth.test.ts` |
21 | child → parent | a heartbeat and a brokered sign-in are signed (HMAC) with the key spawn gave both sides, looked up by the name inside the signed body, so the door a call arrives on says nothing about whose it is; the lent model by a bearer whose hash the parent keeps; a child's door answers those routes and nothing else. Code is pulled over public git, and the claim link (sha256 kept, 24 hours, single use) hands the child to its person | `test/boundary-tenancy-cell.test.ts` |
22
23 Gaps: edge → pod and runner → forge ride a shared secret, not a per-call
24 signature.
docs/threats/snooper.md added +17
@@ -0,0 +1,17 @@
1 ## A snooper on the network
2
3 Wants: session cookies, tokens and pushed code in transit, or to learn who
4 talks to whom.
5
6 - Sessions are HttpOnly cookies, `Secure` when the request came over https, so
7 script cannot read one and a plain-http hop does not carry it.
8 Enforced by: `test/own-session.test.ts`
9 - Tokens are shown once; the database keeps only their sha256, so a copy of the
10 index does not replay as a login.
11 Enforced by: `test/tokens.test.ts`
12 - TLS is terminated by the edge in front of the forge, and certificates are
13 issued only for names the forge vouches for (`on_demand_tls` ask).
14 Enforced by: none yet
15 - Between the edge and the forge process, and between forge and cell, traffic is
16 plain HTTP on one machine or a pod network. Nothing encrypts it.
17 Enforced by: none yet
docs/threats/stolen-token.md added +87
@@ -0,0 +1,87 @@
1 ## A stolen token
2
3 Wants: to act as the person or agent it was issued to, for as long as it works.
4
5 - Tokens carry a scope and an optional expiry; a narrower token cannot do what a
6 wider one can.
7 Enforced by: `test/tokens.test.ts`
8 - A crew run's secrets are named in the brief, opened per run, redacted from the
9 log, and released when the run ends.
10 Enforced by: `test/run-secrets.test.ts`
11 - The model credential in a crew run's environment is held for redaction like a
12 granted secret, from before the agent starts until the run ends: a run that
13 says it leaves `[redacted]` in its log, its summary and every event. The
14 two other children the forge starts with that credential, a one-shot and a
15 conversation turn, are held the same way.
16 Enforced by: `test/boundary-secrets-run.test.ts`
17 - A passport (`fp1.…`) is bound to one audience and scope set and dies in
18 minutes, so a copy lifted from a run is useful to one door briefly.
19 Enforced by: `test/passport.test.ts`
20 - Sign-in attempts are throttled per client, with a whole-forge cap beside it; eight wrong passwords at one account from one client in ten minutes shut that pair until the window passes (`src/core/signin-window.ts`, #14373).
21 Enforced by: `test/signin-throttle.test.ts`
22 - Stored provider tokens (origins) are sealed under a key in `secret.key`, never
23 returned by any route.
24 Enforced by: `test/origins-security-auth.test.ts`
25 - The operator's GitHub application (`FORGE_GITHUB_CLIENT_ID`, `_SECRET`) is
26 github.com's alone: a host a member calls GitHub Enterprise gets no app, and
27 the secret is withheld from every other host at the device poll, the
28 refresh and the revoke, whatever registration carries it (#14757).
29 Enforced by: `test/origins-github-secret.test.ts`
30 - The SSH host key and the database files are created 0600; a host key group-
31 or world-readable is refused, and a database file found too open is a
32 degraded finding naming the chmod, never a silent change and never a stop.
33 Enforced by: `test/file-modes.test.ts`
34 - The files a forge's family keeps keys in (`parent.json`: the heartbeat key, a
35 proposal token, a read credential offered and not yet sealed; the parent's
36 `spawn/<name>.json`: the status token and the heartbeat key) are written 0600
37 (`writePrivate`), and one found wider is narrowed at boot and said once.
38 Enforced by: `test/boundary-tokens-follow.test.ts`
39 - A token bound to one repository (a run's, a child's, an outside agent's, an
40 app's) is refused on every route of every other repository before the
41 route's handler runs, and ends with its repository: it never becomes an
42 unbound one.
43 Enforced by: `test/boundary-tokens-gates.test.ts`
44 - Every such token is minted with an end, read on every use, and its own
45 revoke ends it at the next request, with no restart and no wait. A
46 repository's admin sees and ends every child's read of it, whoever it was
47 minted as; a suspended account's tokens stop with it.
48 Enforced by: `test/boundary-tokens-gates.test.ts`
49 - A crew run's git offers its token to this forge's two addresses and to no
50 other host it talks to, and the token ends with the run.
51 Enforced by: `test/boundary-tokens-crew.test.ts`
52 - The credential a child holds to read a private app is minted for that one
53 repository and kept by the parent as a hash; the child seals it with its own
54 key and keeps it in no file, config or address. It lives a week at a time,
55 renewed while the child follows, and ends when the child is removed, refuses
56 the offer or is revoked; no log line or event on either forge carries it.
57 Enforced by: `test/boundary-tokens-follow.test.ts`
58 - A child's tokens and an outside agent's contribute token never enter an app
59 at its own host, whoever's account they ride on. The token a preview's own
60 process holds reaches its repository, its timers and its printer, and
61 nothing else of its owner's.
62 Enforced by: `test/boundary-tokens-apphost.test.ts`
63 - Only a forge admin sets or removes a secret, and nothing is opened for
64 anyone else. An open leaves one `secret.read` per name opened; no event
65 carries a value, plain or sealed; the data browser shows no sealed column.
66 The key file is 32 bytes only its owner reads, and one that others can read
67 is refused by name. A lost key costs the values and nothing else. Deleting a
68 repository removes the secrets scoped to it.
69 Enforced by: `test/boundary-secrets-store.test.ts`
70 - A secret kept for the forge or an organization reaches a repository's app
71 and its crew's runs only after a forge admin granted that name to that
72 repository; a repository's own secrets need no grant. A name a run declares
73 and nobody granted is never opened: the run goes on without it and says so
74 in its log and once on its issue, with the link that grants it.
75 Enforced by: `test/boundary-secrets-store.test.ts`
76 - A production app's `FORGE_TOKEN` is its owner's read-only token: the app's
77 code and what it depends on read everything its owner reads, every private
78 repository included. A preview's is bound to the app's one repository;
79 production's is not, because reading the whole forge from an app is a
80 documented feature (`docs/APPS.md`, `examples/forge-live`). Binding it too
81 waits for the owner's word: it needs a per-app grant the owner sees listed,
82 and until that grant is given it stops an app that reads its owner's other
83 repositories on purpose.
84 Enforced by: none yet
85 - Revoking every token of one account at once, and telling its owner a token was
86 used from somewhere new.
87 Enforced by: none yet
src/checks/resilience.ts +2 −6
@@ -3,18 +3,14 @@
33 * each line of docs/THREATS.md with its standing in the last full gate.
44 */
55
6 import { readFileSync } from "node:fs";
7 import { join } from "node:path";
8 import { parseThreats, standing, type Protection, type Standing } from "../core/threats.ts";
6 import { parseThreats, readThreats, standing, type Protection, type Standing } from "../core/threats.ts";
97 import { readGate } from "./gate_last.ts";
108
11 const DOC = join(import.meta.dir, "..", "..", "docs", "THREATS.md");
12
139 export type Row = { p: Protection; s: Standing };
1410
1511 function doc(): string {
1612 try {
17 return readFileSync(DOC, "utf8");
13 return readThreats();
1814 } catch {
1915 return "";
2016 }
src/core/threats.ts +50 −1
@@ -1,9 +1,58 @@
11 /**
22 * The protections in docs/THREATS.md, as plain data: each `Enforced by:` line
33 * (after a bullet or a paragraph) and each table row naming a call, with the
4 * enforcer cited, or none.
4 * enforcer cited, or none. docs/THREATS.md is an index: its preamble, then one
5 * link per section, each section a file in docs/threats/ (#15005), so two
6 * pulls about two adversaries touch two files. `readThreats` puts them back
7 * together as one document, in the index's order; everything else reads that.
58 */
69
10 import { readFileSync } from "node:fs";
11 import { join } from "node:path";
12
13 const DOCS = join(import.meta.dir, "..", "..", "docs");
14
15 /** One section's line in the index: `- [its heading](threats/its-file.md)`. */
16 export const SECTION_LINK = /^- \[(.+)\]\(threats\/([a-z0-9-]+\.md)\)$/;
17
18 export interface SectionLink {
19 readonly heading: string;
20 readonly file: string;
21 }
22
23 /** The sections the index links, in its order. */
24 export function sectionLinks(index: string): SectionLink[] {
25 const out: SectionLink[] = [];
26 for (const line of index.split("\n")) {
27 const m = SECTION_LINK.exec(line);
28 if (m !== null) out.push({ heading: m[1]!, file: m[2]! });
29 }
30 return out;
31 }
32
33 /**
34 * The whole document: the index up to its first section link, then each
35 * linked file in order, a blank line between. `read` gets a bare file name.
36 */
37 export function assembleThreats(index: string, read: (file: string) => string): string {
38 const first = index.split("\n").findIndex((l) => SECTION_LINK.test(l));
39 if (first < 0) return index;
40 const preamble = index.split("\n").slice(0, first).join("\n") + "\n";
41 return preamble + sectionLinks(index).map((s) => read(s.file).trimEnd() + "\n").join("\n");
42 }
43
44 /** docs/THREATS.md with its sections read back in; a file that cannot be read adds nothing. */
45 export function readThreats(docs = DOCS): string {
46 const index = readFileSync(join(docs, "THREATS.md"), "utf8");
47 return assembleThreats(index, (file) => {
48 try {
49 return readFileSync(join(docs, "threats", file), "utf8");
50 } catch {
51 return "";
52 }
53 });
54 }
55
756 export interface Protection {
857 readonly adversary: string;
958 readonly text: string;
src/view/docs.ts +4 −1
@@ -10,6 +10,7 @@
1010 import { parseSection, renderSpine } from "./design_spine.ts";
1111 import { parseFront, renderFeatureIndex, stripFront } from "./feature_index.ts";
1212 import { docsPages, renderDocsIndex } from "./docs_index.ts";
13 import { readThreats } from "../core/threats.ts";
1314 import { readdirSync, readFileSync } from "node:fs";
1415 import { join } from "node:path";
1516
@@ -52,9 +53,11 @@ export function docText(entry: DocEntry, ssh = false): string {
5253
5354 /**
5455 * A document as read: a note without its front matter, the features index built from the notes
55 * (#14248), the design file's list of sections from the section files (#14354).
56 * (#14248), the design file's list of sections from the section files (#14354), the threats
57 * index with its section files read back in (#15005).
5658 */
5759 function readDoc(name: string): string {
60 if (name === "THREATS.md") return stripFront(readThreats(DOCS));
5861 const text = readFileSync(join(DOCS, name), "utf8");
5962 if (name === "DESIGN.md") {
6063 const dir = join(DOCS, "design", "sections");
test/checks-resilience.test.ts +2 −2
@@ -5,14 +5,14 @@
55 * never dropped.
66 */
77 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { readFileSync } from "node:fs";
98 import { mkdtemp, rm } from "node:fs/promises";
109 import { tmpdir } from "node:os";
1110 import { join } from "node:path";
1211 import { keepGate } from "../src/checks/gate_last.ts";
1312 import { readResilience, type Row } from "../src/checks/resilience.ts";
13 import { readThreats } from "../src/core/threats.ts";
1414
15 const DOC = readFileSync(join(import.meta.dir, "..", "docs", "THREATS.md"), "utf8");
15 const DOC = readThreats();
1616 const UNKNOWN = new Set(["untested", "no test yet"]);
1717
1818 // Counted from the document without its parser: one protection per `Enforced by:`
test/resilience.test.ts +2 −2
@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
99 import { join } from "node:path";
1010 import { createApp, type App } from "../src/app.ts";
1111 import { fileResults, keepForgeGate, keepGate, readGate } from "../src/checks/gate_last.ts";
12 import { parseThreats, standing } from "../src/core/threats.ts";
12 import { parseThreats, readThreats, standing } from "../src/core/threats.ts";
1313 import { createUser, getUserByName } from "../src/core/users.ts";
1414 import type { Ctx, Screen } from "../src/tui/app/app.ts";
1515 import { forgeCommands, Session } from "../src/tui/forge.ts";
@@ -64,7 +64,7 @@ describe("resilience", () => {
6464 });
6565
6666 test("the real docs/THREATS.md yields one protection per Enforced by: line and per → row", async () => {
67 const md = await Bun.file(join(import.meta.dir, "..", "docs", "THREATS.md")).text();
67 const md = readThreats();
6868 const tests = md.split("\n").filter((l) => /^\s*Enforced by: /.test(l)).length;
6969 const rows = md.split("\n").filter((l) => l.startsWith("| ") && l.includes("→")).length;
7070 const got = parseThreats(md);
test/threats-enforced.test.ts +3 −3
@@ -5,12 +5,12 @@
55 * and only editing a row lowers it.
66 */
77 import { expect, test } from "bun:test";
8 import { existsSync, readFileSync } from "node:fs";
8 import { existsSync } from "node:fs";
99 import { join } from "node:path";
10 import { enforcement, parseThreats } from "../src/core/threats.ts";
10 import { enforcement, parseThreats, readThreats } from "../src/core/threats.ts";
1111
1212 const root = join(import.meta.dir, "..");
13 const doc = readFileSync(join(root, "docs/THREATS.md"), "utf8");
13 const doc = readThreats();
1414 const exists = (path: string): boolean => existsSync(join(root, path));
1515
1616 test("the doc covers each adversary, the internal calls and honeypots", () => {
test/threats-sections-linked.test.ts added +49
@@ -0,0 +1,49 @@
1 /**
2 * docs/THREATS.md is an index of its sections, each a file in docs/threats/ (#15005): every link
3 * names a file that is there and opens with the link's heading, every file there is linked once,
4 * and the assembled document keeps each `## ` heading in the index's order.
5 */
6 import { expect, test } from "bun:test";
7 import { readdirSync, readFileSync } from "node:fs";
8 import { join } from "node:path";
9 import { assembleThreats, readThreats, sectionLinks } from "../src/core/threats.ts";
10
11 const DOCS = join(import.meta.dir, "..", "docs");
12 const index = readFileSync(join(DOCS, "THREATS.md"), "utf8");
13 const links = sectionLinks(index);
14 const files = readdirSync(join(DOCS, "threats")).filter((n) => n.endsWith(".md")).sort();
15
16 test("every section the index links is a file that opens with that heading", () => {
17 expect(links.length).toBeGreaterThan(0);
18 const missing = links.filter((l) => !files.includes(l.file)).map((l) => l.file);
19 expect(missing).toEqual([]);
20 for (const l of links) {
21 const first = readFileSync(join(DOCS, "threats", l.file), "utf8").split("\n")[0];
22 expect(first, l.file).toBe(`## ${l.heading}`);
23 }
24 });
25
26 test("every file in docs/threats/ is linked from the index, once", () => {
27 const linked = links.map((l) => l.file);
28 expect(new Set(linked).size).toBe(linked.length);
29 expect(files.filter((f) => !linked.includes(f))).toEqual([]);
30 });
31
32 test("the index holds no section of its own; each section's file holds exactly one", () => {
33 expect(index.split("\n").filter((l) => l.startsWith("## "))).toEqual([]);
34 for (const f of files) {
35 const heads = readFileSync(join(DOCS, "threats", f), "utf8").split("\n").filter((l) => l.startsWith("## "));
36 expect(heads.length, f).toBe(1);
37 }
38 });
39
40 test("the assembled document has each heading once, in the index's order", () => {
41 const heads = readThreats().split("\n").filter((l) => l.startsWith("## ")).map((l) => l.slice(3));
42 expect(heads).toEqual(links.map((l) => l.heading));
43 });
44
45 test("assembly keeps the preamble and joins the linked files with one blank line", () => {
46 const idx = "# T\n\nWhy.\n\n- [A](threats/a.md)\n- [B](threats/b.md)\n";
47 const read = (f: string): string => ({ "a.md": "## A\n\n- one\n", "b.md": "## B\n\n- two\n\n" })[f] ?? "";
48 expect(assembleThreats(idx, read)).toBe("# T\n\nWhy.\n\n## A\n\n- one\n\n## B\n\n- two\n");
49 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs