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

Merged opened this

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

Merged

mason/forge:mason/13887-every-file-the-security-page-cites-as-th → main 2 commits fork

  • Merged. mason/13887-every-file-the-security-page-cites-as-th was merged into main as 18fcdb9.

Review

Sign in to review this change.
2 files changed +113 −3
src/view/security.ts +17 −3
@@ -1,8 +1,9 @@
11 /**
22 * 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.
67 */
78
89 import { REFUSED_PREFIX } from "../apps/egress.ts";
@@ -15,6 +16,8 @@ export interface Claim {
1516 words: string;
1617 /** The file that enforces it, from the repository root. */
1718 source: string;
19 /** A function, const or class `source` must still export: the enforcer by name. */
20 symbol: string;
1821 /** Text that file must still contain for the sentence to stay true. */
1922 needle: string;
2023 /** The test that proves the behaviour. */
@@ -26,6 +29,7 @@ export const CLAIMS: readonly Claim[] = [
2629 what: "Outside hosts",
2730 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".`,
2831 source: "src/apps/egress.ts",
32 symbol: "refusedWords",
2933 needle: "is not in this app's forge.json egress",
3034 proof: "test/egress-refused.test.ts",
3135 },
@@ -34,6 +38,7 @@ export const CLAIMS: readonly Claim[] = [
3438 words:
3539 "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.",
3640 source: "src/apps/contain.ts",
41 symbol: "openCell",
3742 needle: "bubblewrap",
3843 proof: "test/contain.test.ts",
3944 },
@@ -42,6 +47,7 @@ export const CLAIMS: readonly Claim[] = [
4247 words:
4348 "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.",
4449 source: "src/crew/sandbox.ts",
50 symbol: "sandboxPolicy",
4551 needle: "export function sandboxPolicy",
4652 proof: "test/crew-sandbox.test.ts",
4753 },
@@ -50,6 +56,7 @@ export const CLAIMS: readonly Claim[] = [
5056 words:
5157 "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.",
5258 source: "src/kernel/protection.ts",
59 symbol: "protectionNotice",
5360 needle: "export function protectionNotice",
5461 proof: "test/protection.test.ts",
5562 },
@@ -58,6 +65,7 @@ export const CLAIMS: readonly Claim[] = [
5865 words:
5966 "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).",
6067 source: "src/auth/cookies.ts",
68 symbol: "setCookie",
6169 needle: '"HttpOnly", "SameSite=Lax"',
6270 proof: "test/cookie-flags.test.ts",
6371 },
@@ -66,6 +74,7 @@ export const CLAIMS: readonly Claim[] = [
6674 words:
6775 "A POST, PUT, PATCH or DELETE your browser sends from another site with your sign-in is refused before any code acts on it.",
6876 source: "src/http/origin_gate.ts",
77 symbol: "originGate",
6978 needle: 'new Set(["POST", "PUT", "PATCH", "DELETE"])',
7079 proof: "test/origin-every-mutation.test.ts",
7180 },
@@ -74,6 +83,7 @@ export const CLAIMS: readonly Claim[] = [
7483 words:
7584 "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.",
7685 source: "src/runs/log.ts",
86 symbol: "readRunLog",
7787 needle: "mask: (text: string) => string = redactHeld",
7888 proof: "test/run-log-mask.test.ts",
7989 },
@@ -82,6 +92,7 @@ export const CLAIMS: readonly Claim[] = [
8292 words:
8393 "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).",
8494 source: "src/http/respond.ts",
95 symbol: "securityFloor",
8596 needle: "export function securityFloor",
8697 proof: "test/security-floor-every-route.test.ts",
8798 },
@@ -94,6 +105,7 @@ export const REPORT_CLAIMS: readonly Claim[] = [
94105 words:
95106 '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.',
96107 source: "src/core/sealed.ts",
108 symbol: "canSeeSealed",
97109 needle: "export function canSeeSealed",
98110 proof: "test/sealed-issues.test.ts",
99111 },
@@ -101,6 +113,7 @@ export const REPORT_CLAIMS: readonly Claim[] = [
101113 what: "A repository",
102114 words: "Any public repository takes a report at /<owner>/<name>/report, with no account.",
103115 source: "src/http/server.ts",
116 symbol: "buildRouter",
104117 needle: 'router.add("GET", "/:owner/:name/report", reportPage)',
105118 proof: "test/reports.test.ts",
106119 },
@@ -108,6 +121,7 @@ export const REPORT_CLAIMS: readonly Claim[] = [
108121 what: "An app",
109122 words: "Every public app takes one at /__forge/report on its own address, even while the app is down.",
110123 source: "src/apps/proxy.ts",
124 symbol: "proxyApp",
111125 needle: 'url.pathname === "/__forge/report"',
112126 proof: "test/apps-report.test.ts",
113127 },
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs