cursedops 0.9.2 → 0.10.1

package/README.md

@@ -25,6 +25,8 @@ bun add cursedops
 | `cursedops/bound-lists` | the static check that no SQL builds an `IN (…)` list one `?` per value — the shape D1 500s on past 100 ids. Test-time only; the recorded third exception, see below |
 | `cursedops/staged-client` | the IMMUTABLE client a checkout-served app serves — a build staged into `<APP_DATA_DIR>/client/<commit>/` behind `CURRENT`, so another agent's `vite build` in the checkout never changes live bytes — and its `forge-client stamp` / `forge-client stage` bin (0.6.0, lifted from family, flix, roms, station) |
 | `cursedops/deploy-tree` | the two refusals a checkout-served deploy needs — never deploy a dirty tree, never `git revert` in one (`readTreeStatus`, `refuseToDeploy`, `refuseToRevert`; 0.6.0, lifted from nine apps) |
+| `cursedops/relay` | the WORKER half of a relay — a Worker in front of a Mac-bound app over ONE outbound WebSocket: the frames (station's wire, byte for byte), the key-digest door (`acceptLink`), and `RelayLink`, the Durable Object an app subclasses with its name, body ceiling, timeout and (optionally) station's per-cookie offline cache. No `node:` import (0.10.0, lifted from station for roms, task 065) |
+| `cursedops/relay-link` | the MAC half — `dialLink` (answer each frame with the app's own `fetch`, redial 1 s → 60 s on close, no timer otherwise), `readLinkSettings` for `<APP>_LINK_URL`/`<APP>_LINK_KEY`, and `rotateLinkKey` (digest to the Worker FIRST, the key to the 0600 file only if it took) (0.10.0) |
 | `cursedops/public-surface` | the ratchet on a LIBRARY's public surface — a symbol count per export subpath against a committed baseline that may only fall — and its `public-surface` bin. Not an app's: the one entry here admitted for three published libraries, see below |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"version": "0.9.2",
-	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots — and printing a command that runs when pasted — without knowing a path, the generation's whole-tree laws run over one repo from a checkout or a worktree, macOS launchd agent install/replace/remove and the live port a job serves, the scaffolding and verdicts of a deployed smoke (origin probe, the smoke's own environment, a network that lies about DNS, a settled version), the static-serving helpers eight apps copied — the path-traversal guard among them — the API floor that keeps an unmatched /api/... from ever being answered with the app shell, the commit and dirty flag a checkout-served process reports, the Cloudflare Worker deploy toolkit four apps copied (the deploy sequence, exact-set secrets over a pipe, origin-first rollback, the curl edge fetch, the row-for-row D1 import proof, the billed-CPU tail check around a deploy's walk and smoke, and each app's worker:secrets and worker:smoke main as one function of its data), the Worker import-graph and await-port checks every Worker app's suite runs over its own source, and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
+	"version": "0.10.1",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots — and printing a command that runs when pasted — without knowing a path, the generation's whole-tree laws run over one repo from a checkout or a worktree, macOS launchd agent install/replace/remove and the live port a job serves, the scaffolding and verdicts of a deployed smoke (origin probe, the smoke's own environment, a network that lies about DNS, a settled version), the static-serving helpers eight apps copied — the path-traversal guard among them — the API floor that keeps an unmatched /api/... from ever being answered with the app shell, the commit and dirty flag a checkout-served process reports, the Cloudflare Worker deploy toolkit four apps copied (the deploy sequence, exact-set secrets over a pipe, origin-first rollback, the curl edge fetch, the row-for-row D1 import proof, the billed-CPU tail check around a deploy's walk and smoke, and each app's worker:secrets and worker:smoke main as one function of its data), the relay a Worker fronts a Mac-bound app with (the Durable Object, the frames, the Mac's dialer and key rotation — lifted from station for roms), the Worker import-graph and await-port checks every Worker app's suite runs over its own source, and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -121,6 +121,18 @@
 			"bun": "./src/deployTree.ts",
 			"source": "./src/deployTree.ts",
 			"import": "./src/deployTree.ts"
+		},
+		"./relay": {
+			"types": "./src/relay.ts",
+			"bun": "./src/relay.ts",
+			"source": "./src/relay.ts",
+			"import": "./src/relay.ts"
+		},
+		"./relay-link": {
+			"types": "./src/relayLink.ts",
+			"bun": "./src/relayLink.ts",
+			"source": "./src/relayLink.ts",
+			"import": "./src/relayLink.ts"
 		}
 	},
 	"bin": {

package/src/relay.ts

@@ -0,0 +1,494 @@
+/**
+ * `cursedops/relay` — the WORKER half of a relay: a Cloudflare Worker in front, the app unchanged
+ * on the Mac behind ONE outbound WebSocket, `cursed.app.runtime: "relay"`. The Mac half (the dialer
+ * and the key rotation) is `cursedops/relay-link`.
+ *
+ * ```
+ *   browser ──HTTPS──▶ Worker ──(Durable Object RelayLink)──▶ the Mac's socket ──▶ app.fetch
+ *                                                        ◀── { t: "res", id, … } ◀──
+ * ```
+ *
+ * ## Why it is here, and who wrote it twice
+ *
+ * `apps/station` built it first (task 047, 2026-09-24 — its Worker, its frames and
+ * `apps/station/scripts/link.ts`) — station is the console of THIS Mac and cannot
+ * live in an isolate. `apps/roms` needed the identical shape the same day (task 065): its play-host
+ * agent drives play on this Mac, so a full D1 port would have rewritten 40 `bun:sqlite` files to
+ * move an app whose other half can never move. Lifted here ONCE rather than copied — the README's
+ * rule 1 is met by two apps needing the same wire, and a relay whose two copies drifted would put
+ * two frame formats on the fleet.
+ *
+ * 🔴 **The wire is station's, byte for byte**: JSON text frames, bodies base64, `set-cookie` lines
+ * kept separate. A Worker on this module and a Mac on station's old `link.ts` (or the reverse)
+ * still talk, which is what let station move onto this without a flag day.
+ *
+ * ## What it holds, and what it does not
+ *
+ * Mechanism only. The app's Worker decides WHICH paths relay (its routes are identity), holds the
+ * key digest as a secret, and subclasses {@link RelayLink} with its name and knobs. The gate stays
+ * the Mac's: this Worker holds no session and no D1, so it cannot drift from the app it fronts.
+ *
+ * Pure: no `node:` import and no Worker globals at module scope, because both ends import the
+ * frames — workerd for the object, Bun for the dialer.
+ */
+
+/** The largest request or response body a link carries unless the app says otherwise. */
+export const DEFAULT_MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+/** How long the Worker waits for the Mac to answer one request before it says so. */
+export const DEFAULT_RELAY_TIMEOUT_MS = 30_000;
+
+/** A request travelling DOWN the link. `path` includes the query string. */
+export interface RequestFrame {
+	t: "req";
+	id: string;
+	method: string;
+	path: string;
+	headers: [string, string][];
+	body: string | null;
+}
+
+/** The Mac's answer, travelling UP. Multiple `set-cookie` lines stay separate pairs. */
+export interface ResponseFrame {
+	t: "res";
+	id: string;
+	status: number;
+	headers: [string, string][];
+	body: string | null;
+}
+
+export type LinkFrame = RequestFrame | ResponseFrame;
+
+/**
+ * Sent UP by the Mac once, right after it connects (station, task 089): the GETs every page
+ * performs, so a {@link RelayLink} with an offline cache can refresh it while the Mac is awake.
+ * Only `/api/` GET paths survive the parse; at most 64.
+ */
+export interface WarmFrame {
+	t: "warm";
+	paths: string[];
+}
+
+/**
+ * Headers that must NOT cross: hop-by-hop ones, and the edge's own, which the Mac's request log
+ * must not mistake for its tunnel's. `cf-connecting-ip` and `cf-ipcountry` DO cross, so the Mac
+ * still places a request the way it always has (station, task 2156).
+ */
+const DROP = new Set(["connection", "keep-alive", "transfer-encoding", "upgrade", "host", "content-length", "cf-ray", "cf-visitor", "cf-worker"]);
+
+function portableHeaders(headers: Headers): [string, string][] {
+	const out: [string, string][] = [];
+	headers.forEach((value, name) => {
+		if (name === "set-cookie" || DROP.has(name)) return;
+		out.push([name, value]);
+	});
+	for (const cookie of headers.getSetCookie?.() ?? []) out.push(["set-cookie", cookie]);
+	return out;
+}
+
+export function toBase64(bytes: Uint8Array): string {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+	return btoa(binary);
+}
+
+function fromBase64(text: string): Uint8Array<ArrayBuffer> {
+	const binary = atob(text);
+	const out = new Uint8Array(new ArrayBuffer(binary.length));
+	for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+	return out;
+}
+
+/** A frame off the wire, or null for anything that is not one — never a throw into a handler. */
+export function parseFrame(text: string): LinkFrame | null {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (typeof value !== "object" || value === null) return null;
+	const f = value as Record<string, unknown>;
+	if (typeof f.id !== "string" || !Array.isArray(f.headers)) return null;
+	if (f.body !== null && typeof f.body !== "string") return null;
+	if (f.t === "req" && typeof f.method === "string" && typeof f.path === "string" && f.path.startsWith("/")) return f as unknown as RequestFrame;
+	if (f.t === "res" && typeof f.status === "number") return f as unknown as ResponseFrame;
+	return null;
+}
+
+export function parseWarmFrame(text: string): WarmFrame | null {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	const f = value as { t?: unknown; paths?: unknown } | null;
+	if (f?.t !== "warm" || !Array.isArray(f.paths)) return null;
+	return { t: "warm", paths: f.paths.filter((p): p is string => typeof p === "string" && p.startsWith("/api/")).slice(0, 64) };
+}
+
+export async function requestFrame(id: string, request: Request): Promise<RequestFrame> {
+	const url = new URL(request.url);
+	const bytes = request.method === "GET" || request.method === "HEAD" ? null : new Uint8Array(await request.arrayBuffer());
+	return {
+		t: "req",
+		id,
+		method: request.method,
+		path: `${url.pathname}${url.search}`,
+		headers: portableHeaders(request.headers),
+		body: bytes && bytes.length > 0 ? toBase64(bytes) : null,
+	};
+}
+
+/** The Request the Mac's app answers — on the Worker's own origin, so every URL it builds is right. */
+export function frameToRequest(frame: RequestFrame, origin: string): Request {
+	const headers = new Headers();
+	for (const [name, value] of frame.headers) headers.append(name, value);
+	return new Request(`${origin.replace(/\/+$/, "")}${frame.path}`, {
+		method: frame.method,
+		headers,
+		body: frame.body === null ? null : fromBase64(frame.body),
+		redirect: "manual",
+	});
+}
+
+export async function responseFrame(id: string, response: Response): Promise<ResponseFrame> {
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	return { t: "res", id, status: response.status, headers: portableHeaders(response.headers), body: bytes.length > 0 ? toBase64(bytes) : null };
+}
+
+export function frameToResponse(frame: ResponseFrame): Response {
+	const headers = new Headers();
+	for (const [name, value] of frame.headers) headers.append(name, value);
+	// A 1xx/204/304 may carry no body, and `new Response` throws if one is given.
+	const bodyless = frame.status === 204 || frame.status === 304 || frame.status < 200;
+	return new Response(bodyless || frame.body === null ? null : fromBase64(frame.body), { status: frame.status, headers });
+}
+
+export async function sha256Hex(text: string): Promise<string> {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Constant-time compare of two SHA-256 hex digests. Its own, not `cwip/constant-time`, because this
+ * package has ZERO runtime dependencies and a Worker bundle imports it; the length difference is
+ * folded into the accumulator, never an early return (the rule `check-own-compare` enforces).
+ */
+function digestsEqual(a: string, b: string): boolean { // check-own-compare:ignore zero-dependency library; compares two fixed-length SHA-256 digests, length folded in
+	let diff = a.length ^ b.length;
+	for (let i = 0; i < Math.max(a.length, b.length); i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+	return diff === 0;
+}
+
+/**
+ * Is `header` (`Bearer <key>`) the key whose SHA-256 the Worker holds? The Worker keeps only the
+ * digest as a secret, so the key itself exists on the Mac alone and a leaked secret opens nothing.
+ */
+export async function linkKeyMatches(header: string | null, expectedSha256: string | undefined): Promise<boolean> {
+	if (!expectedSha256 || !header?.startsWith("Bearer ")) return false;
+	const presented = header.slice("Bearer ".length).trim();
+	if (presented.length < 32) return false;
+	return digestsEqual(await sha256Hex(presented), expectedSha256.trim().toLowerCase());
+}
+
+/** One cookie's value off a `cookie` header, or null — exact name match, `=` in the value kept. */
+export function cookieValue(header: string | null, name: string): string | null {
+	for (const part of (header ?? "").split(";")) {
+		const [key, ...rest] = part.trim().split("=");
+		if (key === name && rest.length > 0) return rest.join("=") || null;
+	}
+	return null;
+}
+
+/** A server-side socket as the hibernation API hands it back. Structural — no Worker globals. */
+export interface LinkSocket {
+	send(data: string): void;
+	close(code?: number, reason?: string): void;
+	serializeAttachment(value: unknown): void;
+	deserializeAttachment(): unknown;
+}
+
+/** The slice of `DurableObjectStorage` the offline answers use. */
+export interface LinkStorage {
+	get<T>(key: string): Promise<T | undefined>;
+	put(key: string, value: unknown): Promise<void>;
+	delete(keys: string[]): Promise<number>;
+	list<T>(options: { prefix: string }): Promise<Map<string, T>>;
+}
+
+/** The slice of `DurableObjectState` this object uses. */
+export interface LinkState {
+	acceptWebSocket(socket: LinkSocket, tags?: string[]): void;
+	getWebSockets(tag?: string): LinkSocket[];
+	storage: LinkStorage;
+}
+
+/** What `/healthz` and a smoke may know about the link. No content — the body is public. */
+export interface LinkStatus {
+	connected: boolean;
+	/** When the socket that is up now connected, ISO. */
+	since: string | null;
+}
+
+/** `new WebSocketPair()` on workerd; a test passes its own. */
+export type PairMaker = () => { client: unknown; server: LinkSocket };
+
+const workerdPair: PairMaker = () => {
+	const pair = new (globalThis as unknown as { WebSocketPair: new () => Record<string, unknown> }).WebSocketPair();
+	const [client, server] = Object.values(pair);
+	return { client, server: server as LinkSocket };
+};
+
+/**
+ * The Mac asleep — the last good answer, as of when (station, task 089). Off unless an app asks.
+ *
+ * 🔴 **The Worker cannot read a session** — the gate is the Mac's. So an answer is keyed by the
+ * SHA-256 of the request's own session cookie: a request gets back only what that exact cookie
+ * was already shown, for no longer than {@link OfflineCache.ttlMs} (make it the Mac's session
+ * TTL). A sign-out, or any `401` from the Mac under a cookie, drops everything kept for it. A
+ * request with no cookie gets the offline `503`.
+ */
+export interface OfflineCache {
+	/** The app's session cookie name, e.g. `station_session`. */
+	cookie: string;
+	/** Every path that ends a session — kept answers for the cookie are dropped on it. */
+	signOut: readonly string[];
+	/** How long an answer may be served with the Mac away. */
+	ttlMs: number;
+	/** The header an offline answer carries: when the Mac gave it, ISO. */
+	asOfHeader: string;
+	/** Bigger answers are not kept. Default 512 KB. */
+	maxKeptBody?: number;
+}
+
+export interface RelayLinkOptions {
+	/** For the messages: `"station's Mac …"`. */
+	app: string;
+	/** The JSON 503's `error` while no Mac is linked. Say what dials out and when. */
+	offlineMessage: string;
+	/** Default {@link DEFAULT_MAX_BODY_BYTES}. Set it to at least the Mac's own body ceiling. */
+	maxBodyBytes?: number;
+	/** Default {@link DEFAULT_RELAY_TIMEOUT_MS}. Must exceed the Mac's longest held request. */
+	timeoutMs?: number;
+	/** Absent: nothing is kept and a Mac away is always the 503. */
+	offline?: OfflineCache;
+	makePair?: PairMaker;
+	now?: () => number;
+}
+
+interface Kept {
+	body: string;
+	contentType: string;
+	at: number;
+}
+
+const json = (status: number, body: unknown) =>
+	new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store" } });
+
+/**
+ * The Durable Object that holds the Mac's end of the link. Subclass it in the app's Worker with
+ * the runtime's `(state, env)` constructor and this one's options:
+ *
+ * ```ts
+ * export class MacLink extends RelayLink {
+ *   constructor(state: LinkState) { super(state, { app: "roms", offlineMessage: "…" }); }
+ * }
+ * ```
+ *
+ * The Worker hands it three paths: `/__link` (a verified upgrade — {@link linkKeyMatches} first),
+ * `/__status`, and anything else, which is relayed.
+ *
+ * ## Why an object and not the isolate
+ *
+ * The Mac's socket and a browser's request must MEET, and they arrive in different isolates. An
+ * object addressed by one name is the one place every isolate reaches.
+ *
+ * ## Hibernation
+ *
+ * Accepted with `state.acceptWebSocket`, so a quiet day is not billed as duration. The pending
+ * map is memory, and that is correct: an object with a request in flight is not evicted.
+ *
+ * ## One Mac
+ *
+ * A second link REPLACES the first (close code 4000): a Mac that woke from sleep reconnects before
+ * the edge has noticed its old socket died, and a relay that sent to the dead one would time every
+ * request out for as long as that took.
+ *
+ * 🔴 A plain class with a `fetch` method, NOT `extends DurableObject`: importing
+ * `cloudflare:workers` leaks Worker globals over a Bun host's type graph. The hibernation handlers
+ * are found by name.
+ */
+export class RelayLink {
+	private readonly pending = new Map<string, { socket: LinkSocket; resolve: (r: Response) => void; timer: ReturnType<typeof setTimeout> }>();
+	private readonly makePair: PairMaker;
+	protected readonly timeoutMs: number;
+	protected readonly maxBodyBytes: number;
+	private readonly now: () => number;
+
+	constructor(
+		private readonly state: LinkState,
+		private readonly options: RelayLinkOptions,
+	) {
+		this.makePair = options.makePair ?? workerdPair;
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_RELAY_TIMEOUT_MS;
+		this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+		this.now = options.now ?? Date.now;
+	}
+
+	async fetch(request: Request): Promise<Response> {
+		const path = new URL(request.url).pathname;
+		if (path === "/__link") return this.accept();
+		if (path === "/__status") return json(200, this.status());
+		return this.relay(request);
+	}
+
+	status(): LinkStatus {
+		const socket = this.state.getWebSockets()[0];
+		const attachment = socket?.deserializeAttachment() as { since?: string } | null | undefined;
+		return { connected: socket !== undefined, since: attachment?.since ?? null };
+	}
+
+	private accept(): Response {
+		for (const old of this.state.getWebSockets()) old.close(4000, "replaced by a newer link");
+		const { client, server } = this.makePair();
+		this.state.acceptWebSocket(server);
+		server.serializeAttachment({ since: new Date().toISOString() });
+		return new Response(null, { status: 101, webSocket: client } as ResponseInit);
+	}
+
+	private offline(): Response {
+		return json(503, { error: this.options.offlineMessage, link: "down" });
+	}
+
+	/** Relay, and keep or drop what the answer says about the cookie that asked — see {@link OfflineCache}. */
+	private async relay(request: Request): Promise<Response> {
+		const cache = this.options.offline;
+		if (!cache) return this.state.getWebSockets()[0] ? this.send(request) : this.offline();
+		const url = new URL(request.url);
+		const cookie = cookieValue(request.headers.get("cookie"), cache.cookie);
+		const owner = cookie ? await sha256Hex(cookie) : null;
+		const keyed = `${url.pathname}${url.search}`;
+		const cacheable = owner !== null && request.method === "GET" && url.pathname.startsWith("/api/");
+		if (owner && cache.signOut.includes(url.pathname)) await this.forget(owner);
+		if (!this.state.getWebSockets()[0]) {
+			if (cacheable) {
+				const kept = await this.state.storage.get<Kept>(`c:${owner}:${keyed}`);
+				if (kept && this.now() - kept.at < cache.ttlMs) {
+					return new Response(kept.body, {
+						status: 200,
+						headers: { "content-type": kept.contentType, "cache-control": "no-store", [cache.asOfHeader]: new Date(kept.at).toISOString() },
+					});
+				}
+			}
+			return this.offline();
+		}
+		const response = await this.send(request);
+		if (owner && response.status === 401) await this.forget(owner);
+		else if (cacheable && response.status === 200 && (response.headers.get("content-type") ?? "").includes("json")) {
+			const body = await response.clone().text();
+			if (body.length <= (cache.maxKeptBody ?? 512 * 1024)) {
+				const at = this.now();
+				await this.state.storage.put(`c:${owner}:${keyed}`, { body, contentType: response.headers.get("content-type") ?? "application/json", at } satisfies Kept);
+				// The newest cookie the Mac honoured is the one a `warm` frame refreshes under.
+				await this.state.storage.put("warm", { cookie, at });
+			}
+		}
+		return response;
+	}
+
+	/** Drop every answer kept for one cookie, and the warm cookie if it is that one. */
+	private async forget(owner: string): Promise<void> {
+		const keys = [...(await this.state.storage.list({ prefix: `c:${owner}:` })).keys()];
+		const warm = await this.state.storage.get<{ cookie: string }>("warm");
+		if (warm && (await sha256Hex(warm.cookie)) === owner) keys.push("warm");
+		if (keys.length > 0) await this.state.storage.delete(keys);
+	}
+
+	/** Refresh every read the Mac named, under the newest cookie it honoured — if that is still fresh. */
+	private async warm(paths: readonly string[]): Promise<void> {
+		const cache = this.options.offline;
+		if (!cache) return;
+		const warm = await this.state.storage.get<{ cookie: string; at: number }>("warm");
+		if (!warm || this.now() - warm.at >= cache.ttlMs) return;
+		for (const path of paths) {
+			if (!this.state.getWebSockets()[0]) return;
+			await this.relay(new Request(`https://relay.link${path}`, { headers: { cookie: `${cache.cookie}=${warm.cookie}` } }));
+		}
+	}
+
+	private async send(request: Request): Promise<Response> {
+		const socket = this.state.getWebSockets()[0];
+		if (!socket) return this.offline();
+		const tooBig = () => json(413, { error: `request body over the link's ${this.maxBodyBytes} bytes` });
+		const declared = Number(request.headers.get("content-length") ?? 0);
+		if (declared > this.maxBodyBytes) return tooBig();
+		const id = crypto.randomUUID();
+		const frame = await requestFrame(id, request);
+		// Exactly, off the base64: a chunked upload carries no content-length, and a slack bound let
+		// the ceiling + 2 bytes through (roms' suite caught it at MAX_BODY_BYTES + 1).
+		const pad = frame.body?.endsWith("==") ? 2 : frame.body?.endsWith("=") ? 1 : 0;
+		if (frame.body !== null && (frame.body.length / 4) * 3 - pad > this.maxBodyBytes) return tooBig();
+		return await new Promise<Response>((resolve) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				resolve(json(504, { error: `${this.options.app}'s Mac did not answer ${frame.method} ${frame.path} within ${this.timeoutMs / 1000}s` }));
+			}, this.timeoutMs);
+			this.pending.set(id, { socket, resolve, timer });
+			try {
+				socket.send(JSON.stringify(frame));
+			} catch (error) {
+				clearTimeout(timer);
+				this.pending.delete(id);
+				resolve(json(502, { error: `the link refused the request: ${(error as Error).message}` }));
+			}
+		});
+	}
+
+	webSocketMessage(_socket: LinkSocket, message: string | ArrayBuffer): void | Promise<void> {
+		if (typeof message !== "string") return;
+		const warm = parseWarmFrame(message);
+		if (warm) return this.warm(warm.paths);
+		const frame = parseFrame(message);
+		if (frame?.t !== "res") return;
+		const waiting = this.pending.get(frame.id);
+		if (!waiting) return;
+		clearTimeout(waiting.timer);
+		this.pending.delete(frame.id);
+		waiting.resolve(frameToResponse(frame));
+	}
+
+	webSocketClose(socket: LinkSocket, code: number, reason: string): void {
+		for (const [id, waiting] of this.pending) {
+			if (waiting.socket !== socket) continue;
+			clearTimeout(waiting.timer);
+			this.pending.delete(id);
+			waiting.resolve(json(502, { error: `${this.options.app}'s link closed mid-request (${code}${reason ? ` ${reason}` : ""})` }));
+		}
+		try {
+			socket.close(code, reason);
+		} catch {}
+	}
+
+	webSocketError(socket: LinkSocket): void {
+		this.webSocketClose(socket, 1011, "socket error");
+	}
+}
+
+/**
+ * The Worker's `/link` door, in one call: WebSocket only, a deployment with no digest refuses every
+ * link rather than accepting any, a wrong key is a 401 before the object is reached, and a right one
+ * is handed to the object as `/__link`.
+ */
+export async function acceptLink(
+	request: Request,
+	digest: string | undefined,
+	link: { fetch(request: Request): Promise<Response> },
+	names: { app: string; mintCommand: string },
+): Promise<Response> {
+	if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") return json(426, { error: "the link is a WebSocket" });
+	if (!digest) return json(503, { error: `this deployment holds no link key — \`${names.mintCommand}\` mints one` });
+	if (!(await linkKeyMatches(request.headers.get("authorization"), digest))) return json(401, { error: `not ${names.app}'s Mac` });
+	return link.fetch(new Request(`${new URL(request.url).origin}/__link`, request));
+}

