cursedops 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # cursedops
 
-Three build-and-ops answers that two apps independently wrote the same way.
+Build-and-ops answers that the apps here wrote independently and identically.
 
 ```sh
 bun add cursedops
@@ -11,6 +11,7 @@ bun add cursedops
 | `cursedops/roots` | finding a generation's roots, and a checkout's package root, without knowing a path |
 | `cursedops/launchd` | installing, replacing and removing a macOS launchd user agent |
 | `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code |
+| `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
 name, a hostname, a port or a route.
@@ -114,6 +115,61 @@ No checks, ever. The checks are the part `desk` and `flix` wrote differently on
 and a shared kit that starts absorbing route lists and health-payload shapes is how the
 last one reached 277 files.
 
+## `cursedops/serve`
+
+```ts
+import { contentTypeFor, fileWithin, installCrashHandlers, isHashedAsset } from "cursedops/serve";
+
+installCrashHandlers("myapp");                        // one log line, then exit 1
+const file = fileWithin(clientDir, url.pathname);     // null unless it is really inside
+if (!file) return c.notFound();
+return new Response(Bun.file(file), {
+  headers: {
+    "content-type": contentTypeFor(file),
+    "cache-control": isHashedAsset(url.pathname) ? ONE_YEAR : "no-cache",
+  },
+});
+```
+
+🔴 `fileWithin` is the reason this subpath exists rather than the convenience of the
+other three. It is the check that stops `%2e%2e%2f` reaching the filesystem, and on
+2026-09-17 there were **eight** of it — one per app, character-identical, with nothing in
+the generation counting them. Eight copies of a security guarantee are eight guarantees:
+a fix in one is a fix in one.
+
+### The verdict for every symbol in the `serve.ts` family
+
+Measured 2026-09-17 across `collections`, `family`, `flix`, `music`, `patterns`, `roms`,
+`station` and `vault` — the eight apps that have a `src/server/serve.ts`. The files are
+247–387 lines and all eight differ, which is why no `diff` ever flagged them; the bodies
+below were compared with whitespace and comments normalised away.
+
+| symbol | identical in | verdict |
+|---|---:|---|
+| `fileWithin` | 8 of 8 | **moved.** The traversal guard. Entry rule 3 — a trap somebody paid for — in its purest form |
+| `installCrashHandlers` | 8 of 8 | **moved.** The app's name is a parameter; it is the only app-shaped thing the four touch |
+| `contentTypeFor` | 8 of 8 | **moved.** Extension → MIME, plus its private `CONTENT_TYPES` table, which was also 8 of 8 |
+| `isHashedAsset` | 8 of 8 | **moved.** Vite's own output convention, which is the bundler's identity and not the app's |
+| `clientDirOf` | 6 of 6 that have it | **stays.** One line, and six apps pin it with their own `clientDir.test.ts` against their own `vite.config.ts`. WHERE an app's build writes is app identity — entry rule 2 — and it is the line that once served `public/` and took a live app down |
+| `createServer` / `createApp` | 0 — all eight differ | **stays.** Route tables, health payloads, gates and body limits. This is the 277-file mistake's front door |
+| `parseRange` / `fileResponse` | `flix` and `station` only | **stays for now.** Two apps, so rule 1 is satisfiable, but rule 3 is not: nothing has been paid for yet, and a `Range` implementation shared by two apps that stream different things is a guess. The trigger to revisit is a THIRD app that needs byte ranges |
+| `API_PREFIX`, `isApiPath`, `canonicalApiPath`, `canonicalApiRequest`, `apiNotFoundBody` | `station` only | **stays.** One app, and rule 4 says an addition one app will use does not go in. `apiNotFoundBody` also writes a sentence the owner reads on a page — identity, not mechanism |
+
+🔴 **The task that ordered this move recorded `contentTypeFor` and `isHashedAsset` as
+7 of 8, with `station` differing. They did not differ.** All four bodies were identical
+in all eight apps when the move was made, so nothing had to converge and no app's
+behaviour changed on adoption. The count came from a census of the whole `serve.ts`
+family rather than of these two bodies; `bun tools/check-copies.ts` in the generation
+repo is the live answer either way.
+
+One behaviour is NOT a byte-for-byte carry, and `src/serve.ts`'s header argues it in
+full: the eight copies checked containment lexically and were therefore blind to a
+symlink under the root pointing out of it. `fileWithin` here resolves the real path of
+**both** sides after the lexical check, which refuses the escape while leaving every
+input the eight copies refused refused, at the same cost. A symlinked ancestor of the
+root cancels out — which is the failure a one-sided `realpath` would have shipped to
+every app on this machine, and is its own test.
+
 ## Verifying
 
 ```sh

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"version": "0.1.0",
-	"description": "The three build-and-ops answers two apps independently wrote the same way: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, and the scaffolding of a deployed smoke. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
+	"version": "0.2.0",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -24,6 +24,12 @@
 			"source": "./src/launchd.ts",
 			"import": "./src/launchd.ts"
 		},
