Public: anyone can read this; the crew can change it.
Every file the /security page cites as the enforcer exists, and a test fails when one is renamed away #13895
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13887-every-file-the-security-page-cites-as-th → main 2 commits fork
2 files
changed +113
−3
src/view/security.ts +17 −3
| @@ -1,8 +1,9 @@ | ||
| 1 | 1 | /** |
| 2 | 2 | * What /security says (#13208), as plain data the page and the terminal screen |
| 3 | * both draw: each claim names the file that enforces it and the test that | |
| 4 | * proves it, and test/security-page.test.ts checks both still stand, so a claim | |
| 5 | * cannot outlive its behaviour. | |
| 3 | * both draw: each claim names the file that enforces it, one symbol that file | |
| 4 | * must still export, and the test that proves it; test/security-citations.test.ts | |
| 5 | * fails naming the row when any of them is gone, so a claim cannot outlive its | |
| 6 | * behaviour or point at a file renamed away. | |
| 6 | 7 | */ |
| 7 | 8 | |
| 8 | 9 | import { REFUSED_PREFIX } from "../apps/egress.ts"; |
| @@ -15,6 +16,8 @@ export interface Claim { | ||
| 15 | 16 | words: string; |
| 16 | 17 | /** The file that enforces it, from the repository root. */ |
| 17 | 18 | source: string; |
| 19 | /** A function, const or class `source` must still export: the enforcer by name. */ | |
| 20 | symbol: string; | |
| 18 | 21 | /** Text that file must still contain for the sentence to stay true. */ |
| 19 | 22 | needle: string; |
| 20 | 23 | /** The test that proves the behaviour. */ |
| @@ -26,6 +29,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 26 | 29 | what: "Outside hosts", |
| 27 | 30 | words: `An app reaches only the hosts its forge.json egress names; any other is refused with a 403 that says "${REFUSED_PREFIX} <host> is not in this app's forge.json egress".`, |
| 28 | 31 | source: "src/apps/egress.ts", |
| 32 | symbol: "refusedWords", | |
| 29 | 33 | needle: "is not in this app's forge.json egress", |
| 30 | 34 | proof: "test/egress-refused.test.ts", |
| 31 | 35 | }, |
| @@ -34,6 +38,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 34 | 38 | words: |
| 35 | 39 | "An app, its preview, its terminal and every install and test step run in a cell of their own: the machine is read-only to them, they see no other process, and the forge's proxy is their only way out.", |
| 36 | 40 | source: "src/apps/contain.ts", |
| 41 | symbol: "openCell", | |
| 37 | 42 | needle: "bubblewrap", |
| 38 | 43 | proof: "test/contain.test.ts", |
| 39 | 44 | }, |
| @@ -42,6 +47,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 42 | 47 | words: |
| 43 | 48 | "An agent's shell reaches the forge, the package registry and its own app, writes only in its own clone, and cannot read the forge's data, keys or other agents' work.", |
| 44 | 49 | source: "src/crew/sandbox.ts", |
| 50 | symbol: "sandboxPolicy", | |
| 45 | 51 | needle: "export function sandboxPolicy", |
| 46 | 52 | proof: "test/crew-sandbox.test.ts", |
| 47 | 53 | }, |
| @@ -50,6 +56,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 50 | 56 | words: |
| 51 | 57 | "Where a machine cannot hold a cell or a sandbox, the forge still runs and says so to its admin at the foot of every page.", |
| 52 | 58 | source: "src/kernel/protection.ts", |
| 59 | symbol: "protectionNotice", | |
| 53 | 60 | needle: "export function protectionNotice", |
| 54 | 61 | proof: "test/protection.test.ts", |
| 55 | 62 | }, |
| @@ -58,6 +65,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 58 | 65 | words: |
| 59 | 66 | "It lives in a cookie scripts cannot read (HttpOnly), other sites cannot send (SameSite=Lax), and that travels only over https when the forge is served over https (Secure).", |
| 60 | 67 | source: "src/auth/cookies.ts", |
| 68 | symbol: "setCookie", | |
| 61 | 69 | needle: '"HttpOnly", "SameSite=Lax"', |
| 62 | 70 | proof: "test/cookie-flags.test.ts", |
| 63 | 71 | }, |
| @@ -66,6 +74,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 66 | 74 | words: |
| 67 | 75 | "A POST, PUT, PATCH or DELETE your browser sends from another site with your sign-in is refused before any code acts on it.", |
| 68 | 76 | source: "src/http/origin_gate.ts", |
| 77 | symbol: "originGate", | |
| 69 | 78 | needle: 'new Set(["POST", "PUT", "PATCH", "DELETE"])', |
| 70 | 79 | proof: "test/origin-every-mutation.test.ts", |
| 71 | 80 | }, |
| @@ -74,6 +83,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 74 | 83 | words: |
| 75 | 84 | "A token, key or secret the forge handed a run (its token, an app's secrets, a model or OAuth credential) is masked in its log and its check's log before the line is stored. A read masks again: while the run is live, every value it was handed; once it ends, only credential shapes (forge_, gh*_, Bearer…), so an app secret stored unmasked by an older forge is not caught then.", |
| 76 | 85 | source: "src/runs/log.ts", |
| 86 | symbol: "readRunLog", | |
| 77 | 87 | needle: "mask: (text: string) => string = redactHeld", |
| 78 | 88 | proof: "test/run-log-mask.test.ts", |
| 79 | 89 | }, |
| @@ -82,6 +92,7 @@ export const CLAIMS: readonly Claim[] = [ | ||
| 82 | 92 | words: |
| 83 | 93 | "It tells your browser not to guess its type (nosniff) and not to send the address you were on to another site (Referrer-Policy: same-origin).", |
| 84 | 94 | source: "src/http/respond.ts", |
| 95 | symbol: "securityFloor", | |
| 85 | 96 | needle: "export function securityFloor", |
| 86 | 97 | proof: "test/security-floor-every-route.test.ts", |
| 87 | 98 | }, |
| @@ -94,6 +105,7 @@ export const REPORT_CLAIMS: readonly Claim[] = [ | ||
| 94 | 105 | words: |
| 95 | 106 | 'In a repository here, open an issue and tick "Sealed security report": only people who can write there and its crew see it, until one of them unseals it.', |
| 96 | 107 | source: "src/core/sealed.ts", |
| 108 | symbol: "canSeeSealed", | |
| 97 | 109 | needle: "export function canSeeSealed", |
| 98 | 110 | proof: "test/sealed-issues.test.ts", |
| 99 | 111 | }, |
| @@ -101,6 +113,7 @@ export const REPORT_CLAIMS: readonly Claim[] = [ | ||
| 101 | 113 | what: "A repository", |
| 102 | 114 | words: "Any public repository takes a report at /<owner>/<name>/report, with no account.", |
| 103 | 115 | source: "src/http/server.ts", |
| 116 | symbol: "buildRouter", | |
| 104 | 117 | needle: 'router.add("GET", "/:owner/:name/report", reportPage)', |
| 105 | 118 | proof: "test/reports.test.ts", |
| 106 | 119 | }, |
| @@ -108,6 +121,7 @@ export const REPORT_CLAIMS: readonly Claim[] = [ | ||
| 108 | 121 | what: "An app", |
| 109 | 122 | words: "Every public app takes one at /__forge/report on its own address, even while the app is down.", |
| 110 | 123 | source: "src/apps/proxy.ts", |
| 124 | symbol: "proxyApp", | |
| 111 | 125 | needle: 'url.pathname === "/__forge/report"', |
| 112 | 126 | proof: "test/apps-report.test.ts", |
| 113 | 127 | }, |
test/security-citations.test.ts added +96
| @@ -0,0 +1,96 @@ | ||
| 1 | /** | |
| 2 | * Every file /security and /settings/security/controls cite as the enforcer | |
| 3 | * still exists (#13887): a claim's `source` holds its exported `symbol` and its | |
| 4 | * `needle`, its `proof` is a file, and a control's `keptBy` path is a file. A | |
| 5 | * stale citation fails here with the row's name, not as a bare mismatch. | |
| 6 | */ | |
| 7 | import { expect, test } from "bun:test"; | |
| 8 | import { existsSync, readFileSync } from "node:fs"; | |
| 9 | import { join } from "node:path"; | |
| 10 | import { CONTROLS, type Control } from "../src/checks/controls.ts"; | |
| 11 | import { CLAIMS, REPORT_CLAIMS, type Claim } from "../src/view/security.ts"; | |
| 12 | ||
| 13 | const root = join(import.meta.dir, ".."); | |
| 14 | const REPO_PATH = /^(src|test|scripts|docs)\/[\w./-]+$/; | |
| 15 | ||
| 16 | const read = (path: string): string | undefined => { | |
| 17 | const full = join(root, path); | |
| 18 | return existsSync(full) ? readFileSync(full, "utf8") : undefined; | |
| 19 | }; | |
| 20 | ||
| 21 | /** Whether `text` declares `name` as an exported runtime value (function, const, let or class). */ | |
| 22 | function exports(text: string, name: string): boolean { | |
| 23 | const decl = new RegExp(`^export\\s+(?:async\\s+)?(?:function\\*?|const|let|class)\\s+${name}\\b`, "m"); | |
| 24 | return decl.test(text); | |
| 25 | } | |
| 26 | ||
| 27 | /** What is wrong with one claim's citation, each line naming the row; empty when it stands. */ | |
| 28 | function claimProblems(c: Claim, load = read): string[] { | |
| 29 | const out: string[] = []; | |
| 30 | const row = `"${c.what}"`; | |
| 31 | const text = REPO_PATH.test(c.source) ? load(c.source) : undefined; | |
| 32 | if (text === undefined) out.push(`${row}: ${c.source} is missing`); | |
| 33 | else { | |
| 34 | if (!exports(text, c.symbol)) out.push(`${row}: ${c.source} no longer exports ${c.symbol}`); | |
| 35 | if (!text.includes(c.needle)) out.push(`${row}: ${c.source} no longer says ${JSON.stringify(c.needle)}`); | |
| 36 | } | |
| 37 | if (!REPO_PATH.test(c.proof) || load(c.proof) === undefined) out.push(`${row}: proof ${c.proof} is missing`); | |
| 38 | return out; | |
| 39 | } | |
| 40 | ||
| 41 | /** A tested control's `keptBy` is a file here; an untested one may name a place outside. */ | |
| 42 | function controlProblems(c: Control, load = read): string[] { | |
| 43 | const row = `"${c.name}"`; | |
| 44 | if (REPO_PATH.test(c.keptBy)) return load(c.keptBy) === undefined ? [`${row}: ${c.keptBy} is missing`] : []; | |
| 45 | return c.tested ? [`${row}: tested, but kept by ${JSON.stringify(c.keptBy)}, not a file here`] : []; | |
| 46 | } | |
| 47 | ||
| 48 | test("every claim on /security cites a file that exists, still exports its symbol and says its needle", () => { | |
| 49 | expect([...CLAIMS, ...REPORT_CLAIMS].flatMap((c) => claimProblems(c))).toEqual([]); | |
| 50 | }); | |
| 51 | ||
| 52 | test("every control on /settings/security/controls is kept by a file that exists", () => { | |
| 53 | expect(CONTROLS.flatMap((c) => controlProblems(c))).toEqual([]); | |
| 54 | }); | |
| 55 | ||
| 56 | test("a claim renamed away fails naming its row: missing path, lost symbol, lost needle, missing proof", () => { | |
| 57 | const claim: Claim = { | |
| 58 | what: "Example", | |
| 59 | words: "", | |
| 60 | source: "src/x.ts", | |
| 61 | symbol: "guard", | |
| 62 | needle: "holds", | |
| 63 | proof: "test/x.test.ts", | |
| 64 | }; | |
| 65 | const files = (m: Record<string, string>) => (p: string) => m[p]; | |
| 66 | expect(claimProblems(claim, files({ "test/x.test.ts": "" }))).toEqual(['"Example": src/x.ts is missing']); | |
| 67 | expect(claimProblems(claim, files({ "src/x.ts": "function guard() {} // holds", "test/x.test.ts": "" }))).toEqual([ | |
| 68 | '"Example": src/x.ts no longer exports guard', | |
| 69 | ]); | |
| 70 | expect(claimProblems(claim, files({ "src/x.ts": "export function guard() {}", "test/x.test.ts": "" }))).toEqual([ | |
| 71 | '"Example": src/x.ts no longer says "holds"', | |
| 72 | ]); | |
| 73 | expect(claimProblems(claim, files({ "src/x.ts": "export const guard = 1; // holds" }))).toEqual([ | |
| 74 | '"Example": proof test/x.test.ts is missing', | |
| 75 | ]); | |
| 76 | expect(claimProblems({ ...claim, source: "../etc/passwd" }, files({ "test/x.test.ts": "" }))).toEqual([ | |
| 77 | '"Example": ../etc/passwd is missing', | |
| 78 | ]); | |
| 79 | }); | |
| 80 | ||
| 81 | test("a symbol counts only as its own exported declaration, not a longer name or a mention", () => { | |
| 82 | expect(exports("export async function guard(", "guard")).toBe(true); | |
| 83 | expect(exports("export class guard {}", "guard")).toBe(true); | |
| 84 | expect(exports("export function guardAll(", "guard")).toBe(false); | |
| 85 | expect(exports("// export function guard(", "guard")).toBe(false); | |
| 86 | expect(exports("import { guard } from './x.ts';", "guard")).toBe(false); | |
| 87 | }); | |
| 88 | ||
| 89 | test("a control renamed away fails naming its row; an untested one may live outside the repository", () => { | |
| 90 | const control: Control = { id: "x", name: "Example", holds: "", keptBy: "test/x.test.ts", tested: true }; | |
| 91 | expect(controlProblems(control, () => undefined)).toEqual(['"Example": test/x.test.ts is missing']); | |
| 92 | expect(controlProblems({ ...control, keptBy: "somewhere" }, () => undefined)).toEqual([ | |
| 93 | '"Example": tested, but kept by "somewhere", not a file here', | |
| 94 | ]); | |
| 95 | expect(controlProblems({ ...control, keptBy: "somewhere", tested: false }, () => undefined)).toEqual([]); | |
| 96 | }); |
new above
offline