package/src/relayLink.ts

@@ -0,0 +1,210 @@
+/**
+ * `cursedops/relay-link` — the MAC half of a relay (`cursedops/relay` is the Worker half): dial the
+ * app's Worker at `/link` over ONE outbound WebSocket, answer every request frame that comes down
+ * it with the app's own `fetch`, reconnect when it closes, and mint (= rotate) the key.
+ *
+ * Lifted from `apps/station/scripts/link.ts` and `apps/station/scripts/link-key.ts` (task 047) when `apps/roms`
+ * needed the identical dialer (task 065). What stays in each app: which process dials (station's
+ * `com.station.link`, roms' own `com.roms.host`), what else that process arms, and its names.
+ *
+ * 🔴 **The Mac listens on nothing for the relay.** What reaches the app arrives down a socket this
+ * process opened to a hostname it verified over TLS, holding a key only the Worker's digest matches.
+ *
+ * 🔴 **No timer asks anything** (owner, 2026-09-15: *"There should be no polling"*). The one
+ * `setTimeout` is the reconnect after the socket CLOSES — a sleeping Mac's socket dies, and the link
+ * is back within seconds of waking, backing off to a minute while the Worker is unreachable.
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { frameToRequest, parseFrame, type ResponseFrame, responseFrame, sha256Hex, toBase64 } from "cursedops/relay";
+import { readEnvFile } from "cursedops/worker-deploy";
+
+export interface LinkSettings {
+	url: string;
+	key: string;
+}
+
+/**
+ * The link's URL and key out of its 0600 env file (`<APP>_LINK_URL`, `<APP>_LINK_KEY`), or a sentence
+ * saying what is wrong. `wss://<host>/link`, or `ws://127.0.0.1:<port>/link` for a local workerd.
+ */
+export function readLinkSettings(text: string, prefix: string, mintCommand = "bun run link:key"): LinkSettings | string {
+	const found = readEnvFile(text);
+	const url = found[`${prefix}_LINK_URL`]?.trim() ?? "";
+	const key = found[`${prefix}_LINK_KEY`]?.trim() ?? "";
+	if (!/^wss:\/\/[^/]+\/link$/.test(url) && !/^ws:\/\/(127\.0\.0\.1|localhost)(:\d+)?\/link$/.test(url)) {
+		return `${prefix}_LINK_URL must be wss://<host>/link (or ws://127.0.0.1:<port>/link for a local workerd), got "${url}"`;
+	}
+	if (key.length < 32) return `${prefix}_LINK_KEY is missing or short — \`${mintCommand}\` mints one`;
+	return { url, key };
+}
+
+/** The public origin a link's URL belongs to — the origin the Mac's app builds its URLs on. */
+export const publicOriginOf = (linkUrl: string): string => {
+	const u = new URL(linkUrl);
+	return `${u.protocol === "wss:" ? "https:" : "http:"}//${u.host}`;
+};
+
+/**
+ * The Access service token, when the link dials a host behind Access (a `*-stage` host). Measured on
+ * station's first stage link: without these the edge refused every handshake (1006).
+ */
+export function linkAccessHeaders(env: Record<string, string | undefined>): Record<string, string> {
+	const id = env.CF_ACCESS_CLIENT_ID?.trim();
+	const secret = env.CF_ACCESS_CLIENT_SECRET?.trim();
+	return id && secret ? { "CF-Access-Client-Id": id, "CF-Access-Client-Secret": secret } : {};
+}
+
+/** Answer one frame with `fetch`, never throwing: a crash in a route is a 500 on the wire. */
+export async function answerFrame(
+	fetch: (request: Request) => Response | Promise<Response>,
+	text: string,
+	origin: string,
+	app = "the app",
+): Promise<ResponseFrame | null> {
+	const frame = parseFrame(text);
+	if (frame?.t !== "req") return null;
+	try {
+		return await responseFrame(frame.id, await fetch(frameToRequest(frame, origin)));
+	} catch (error) {
+		const body = new TextEncoder().encode(JSON.stringify({ error: `${app}'s Mac failed ${frame.method} ${frame.path}: ${(error as Error).message}` }));
+		return { t: "res", id: frame.id, status: 500, headers: [["content-type", "application/json"]], body: toBase64(body) };
+	}
+}
+
+/** The one socket shape the dialer uses — the global `WebSocket` in Bun, a fake in a test. */
+export interface DialSocket {
+	send(data: string): void;
+	close(code?: number, reason?: string): void;
+	addEventListener(type: "open" | "message" | "close" | "error", listener: (event: { data?: unknown; code?: number; reason?: string }) => void): void;
+}
+
+export interface DialOptions {
+	settings: LinkSettings;
+	/** The app's own `fetch` — every request frame is answered with it. */
+	fetch: (request: Request) => Response | Promise<Response>;
+	/** The origin each relayed Request is built on. Default: the link URL's ({@link publicOriginOf}). */
+	origin?: string;
+	/** For the log lines: `[roms-link] …`. */
+	app: string;
+	/** Extra handshake headers — {@link linkAccessHeaders} for a host behind Access. */
+	headers?: Record<string, string>;
+	/** Sent right after each connect — station's `warm` frame. */
+	onOpen?: (socket: DialSocket) => void;
+	log?: (line: string) => void;
+	/** Tests only. */
+	openSocket?: (url: string, headers: Record<string, string>) => DialSocket;
+	setTimer?: (fn: () => void, ms: number) => unknown;
+}
+
+export interface DialedLink {
+	/** Stop reconnecting and close the socket. */
+	close(): void;
+	/** Is a socket open right now? */
+	connected(): boolean;
+}
+
+const bunSocket = (url: string, headers: Record<string, string>): DialSocket =>
+	// Bun's WebSocket takes `{ headers }` as its second argument; the DOM typing says protocols.
+	new WebSocket(url, { headers } as unknown as string[]) as unknown as DialSocket;
+
+/** Dial, answer, and redial on close with a 1 s → 60 s backoff. See the header. */
+export function dialLink(options: DialOptions): DialedLink {
+	const origin = options.origin ?? publicOriginOf(options.settings.url);
+	const log = options.log ?? ((line: string) => console.log(line));
+	const open = options.openSocket ?? bunSocket;
+	const later = options.setTimer ?? ((fn: () => void, ms: number) => setTimeout(fn, ms));
+	let backoff = 1_000;
+	let stopped = false;
+	let current: DialSocket | null = null;
+	let isOpen = false;
+	const connect = () => {
+		if (stopped) return;
+		const socket = open(options.settings.url, { ...(options.headers ?? {}), authorization: `Bearer ${options.settings.key}` });
+		current = socket;
+		socket.addEventListener("open", () => {
+			backoff = 1_000;
+			isOpen = true;
+			log(`[${options.app}-link] ✓ linked to ${origin} — answering its requests`);
+			options.onOpen?.(socket);
+		});
+		socket.addEventListener("message", async (event) => {
+			const reply = await answerFrame(options.fetch, String(event.data), origin, options.app);
+			if (reply) socket.send(JSON.stringify(reply));
+		});
+		socket.addEventListener("close", (event) => {
+			isOpen = false;
+			if (stopped) return;
+			log(`[${options.app}-link] link closed (${event.code}${event.reason ? ` ${event.reason}` : ""}); reconnecting in ${backoff / 1000}s`);
+			later(connect, backoff);
+			backoff = Math.min(backoff * 2, 60_000);
+		});
+		socket.addEventListener("error", () => {
+			/* the close that follows reconnects */
+		});
+	};
+	connect();
+	return {
+		close() {
+			stopped = true;
+			current?.close(1000, "closed by the Mac");
+		},
+		connected: () => isOpen,
+	};
+}
+
+/** 32 random bytes, hex — a link key. */
+export function mintLinkKey(): string {
+	return [...crypto.getRandomValues(new Uint8Array(32))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** The link's env file, single-quoted so a shell `source` cannot mangle it. */
+export function linkEnvText(prefix: string, url: string, key: string, mintCommand = "bun run link:key"): string {
+	return `# ${prefix.toLowerCase()}'s link — written by \`${mintCommand}\`. The key never leaves this Mac.\n${prefix}_LINK_URL='${url}'\n${prefix}_LINK_KEY='${key}'\n`;
+}
+
+export interface RotateSpec {
+	/** The app checkout — where `wrangler secret put` runs. */
+	appDir: string;
+	/** The 0600 env file the Mac reads. */
+	file: string;
+	/** `ROMS` → `ROMS_LINK_URL` / `ROMS_LINK_KEY` / `ROMS_LINK_KEY_SHA256`. */
+	prefix: string;
+	/** A new URL, or undefined to keep the file's. */
+	url?: string;
+	/** `cloudflareCredential(...)` — the env overlay wrangler runs with. */
+	credential: Record<string, string>;
+	/** `wrangler secret put … --env <env>` when set. */
+	env?: string;
+	/** Tests only. */
+	putSecret?: (name: string, value: string) => { ok: boolean; detail: string };
+}
+
+/**
+ * Mint (= ROTATE) the link key: the digest goes to the Worker FIRST, the key to the 0600 file only
+ * if the Worker took it — so a refused upload changes nothing on the Mac. The old key stops matching
+ * the moment the digest is replaced; the running link is refused on its next connect.
+ */
+export async function rotateLinkKey(spec: RotateSpec): Promise<{ ok: true; file: string } | { ok: false; why: string }> {
+	const previous = existsSync(spec.file) ? readEnvFile(readFileSync(spec.file, "utf8")) : {};
+	const url = spec.url ?? previous[`${spec.prefix}_LINK_URL`];
+	if (!url) return { ok: false, why: `no link URL yet — pass \`--url wss://<worker host>/link\` the first time` };
+	const key = mintLinkKey();
+	const secret = `${spec.prefix}_LINK_KEY_SHA256`;
+	const put =
+		spec.putSecret ??
+		((name: string, value: string) => {
+			const r = spawnSync("bunx", ["wrangler@4", "secret", "put", name, ...(spec.env ? ["--env", spec.env] : [])], {
+				cwd: spec.appDir,
+				input: value,
+				env: { ...process.env, ...spec.credential },
+				encoding: "utf8",
+			});
+			return { ok: r.status === 0, detail: `${r.stderr ?? ""}` };
+		});
+	const done = put(secret, await sha256Hex(key));
+	if (!done.ok) return { ok: false, why: `the Worker refused the digest — nothing was changed on this Mac:\n${done.detail}` };
+	writeFileSync(spec.file, linkEnvText(spec.prefix, url, key), { mode: 0o600 });
+	chmodSync(spec.file, 0o600);
+	return { ok: true, file: spec.file };
+}