+		"./serve": {
+			"types": "./src/serve.ts",
+			"bun": "./src/serve.ts",
+			"source": "./src/serve.ts",
+			"import": "./src/serve.ts"
+		},
 		"./smoke": {
 			"types": "./src/smoke.ts",
 			"bun": "./src/smoke.ts",

package/src/serve.ts

@@ -0,0 +1,153 @@
+/**
+ * The four helpers every app's `src/server/serve.ts` wrote the same way — the
+ * path-traversal guard among them.
+ *
+ * ## Why this is a library and not eight copies
+ *
+ * Measured 2026-09-17 by the apps maintenance sweep, and again by this move before
+ * it started: `collections`, `family`, `flix`, `music`, `patterns`, `roms`,
+ * `station` and `vault` each have a `src/server/serve.ts`. The FILES differ — 247
+ * to 387 lines, eight distinct versions, which is why no `diff` ever flagged them —
+ * but these four bodies are character-identical in **eight of eight**, with the
+ * whitespace and comments normalised away.
+ *
+ * 🔴 **`fileWithin` is why this was urgent rather than tidy.** It is the check that
+ * stops `%2e%2e%2f` reaching the filesystem. Eight copies of a security guarantee
+ * are eight guarantees: a fix in one is a fix in one, and the other seven apps keep
+ * the hole. That is the arithmetic the entry rule in `../README.md` asks for —
+ * rule 1 (two apps wrote it independently) answered eight times over, rule 2
+ * (mechanism, not identity — nothing here knows an app's name, port, hostname or
+ * routes; `installCrashHandlers` is HANDED the name), and rule 3 (a trap somebody
+ * paid for — a traversal guard is the definition of one).
+ *
+ * `clientDirOf` deliberately did NOT come with them. It is one line, six apps pin
+ * it with their own `clientDir.test.ts` against their own `vite.config.ts`, and
+ * where an app's build writes is app identity.
+ *
+ * `tools/check-copies.baseline` in the generation repo carried these four at
+ * `8  <symbol> src/server/serve.ts` and is the census that will notice if a copy
+ * comes back.
+ *
+ * ## 🔴 The one behaviour that is NOT a byte-for-byte carry
+ *
+ * The eight copies resolved containment LEXICALLY — `resolve(join(root, …))` and a
+ * `startsWith` — which is correct for `..` and for `%2e%2e%2f`, and blind to a
+ * symlink inside the root that points out of it. {@link fileWithin} now resolves
+ * the real path of both sides before comparing, so a symlink cannot walk out
+ * either. It is a strict tightening, not a change of contract:
+ *
+ *   - the lexical check runs FIRST and unchanged, so every input the eight copies
+ *     refused is still refused, at the same cost;
+ *   - a symlinked ANCESTOR of the root cancels out, because the root is resolved
+ *     the same way — the failure mode a naive `realpath` on one side only would
+ *     have introduced, and the reason this is not one line;
+ *   - every caller today passes a Vite `dist/`, and all eight were checked for
+ *     symlinks on 2026-09-17: there are none. So no app's behaviour moves, and the
+ *     day one of them serves a directory it did not build, the guard already holds.
+ *
+ * `serve.test.ts` drives both halves, including the symlink escape, because a guard
+ * that has only ever been seen passing is a guard nobody has proved can fail.
+ */
+
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, normalize, resolve, sep } from "node:path";
+
+/**
+ * Extension → content type, for what a built single-page client actually contains.
+ *
+ * Not a full MIME database on purpose: an app serving a type that is not here is an
+ * app serving something its build did not produce, and `application/octet-stream`
+ * is the honest answer to that rather than a guess.
+ */
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+	html: "text/html; charset=utf-8",
+	js: "text/javascript; charset=utf-8",
+	mjs: "text/javascript; charset=utf-8",
+	css: "text/css; charset=utf-8",
+	json: "application/json; charset=utf-8",
+	svg: "image/svg+xml",
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	avif: "image/avif",
+	ico: "image/x-icon",
+	woff: "font/woff",
+	woff2: "font/woff2",
+	txt: "text/plain; charset=utf-8",
+	map: "application/json; charset=utf-8",
+};
+
+/** The `content-type` for a path, by extension — `application/octet-stream` if unknown. */
+export const contentTypeFor = (path: string): string =>
+	CONTENT_TYPES[path.slice(path.lastIndexOf(".") + 1).toLowerCase()] ?? "application/octet-stream";
+
+/**
+ * Vite's own output convention: `name-<8+ hex/base64url chars>.ext` under
+ * `/assets/`. Only these get the immutable year.
+ */
+export const isHashedAsset = (urlPath: string): boolean =>
+	/^\/assets\/[^/]+-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/.test(urlPath);
+
+/**
+ * The file `urlPath` names inside `root`, or `null`.
+ *
+ * 🔴 The containment check is the point. `decodeURIComponent` then `normalize`
+ * collapses `..`, and the result must still start with the root — otherwise
+ * `/assets/..%2f..%2f..%2fetc%2fpasswd` reads whatever the process can. A
+ * directory, a missing file and a malformed escape are all `null`; a caller that
+ * gets a string has a regular file it may open.
+ *
+ * The final `realpath` pass is the one thing the eight app copies did not do — see
+ * the module header for why it cannot break a caller.
+ */
+export function fileWithin(root: string, urlPath: string): string | null {
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(urlPath);
+	} catch {
+		return null; // a malformed escape is not a path
+	}
+	if (decoded.includes("\0")) return null;
+	const full = resolve(join(root, normalize(decoded)));
+	const base = resolve(root);
+	if (full !== base && !full.startsWith(base + sep)) return null;
+	if (!existsSync(full) || !statSync(full).isFile()) return null;
+	// Lexically inside, and the file is there. Now the same question of the DISK: a
+	// symlink under the root is the one way a path can pass the check above and
+	// still read something outside. Both sides, or a symlinked ancestor of the root
+	// would refuse every file it holds.
+	let realFull: string;
+	let realBase: string;
+	try {
+		realFull = realpathSync(full);
+		realBase = realpathSync(base);
+	} catch {
+		return null; // it existed a line ago; whatever it is now, do not serve it
+	}
+	if (realFull !== realBase && !realFull.startsWith(realBase + sep)) return null;
+	return full;
+}
+
+/**
+ * Say what killed the process, once, before it goes.
+ *
+ * The whole value is the log line. An app holding SQLite handles that Bun closes on
+ * exit and nothing else in flight has nothing to drain — what was missing in the
+ * previous generation was not cleanup, it was ever finding out why a long-running
+ * process had stopped.
+ *
+ * 🔴 `name` is a parameter rather than anything this library could look up. That is
+ * the whole of rule 2: the only app-shaped thing these four helpers touch arrives
+ * as an argument.
+ */
+export function installCrashHandlers(name: string): void {
+	process.on("uncaughtException", (error) => {
+		console.error(`[${name}] uncaught exception — exiting`, error);
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		console.error(`[${name}] unhandled rejection — exiting`, reason);
+		process.exit(1);
+	});
+}