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

A literal host in src/ that forge.json egress does not declare fails the test, naming the file #15176

Merged opened this

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

Merged

torque/forge:torque/15156-a-literal-host-in-src-that-forge-json-eg → main 2 commits fork

  • Merged. torque/15156-a-literal-host-in-src-that-forge-json-eg was merged into main as 2541ab6.

Review

Sign in to review this change.
2 files changed +141 −1
forge.json +13 −1
@@ -1,7 +1,19 @@
11 {
22 "egress": [
33 "api.anthropic.com",
4 "api.github.com"
4 "api.github.com",
5 "github.com",
6 "api.stripe.com",
7 "challenges.cloudflare.com",
8 "api.cloudflare.com",
9 "api.digitalocean.com",
10 "api.fly.io",
11 "api.backblazeb2.com",
12 "api.vercel.com",
13 "login.microsoftonline.com",
14 "management.azure.com",
15 "api.typesafe.ai",
16 "graph.instagram.com"
517 ],
618 "app": {
719 "looks": ["/", "/docs", "/explore", "/board", "/notes", "/review", "/releases", "/apps", "/security", "/system", "/admin/limits", "/maintenance", "/talk", "/flow", "/resilience", "/boards?help", "/settings/crew", "/settings/crew?help", "/settings/security/controls", "/settings/grants", "/preview-admin/sample", "/preview-admin/sample/drop", "/preview-admin/sample/data-move", "/preview-admin/sample/cut-over", "/preview-admin/sample/pulls/3", "/preview-admin/sample/next?pick", "/preview-admin/sample/bets", "/preview-admin/sample/waves", "/preview-admin/sample/space", "/looks/missing", "/looks/failed", "/nope/nothing"],
test/egress-literals.test.ts added +128
@@ -0,0 +1,128 @@
1 /**
2 * Every https host the forge's code names in a string is declared in
3 * `forge.json` `egress` (#15156), so the build fails before the gate refuses
4 * the call at run time ("refused by this forge: <host> is not in this app's
5 * forge.json egress"). Comments are stripped first (Bun's transpiler), so a
6 * host a doc comment mentions never counts; a host that appears in code but is
7 * never dialled by the server (a link, a placeholder, a URI used as a name) is
8 * listed below with its reason. A failure names the host and the file.
9 */
10
11 import { describe, expect, test } from "bun:test";
12 import { Glob } from "bun";
13 import { STEP_HOSTS } from "../src/apps/contain.ts";
14
15 /**
16 * Host after `https://` or `wss://`: a dotted name, stopping before a port, path or interpolation.
17 */
18 const URL_HOST = /\b(?:https|wss):\/\/([a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+)/gi;
19
20 /** Names reserved for examples and never resolved (RFC 2606, RFC 6761). */
21 const RESERVED = /(^|\.)(example|invalid|test|localhost)$|(^|\.)example\.(com|net|org)$/;
22
23 const LINK = "a link or text rendered for a person; the server never fetches it";
24
25 /** Hosts named in code that the server never dials, with why. */
26 const NOT_CALLED: Record<string, string> = {
27 "billing.stripe.com": "placeholder in the billing form's portal address hint",
28 "dashboard.stripe.com": LINK,
29 "bun.sh": "inside a droplet's cloud-init script: the droplet fetches it, not the forge",
30 "codeberg.org": "placeholder and example text on the bring pages",
31 "forge.open-platform.sh": "the upstream repository's link (core/upstream.ts) and a link-relation URI (apps/proxy.ts)",
32 "git.open-platform.sh": "placeholder in the follow-upstream form",
33 "jsonfeed.org": "the JSON Feed version URI, a name and not a request",
34 "ntfy.sh": "placeholder in the account notification field",
35 "openrouter.ai": "example text for the model endpoint field; the endpoint itself is the admin's configuration",
36 "schema.org": "the JSON-LD @context, a name and not a request",
37 "specification.website": "section links in release and preview reports",
38 "www.espodev.com": LINK,
39 "www.open-platform.sh": LINK,
40 "www.rfc-editor.org": LINK,
41 "your.forge": "placeholder for the person's own forge address",
42 };
43
44 const transpiler = new Bun.Transpiler({ loader: "ts" });
45
46 /** Hosts in a file's code strings, its comments removed. */
47 function codeHosts(text: string): Set<string> {
48 const hosts = new Set<string>();
49 for (const m of transpiler.transformSync(text).matchAll(URL_HOST)) {
50 const host = (m[1] ?? "").toLowerCase();
51 if (!RESERVED.test(host)) hosts.add(host);
52 }
53 return hosts;
54 }
55
56 /** Whether an egress list (exact names, `*.name`, optional `:port`) opens a host. */
57 function declares(egress: readonly string[], host: string): boolean {
58 return egress.some((entry) => {
59 const name = (entry.toLowerCase().split(":")[0] ?? "");
60 return name.startsWith("*.") ? host.endsWith(name.slice(1)) : name === host;
61 });
62 }
63
64 /** `host in file:line` for every host in code that is neither declared nor listed. */
65 function undeclared(files: ReadonlyMap<string, string>, egress: readonly string[]): string[] {
66 const out: string[] = [];
67 for (const [file, text] of files)
68 for (const host of codeHosts(text)) {
69 if (declares(egress, host) || NOT_CALLED[host] !== undefined) continue;
70 const lines = text.split("\n");
71 const at = lines.findIndex((l) => l.toLowerCase().includes(`//${host}`) && !/^\s*(\*|\/\/|\/\*)/.test(l));
72 out.push(`${host} in ${file}${at < 0 ? "" : `:${at + 1}`} is not in forge.json egress`);
73 }
74 return out.sort();
75 }
76
77 let read: Promise<Map<string, string>> | undefined;
78
79 /** Every file under src, read once for the suite. */
80 function sources(): Promise<Map<string, string>> {
81 read ??= (async () => {
82 const files = new Map<string, string>();
83 for (const file of new Glob("src/**/*.ts").scanSync(".")) files.set(file, await Bun.file(file).text());
84 return files;
85 })();
86 return read;
87 }
88
89 async function egress(): Promise<string[]> {
90 const manifest = (await Bun.file("forge.json").json()) as { egress?: string[] };
91 return [...STEP_HOSTS, ...(manifest.egress ?? [])];
92 }
93
94 describe("literal hosts in src against forge.json egress", () => {
95 test("every https host in code strings is declared, or listed in NOT_CALLED", async () => {
96 expect(undeclared(await sources(), await egress())).toEqual([]);
97 });
98
99 test("each never-called host still appears in code, is not also declared, and says why", async () => {
100 const seen = new Set<string>();
101 for (const text of (await sources()).values()) for (const h of codeHosts(text)) seen.add(h);
102 const declared = await egress();
103 for (const [host, why] of Object.entries(NOT_CALLED)) {
104 expect([host, seen.has(host)]).toEqual([host, true]);
105 expect([host, declares(declared, host)]).toEqual([host, false]);
106 expect([host, why.length > 10]).toEqual([host, true]);
107 }
108 });
109
110 test("a host only in a comment does not count; one in a string does, named with its file and line", () => {
111 const files = new Map([
112 [
113 "src/sample.ts",
114 [
115 "/** Calls https://docs.only.dev for nothing. */",
116 "// https://also.comment.dev",
117 'const API = "https://api.undeclared.dev/v1";',
118 "await fetch(`https://ok.declared.dev/${p}`);",
119 'const e = "https://kid.example/x";',
120 ].join("\n"),
121 ],
122 ]);
123 expect(undeclared(files, ["ok.declared.dev"])).toEqual([
124 "api.undeclared.dev in src/sample.ts:3 is not in forge.json egress",
125 ]);
126 expect(undeclared(files, ["*.undeclared.dev", "ok.declared.dev:443"])).toEqual([]);
127 });
128 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs