@statewalker/webrun-http-proxy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @statewalker/webrun-http-proxy
+
+A reverse proxy as a fetch handler: one route table, two kinds of upstream — an
+in-process handler, or a remote origin.
+
+**Zero runtime dependencies.**
+
+**The reverse proxy and "expose a local app" are one mechanism.** Twelve
+scenarios establish it: only the last step differs — a local handler is
+*called*, a URL upstream is *re-issued*. Matching, rewriting, the listing, the
+marker header and streaming are shared.
+
+The scenarios moved here with the code rather than being rewritten, because a
+list that changes when it moves proves nothing about the move. **They run in
+Node here, and only Node.** The prototype also ran them in Chromium, which is
+what established that both upstream kinds behave identically on both platforms
+and that exactly one row cannot pass in a browser (below). That second column
+needs a bundler and a browser and does not exist in this package yet;
+`tests/scenarios.test.ts` says so in its own header.
+
+```ts
+import { routeTable, urlUpstream } from "@statewalker/webrun-http-proxy";
+
+const handler = routeTable({
+  routes: () => [
+    { prefix: "/openai", describe: "OpenAI", upstream: urlUpstream({ base: "https://api.openai.com/v1" }) },
+    { prefix: "/local",  describe: "in-process", upstream: myHandler },
+  ],
+});
+```
+
+## `routes` may be a thunk, and that is load-bearing
+
+The proxy page edits routes and types credentials **while traffic flows**. The
+table is re-read per request for exactly that reason; a snapshot taken at
+construction would serve the old table until something restarted it.
+
+## Secrets are never persisted
+
+A route may carry a credential. The header's **name** is configuration and is
+saved; the header's **value** lives in memory and is merged per request.
+
+`StoredRoute` has no field a value fits in, and `save()` **throws** rather than
+dropping one quietly — a silent drop means a route that worked before a reload
+and 401s after it. `assertNoSecrets` is exported so an adapter written
+elsewhere enforces the same rule instead of inventing its own idea of what a
+secret looks like.
+
+This is not hypothetical: an earlier shape of this API stored a whole `Route`,
+and building the proxy page on it would have written bearer keys into
+`localStorage` — where they survive a reload, a shared machine, and anyone who
+opens devtools.
+
+`load()` returns `undefined` for **never written**, which is not the same as
+`[]`. A first visit seeds its defaults; a visit after the operator deleted
+every route must not bring them back.
+
+## Hygiene belongs to the URL upstream, not to the table
+
+Two measured rows force the asymmetry:
+
+- Re-issuing to a third party **consumes** the caller's `authorization`, the
+  way `Proxy-Authorization` is consumed by the proxy it names. Forwarding it
+  handed a bearer token to an upstream that echoed it straight back.
+- Calling a **local** handler must not strip it, because a handler on this side
+  of the proxy still needs to know who is calling.
+
+Same rule, `stripRequestHeaders` for anything else your system treats as
+identity.
+
+## Two shipping defects, fixed and pinned
+
+- A **redirecting upstream** was reported as `502 upstream-unreachable`: an
+  opaque redirect has status `0`, and constructing a `Response` with it throws
+  *inside* the `try`.
+- The outbound request carried **no `signal`**, so an aborted caller left the
+  upstream call running.
+
+## One row a browser cannot pass
+
+`Via` is a forbidden header name under the Fetch spec — a page may not set it,
+and the browser drops it with no error. ADR-0015 has an intermediary announce
+itself with `Via`, so that part is unimplementable in a browser-hosted
+intermediary. A fact about the platform, not about this code.
+
+## Entry points
+
+| Import | Holds |
+|---|---|
+| `.` | `routeTable`, `urlUpstream`, `RouteStore`, `assertNoSecrets`, `rehydrate` |
+| `./node` | `fileRouteStore(path)` — write-then-rename |
+| `./browser` | `localStorageRouteStore(key?)` |
+
+No transport, no crypto, no platform at the root — proxying needs none of
+them, which is why a proxy **page** and a Node process share this package.
+`tests/boundary.test.ts` asserts it, and the dependency list is **empty**.
+
+## Where it came from
+
+Extracted from `@statewalker/httpeers-expose`, where it was a mesh concept by
+accident of where it was written. Nothing in it is about peers: it moves a
+`Request` to an upstream and a `Response` back. The one place the old package
+knew about meshes is now **`stripRequestHeaders`** — request headers to drop
+before re-issuing upstream, beyond the `authorization` and hop-by-hop sets it
+always drops. httpeers passes its proven-peer header there, because re-issuing
+to a third party must not tell an outside origin which mesh peer called.
+
+The single import it carried was `FetchHandler`, a one-line type. Extracting it
+therefore *dropped* a dependency rather than moving one.
+
+**22 tests**, and the twelve scenarios run inside two of them — the suite
+asserts that every scenario ran (guarding against an empty list) and that
+none failed.

package/dist/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The browser profile: routes in `localStorage`.
+ *
+ * `localStorage` IS the reason `assertNoSecrets` exists. It survives a reload,
+ * a shared machine and anyone who opens devtools, so a credential written here
+ * is a credential leaked — which is exactly what building the proxy page on an
+ * earlier shape of this API would have done.
+ */
+import { type RouteStore } from "./store.js";
+export declare function localStorageRouteStore(key?: string): RouteStore;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAmB,KAAK,UAAU,EAAoB,MAAM,YAAY,CAAC;AAIhF,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAoB,GAAG,UAAU,CAmB5E"}

package/dist/browser.js

@@ -0,0 +1,30 @@
+import { n as assertNoSecrets } from "./store-BwcCz3M9.js";
+//#region src/browser.ts
+/**
+* The browser profile: routes in `localStorage`.
+*
+* `localStorage` IS the reason `assertNoSecrets` exists. It survives a reload,
+* a shared machine and anyone who opens devtools, so a credential written here
+* is a credential leaked — which is exactly what building the proxy page on an
+* earlier shape of this API would have done.
+*/
+const DEFAULT_KEY = "webrun:proxy:routes";
+function localStorageRouteStore(key = DEFAULT_KEY) {
+	return {
+		async load() {
+			const raw = globalThis.localStorage?.getItem(key);
+			if (raw == null) return void 0;
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return [];
+			}
+		},
+		async save(routes) {
+			assertNoSecrets(routes);
+			globalThis.localStorage?.setItem(key, JSON.stringify(routes));
+		}
+	};
+}
+//#endregion
+export { localStorageRouteStore };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A reverse proxy as a fetch handler.
+ *
+ * "Reverse proxy" and "expose a local app" are ONE MECHANISM, and twelve
+ * scenarios establish it: only the last step differs — a local handler is
+ * *called*, a URL upstream is *re-issued*. Matching, rewriting, the listing,
+ * the marker header and streaming are shared.
+ *
+ * EXTRACTED FROM `@statewalker/httpeers-expose`, where it was a mesh concept
+ * by accident of where it was written. Nothing in it is about peers: it moves
+ * a `Request` to an upstream and a `Response` back. The one place the old
+ * package knew about meshes is now `stripRequestHeaders`, which any caller
+ * uses for whatever its own system treats as proven identity.
+ */
+export { type FetchHandler, MARKER, type Route, routeTable, type RouteTableInit, type Upstream, urlUpstream, type UrlUpstreamInit, } from "./proxy.js";
+export { matchRoute, type ProxyRoute, upstreamUrl } from "./routes.js";
+export { assertNoSecrets, rehydrate, type RehydrateInit, type RouteStore, SecretNotPersistableError, type StoredRoute, toStoredRoute, } from "./store.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,KAAK,YAAY,EACjB,MAAM,EACN,KAAK,KAAK,EACV,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,eAAe,EACf,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,yBAAyB,EACzB,KAAK,WAAW,EAChB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,133 @@
+import { i as toStoredRoute, n as assertNoSecrets, r as rehydrate, t as SecretNotPersistableError } from "./store-BwcCz3M9.js";
+//#region src/routes.ts
+/**
+* The route owning `pathname`, and what follows its prefix.
+*
+* LONGEST PREFIX WINS, so `/openai/admin` can go somewhere other than
+* `/openai`, and the answer does not depend on the order routes were added --
+* an ordering dependency would make the UI's list order silently meaningful.
+*/
+function matchRoute(routes, pathname) {
+	let best = null;
+	for (const route of routes) {
+		if (!pathname.startsWith(route.prefix)) continue;
+		const rest = pathname.slice(route.prefix.length);
+		if (rest !== "" && !rest.startsWith("/")) continue;
+		if (best == null || route.prefix.length > best.route.prefix.length) best = {
+			route,
+			rest
+		};
+	}
+	return best;
+}
+/** The absolute upstream URL for a matched route, carrying `search` unchanged. */
+function upstreamUrl(route, rest, search) {
+	return `${route.upstream.endsWith("/") ? route.upstream.slice(0, -1) : route.upstream}${rest}${search}`;
+}
+//#endregion
+//#region src/proxy.ts
+/** Marks this layer's OWN responses, so they are never mistaken for an upstream's. Same header the proxy already uses. */
+const MARKER = "x-webrun-proxy";
+/**
+* The mount: match, strip, delegate. Identical on both platforms — it touches
+* no DOM, no `node:` module and no network of its own.
+*/
+function routeTable(init) {
+	const mountPrefix = init.mountPrefix ?? "/proxy";
+	return async (request) => {
+		const url = new URL(request.url);
+		const pathname = url.pathname.startsWith(mountPrefix) ? url.pathname.slice(mountPrefix.length) : url.pathname;
+		if ((pathname === "" || pathname === "/") && request.method === "GET") {
+			const body = JSON.stringify({ routes: init.routes().map((r) => ({
+				prefix: r.prefix,
+				upstream: r.describe
+			})) });
+			return new Response(body, { headers: { "content-type": "application/json" } });
+		}
+		const found = matchRoute(init.routes().map((r) => ({
+			prefix: r.prefix,
+			upstream: r.describe,
+			headers: {}
+		})), pathname);
+		if (found == null) return new Response(`no route for ${pathname}`, {
+			status: 404,
+			headers: { [MARKER]: "no-route" }
+		});
+		const route = init.routes().find((r) => r.prefix === found.route.prefix);
+		if (route == null) return new Response(`no route for ${pathname}`, {
+			status: 404,
+			headers: { [MARKER]: "no-route" }
+		});
+		const rewritten = new URL(`${found.rest || "/"}${url.search}`, url.origin);
+		const forwarded = new Request(rewritten, {
+			method: request.method,
+			headers: request.headers,
+			body: request.body,
+			...request.body != null ? { duplex: "half" } : {},
+			signal: request.signal
+		});
+		return route.upstream(forwarded);
+	};
+}
+/**
+* Re-issue the request to a URL — the "reverse proxy" half.
+*
+* THE HYGIENE IS HERE AND NOT IN THE TABLE, because it applies only when a
+* request LEAVES the mesh. Calling a local handler must not strip the caller's
+* identity; re-issuing to a third party must.
+*/
+function urlUpstream(init) {
+	const doFetch = init.fetchImpl ?? globalThis.fetch;
+	return async (request) => {
+		const from = new URL(request.url);
+		const target = new URL(`.${from.pathname}${from.search}`, ensureSlash(init.base));
+		const headers = new Headers(request.headers);
+		headers.delete("authorization");
+		for (const name of init.stripRequestHeaders ?? []) headers.delete(name);
+		for (const hop of HOP_BY_HOP) headers.delete(hop);
+		if (init.via != null) headers.set("via", init.via);
+		for (const [name, value] of Object.entries(init.headers ?? {})) headers.set(name, value);
+		for (const [name, value] of Object.entries(init.credential?.() ?? {})) headers.set(name, value);
+		const outbound = new Request(target, {
+			method: request.method,
+			headers,
+			body: request.body,
+			...request.body != null ? { duplex: "half" } : {},
+			signal: request.signal,
+			redirect: "manual"
+		});
+		try {
+			const upstream = await doFetch(outbound);
+			if (upstream.type === "opaqueredirect" || upstream.status === 0) return new Response("upstream redirected; the proxy does not follow redirects", {
+				status: 502,
+				headers: { [MARKER]: "upstream-redirect" }
+			});
+			return new Response(upstream.body, {
+				status: upstream.status,
+				statusText: upstream.statusText,
+				headers: upstream.headers
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return new Response(`upstream ${init.base} could not be reached: ${message}\nIf the upstream is up, it most likely does not permit cross-origin requests.`, {
+				status: 502,
+				headers: { [MARKER]: "upstream-unreachable" }
+			});
+		}
+	};
+}
+const HOP_BY_HOP = [
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+];
+function ensureSlash(base) {
+	return base.endsWith("/") ? base : `${base}/`;
+}
+//#endregion
+export { MARKER, SecretNotPersistableError, assertNoSecrets, matchRoute, rehydrate, routeTable, toStoredRoute, upstreamUrl, urlUpstream };

package/dist/node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Node profile: routes on disk.
+ *
+ * Write-then-rename, for the same reason the identity store does it — a
+ * truncated file is not a corrupt file somebody notices, it is a table that
+ * silently loses routes. Here the cost is smaller than a lost mesh identity,
+ * but the fix is two lines and the failure is equally quiet.
+ */
+import { type RouteStore } from "./store.js";
+export declare function fileRouteStore(path: string): RouteStore;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAmB,KAAK,UAAU,EAAoB,MAAM,YAAY,CAAC;AAEhF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAoBvD"}

package/dist/node.js

@@ -0,0 +1,33 @@
+import { n as assertNoSecrets } from "./store-BwcCz3M9.js";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+//#region src/node.ts
+/**
+* The Node profile: routes on disk.
+*
+* Write-then-rename, for the same reason the identity store does it — a
+* truncated file is not a corrupt file somebody notices, it is a table that
+* silently loses routes. Here the cost is smaller than a lost mesh identity,
+* but the fix is two lines and the failure is equally quiet.
+*/
+function fileRouteStore(path) {
+	return {
+		async load() {
+			try {
+				return JSON.parse(await readFile(path, "utf8"));
+			} catch (error) {
+				if (error.code === "ENOENT") return void 0;
+				throw error;
+			}
+		},
+		async save(routes) {
+			assertNoSecrets(routes);
+			await mkdir(dirname(path), { recursive: true });
+			const staging = `${path}.${process.pid}.${Date.now()}.tmp`;
+			await writeFile(staging, JSON.stringify(routes, null, 2), { mode: 384 });
+			await rename(staging, path);
+		}
+	};
+}
+//#endregion
+export { fileRouteStore };

package/dist/proxy.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The candidate `expose` package: ONE route table, two kinds of upstream.
+ *
+ * THE CLAIM THIS TESTS. "Reverse proxy" and "expose a local service" are the
+ * same mechanism — match a prefix, rewrite the path, stream the result — and
+ * differ only in the last step: an in-process handler is CALLED, a URL
+ * upstream is RE-ISSUED. If that is true, `routeTable` below serves both and
+ * the two features are one package.
+ *
+ * Everything except the upstream kind is lifted from `services/proxy.ts` and
+ * `services/proxy-routes.ts`, which already run in the mesh: longest-prefix
+ * matching on segment boundaries, the listing at the mount root, the marker
+ * header, the `authorization` rule, route headers applied last, and the body
+ * handed on unread.
+ *
+ * TWO DEFECTS OF THE PROVEN CODE ARE FIXED HERE, both measured in the tests:
+ *
+ *   1. `redirect: "manual"` makes a browser return an opaque response whose
+ *      status is 0, and `new Response(body, { status: 0 })` THROWS — inside
+ *      the try, so a redirecting upstream is reported as
+ *      `502 upstream-unreachable`. `urlUpstream` handles redirects explicitly.
+ *   2. The outbound request carried no `signal`, so an aborted caller left the
+ *      upstream call running. It is forwarded.
+ */
+/**
+ * A handler, in the only shape this package needs.
+ *
+ * Declared here rather than imported: it is one line, and depending on another
+ * package for it would give a proxy a dependency it has no other use for.
+ */
+export type FetchHandler = (request: Request) => Promise<Response>;
+/** Marks this layer's OWN responses, so they are never mistaken for an upstream's. Same header the proxy already uses. */
+export declare const MARKER = "x-webrun-proxy";
+/**
+ * An upstream is just a handler. That is the whole merge: a local service, a
+ * remote origin and another peer are all `(Request) => Promise<Response>`.
+ */
+export type Upstream = FetchHandler;
+export interface Route {
+    /** Path prefix, matched on segment boundaries, longest first. */
+    prefix: string;
+    /** What this route reaches, for the listing at the mount root. Never a credential. */
+    describe: string;
+    upstream: Upstream;
+}
+export interface RouteTableInit {
+    /** Read per request, never snapshotted, so routes can be edited live. */
+    routes: () => readonly Route[];
+    /** Where this table is mounted; stripped before matching. */
+    mountPrefix?: string;
+}
+/**
+ * The mount: match, strip, delegate. Identical on both platforms — it touches
+ * no DOM, no `node:` module and no network of its own.
+ */
+export declare function routeTable(init: RouteTableInit): FetchHandler;
+export interface UrlUpstreamInit {
+    /**
+     * Request headers to drop before re-issuing upstream, beyond the ones this
+     * proxy always drops (`authorization` and the hop-by-hop set).
+     *
+     * For anything the surrounding system treats as proven identity and that a
+     * third-party origin has no business seeing.
+     */
+    stripRequestHeaders?: readonly string[];
+    /** Origin (and optional base path) every request is re-issued against. */
+    base: string;
+    /** Static headers for this destination, applied after the caller's. */
+    headers?: Record<string, string>;
+    /** A credential for this destination, read per request so it need not be held in the route. */
+    credential?: () => Record<string, string> | undefined;
+    /** Injected by tests; defaults to the platform's. */
+    fetchImpl?: typeof fetch;
+    /** `Via` value; omitted, no `Via` is added. */
+    via?: string;
+}
+/**
+ * Re-issue the request to a URL — the "reverse proxy" half.
+ *
+ * THE HYGIENE IS HERE AND NOT IN THE TABLE, because it applies only when a
+ * request LEAVES the mesh. Calling a local handler must not strip the caller's
+ * identity; re-issuing to a third party must.
+ */
+export declare function urlUpstream(init: UrlUpstreamInit): Upstream;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAGnE,0HAA0H;AAC1H,eAAO,MAAM,MAAM,mBAAmB,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC,MAAM,WAAW,KAAK;IACpB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,MAAM,EAAE,MAAM,SAAS,KAAK,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,YAAY,CAyD7D;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,CA6D3D"}

package/dist/routes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which configured upstream a mesh-side path belongs to.
+ *
+ * THE UPSTREAM IS NEVER TAKEN FROM THE REQUEST. `cors-anywhere` puts the
+ * destination in the URL (`/https://example.com/`), which is why its public
+ * instance is permanently abused. Here a caller selects among upstreams the
+ * operator configured and can reach nothing else, so this module must never
+ * gain a wildcard or passthrough mode.
+ */
+export interface ProxyRoute {
+    /** Mesh-side prefix, leading slash, no trailing slash: `/openai`. */
+    prefix: string;
+    /** Upstream base: `https://api.openai.com/v1`. */
+    upstream: string;
+    /** Applied to every forwarded request, last, so operator config wins. */
+    headers: Record<string, string>;
+}
+/**
+ * The route owning `pathname`, and what follows its prefix.
+ *
+ * LONGEST PREFIX WINS, so `/openai/admin` can go somewhere other than
+ * `/openai`, and the answer does not depend on the order routes were added --
+ * an ordering dependency would make the UI's list order silently meaningful.
+ */
+export declare function matchRoute(routes: readonly ProxyRoute[], pathname: string): {
+    route: ProxyRoute;
+    rest: string;
+} | null;
+/** The absolute upstream URL for a matched route, carrying `search` unchanged. */
+export declare function upstreamUrl(route: ProxyRoute, rest: string, search: string): string;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAY5C;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnF"}

package/dist/store-BwcCz3M9.js

@@ -0,0 +1,45 @@
+//#region src/store.ts
+/** Thrown when a caller tries to persist something that looks like a secret. */
+var SecretNotPersistableError = class extends Error {
+	prefix;
+	constructor(prefix) {
+		super(`webrun-http-proxy: refusing to persist a credential value for route ${JSON.stringify(prefix)}. Store the header NAME (\`secretHeader\`) and keep the value in memory — a persisted credential survives a reload, a shared machine, and devtools.`);
+		this.prefix = prefix;
+		this.name = "SecretNotPersistableError";
+	}
+};
+/**
+* The check `save()` implementations run. Exported so an adapter written
+* elsewhere enforces the same rule rather than reimplementing its own idea of
+* what a secret looks like.
+*/
+function assertNoSecrets(routes) {
+	for (const route of routes) {
+		const carrier = route;
+		if (typeof carrier.secret === "string" || typeof carrier.secretValue === "string" || carrier.headers != null && typeof carrier.headers === "object") throw new SecretNotPersistableError(route.prefix);
+	}
+}
+/** Keep only the persistable fields, dropping anything else a caller passed. */
+function toStoredRoute(route) {
+	return {
+		prefix: route.prefix,
+		upstream: route.upstream,
+		describe: route.describe,
+		secretHeader: route.secretHeader ?? null
+	};
+}
+/**
+* Stored routes back into live ones.
+*
+* The secret re-enters here, from wherever the caller keeps it in memory —
+* which is the only place it ever was.
+*/
+function rehydrate(stored, init) {
+	return stored.map((route) => ({
+		prefix: route.prefix,
+		describe: route.describe,
+		upstream: init.upstreamFor(route)
+	}));
+}
+//#endregion
+export { toStoredRoute as i, assertNoSecrets as n, rehydrate as r, SecretNotPersistableError as t };

package/dist/store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Persisting routes — and refusing, mechanically, to persist a secret.
+ *
+ * THE RULE THIS FILE EXISTS TO ENFORCE. A route may carry a credential: an
+ * upstream API key, a bearer token, whatever the operator typed into the proxy
+ * page. The header's NAME is configuration and is saved. The header's VALUE is
+ * a secret, lives in memory, and is merged per request.
+ *
+ * That distinction cannot be left to callers. An earlier shape of this API
+ * stored a whole `Route`, and building the proxy page on it would have written
+ * bearer keys into `localStorage` — where they survive a reload, a shared
+ * machine, and anyone who opens devtools. So `StoredRoute` has no field a
+ * value could go in, and `save()` throws rather than silently dropping one:
+ * silently dropping would mean a route that worked before a reload and
+ * mysteriously 401s after it.
+ *
+ * `load()` RETURNS `undefined` FOR "NEVER WRITTEN", which is not the same as
+ * an empty array and the difference is visible to a user. A first visit should
+ * seed the demo routes; a visit after the operator deleted all of them should
+ * not bring them back. One value distinguishes the two.
+ */
+import type { Route, Upstream } from "./proxy.js";
+/**
+ * A route as it is persisted: the upstream as a URL, and the header NAME only.
+ *
+ * There is deliberately no field for a header value. The type is the
+ * enforcement; `save()`'s check is the belt to its braces.
+ */
+export interface StoredRoute {
+    prefix: string;
+    /** The upstream base URL. A route whose upstream is a live handler cannot be stored. */
+    upstream: string;
+    describe: string;
+    /** The name of the header carrying a credential, or `null` for none. */
+    secretHeader: string | null;
+}
+export interface RouteStore {
+    /** `undefined` means NEVER WRITTEN — distinct from `[]`, which means "the operator deleted them all". */
+    load(): Promise<StoredRoute[] | undefined>;
+    /** Throws if any route carries a credential VALUE. */
+    save(routes: StoredRoute[]): Promise<void>;
+}
+/** Thrown when a caller tries to persist something that looks like a secret. */
+export declare class SecretNotPersistableError extends Error {
+    readonly prefix: string;
+    constructor(prefix: string);
+}
+/**
+ * The check `save()` implementations run. Exported so an adapter written
+ * elsewhere enforces the same rule rather than reimplementing its own idea of
+ * what a secret looks like.
+ */
+export declare function assertNoSecrets(routes: readonly StoredRoute[]): void;
+/** Keep only the persistable fields, dropping anything else a caller passed. */
+export declare function toStoredRoute(route: {
+    prefix: string;
+    upstream: string;
+    describe: string;
+    secretHeader?: string | null;
+}): StoredRoute;
+export interface RehydrateInit {
+    /** Build the live upstream for a stored route. Where the secret VALUE is re-supplied. */
+    upstreamFor: (stored: StoredRoute) => Upstream;
+}
+/**
+ * Stored routes back into live ones.
+ *
+ * The secret re-enters here, from wherever the caller keeps it in memory —
+ * which is the only place it ever was.
+ */
+export declare function rehydrate(stored: readonly StoredRoute[], init: RehydrateInit): Route[];
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,yGAAyG;IACzG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,GAAG,SAAS,CAAC,CAAC;IAC3C,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,gFAAgF;AAChF,qBAAa,yBAA0B,SAAQ,KAAK;aACtB,MAAM,EAAE,MAAM;IAA1C,YAA4B,MAAM,EAAE,MAAM,EAOzC;CACF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAapE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,WAAW,CAOd;AAED,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,WAAW,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,QAAQ,CAAC;CAChD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,KAAK,EAAE,CAMtF"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@statewalker/webrun-http-proxy",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A reverse proxy as a fetch handler: one route table, two kinds of upstream — a local handler or a remote origin.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/webrun-wire.git",
+    "directory": "packages/webrun-http-proxy"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check src tests"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,33 @@
+/**
+ * The browser profile: routes in `localStorage`.
+ *
+ * `localStorage` IS the reason `assertNoSecrets` exists. It survives a reload,
+ * a shared machine and anyone who opens devtools, so a credential written here
+ * is a credential leaked — which is exactly what building the proxy page on an
+ * earlier shape of this API would have done.
+ */
+
+import { assertNoSecrets, type RouteStore, type StoredRoute } from "./store.js";
+
+const DEFAULT_KEY = "webrun:proxy:routes";
+
+export function localStorageRouteStore(key: string = DEFAULT_KEY): RouteStore {
+  return {
+    async load() {
+      const raw = globalThis.localStorage?.getItem(key);
+      // `null` from `getItem` means never written. Distinct from `"[]"`.
+      if (raw == null) return undefined;
+      try {
+        return JSON.parse(raw) as StoredRoute[];
+      } catch {
+        // Corrupt is not "never written": resurrecting defaults over a table
+        // somebody edited would be worse than starting empty and saying so.
+        return [];
+      }
+    },
+    async save(routes) {
+      assertNoSecrets(routes);
+      globalThis.localStorage?.setItem(key, JSON.stringify(routes));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * A reverse proxy as a fetch handler.
+ *
+ * "Reverse proxy" and "expose a local app" are ONE MECHANISM, and twelve
+ * scenarios establish it: only the last step differs — a local handler is
+ * *called*, a URL upstream is *re-issued*. Matching, rewriting, the listing,
+ * the marker header and streaming are shared.
+ *
+ * EXTRACTED FROM `@statewalker/httpeers-expose`, where it was a mesh concept
+ * by accident of where it was written. Nothing in it is about peers: it moves
+ * a `Request` to an upstream and a `Response` back. The one place the old
+ * package knew about meshes is now `stripRequestHeaders`, which any caller
+ * uses for whatever its own system treats as proven identity.
+ */
+
+export {
+  type FetchHandler,
+  MARKER,
+  type Route,
+  routeTable,
+  type RouteTableInit,
+  type Upstream,
+  urlUpstream,
+  type UrlUpstreamInit,
+} from "./proxy.js";
+export { matchRoute, type ProxyRoute, upstreamUrl } from "./routes.js";
+export {
+  assertNoSecrets,
+  rehydrate,
+  type RehydrateInit,
+  type RouteStore,
+  SecretNotPersistableError,
+  type StoredRoute,
+  toStoredRoute,
+} from "./store.js";

package/src/node.ts

@@ -0,0 +1,34 @@
+/**
+ * The Node profile: routes on disk.
+ *
+ * Write-then-rename, for the same reason the identity store does it — a
+ * truncated file is not a corrupt file somebody notices, it is a table that
+ * silently loses routes. Here the cost is smaller than a lost mesh identity,
+ * but the fix is two lines and the failure is equally quiet.
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { assertNoSecrets, type RouteStore, type StoredRoute } from "./store.js";
+
+export function fileRouteStore(path: string): RouteStore {
+  return {
+    async load() {
+      try {
+        return JSON.parse(await readFile(path, "utf8")) as StoredRoute[];
+      } catch (error) {
+        // NEVER WRITTEN, not empty. A first run seeds its defaults; a run
+        // after the operator deleted every route must not resurrect them.
+        if ((error as { code?: string }).code === "ENOENT") return undefined;
+        throw error;
+      }
+    },
+    async save(routes) {
+      assertNoSecrets(routes);
+      await mkdir(dirname(path), { recursive: true });
+      const staging = `${path}.${process.pid}.${Date.now()}.tmp`;
+      await writeFile(staging, JSON.stringify(routes, null, 2), { mode: 0o600 });
+      await rename(staging, path);
+    },
+  };
+}

package/src/proxy.ts

@@ -0,0 +1,227 @@
+/**
+ * The candidate `expose` package: ONE route table, two kinds of upstream.
+ *
+ * THE CLAIM THIS TESTS. "Reverse proxy" and "expose a local service" are the
+ * same mechanism — match a prefix, rewrite the path, stream the result — and
+ * differ only in the last step: an in-process handler is CALLED, a URL
+ * upstream is RE-ISSUED. If that is true, `routeTable` below serves both and
+ * the two features are one package.
+ *
+ * Everything except the upstream kind is lifted from `services/proxy.ts` and
+ * `services/proxy-routes.ts`, which already run in the mesh: longest-prefix
+ * matching on segment boundaries, the listing at the mount root, the marker
+ * header, the `authorization` rule, route headers applied last, and the body
+ * handed on unread.
+ *
+ * TWO DEFECTS OF THE PROVEN CODE ARE FIXED HERE, both measured in the tests:
+ *
+ *   1. `redirect: "manual"` makes a browser return an opaque response whose
+ *      status is 0, and `new Response(body, { status: 0 })` THROWS — inside
+ *      the try, so a redirecting upstream is reported as
+ *      `502 upstream-unreachable`. `urlUpstream` handles redirects explicitly.
+ *   2. The outbound request carried no `signal`, so an aborted caller left the
+ *      upstream call running. It is forwarded.
+ */
+
+/**
+ * A handler, in the only shape this package needs.
+ *
+ * Declared here rather than imported: it is one line, and depending on another
+ * package for it would give a proxy a dependency it has no other use for.
+ */
+export type FetchHandler = (request: Request) => Promise<Response>;
+import { matchRoute } from "./routes.js";
+
+/** Marks this layer's OWN responses, so they are never mistaken for an upstream's. Same header the proxy already uses. */
+export const MARKER = "x-webrun-proxy";
+
+/**
+ * An upstream is just a handler. That is the whole merge: a local service, a
+ * remote origin and another peer are all `(Request) => Promise<Response>`.
+ */
+export type Upstream = FetchHandler;
+
+export interface Route {
+  /** Path prefix, matched on segment boundaries, longest first. */
+  prefix: string;
+  /** What this route reaches, for the listing at the mount root. Never a credential. */
+  describe: string;
+  upstream: Upstream;
+}
+
+export interface RouteTableInit {
+  /** Read per request, never snapshotted, so routes can be edited live. */
+  routes: () => readonly Route[];
+  /** Where this table is mounted; stripped before matching. */
+  mountPrefix?: string;
+}
+
+/**
+ * The mount: match, strip, delegate. Identical on both platforms — it touches
+ * no DOM, no `node:` module and no network of its own.
+ */
+export function routeTable(init: RouteTableInit): FetchHandler {
+  const mountPrefix = init.mountPrefix ?? "/proxy";
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const pathname = url.pathname.startsWith(mountPrefix)
+      ? url.pathname.slice(mountPrefix.length)
+      : url.pathname;
+
+    // The listing: prefixes and descriptions, never headers — a header value
+    // is a credential and every member of the mesh can read this.
+    if ((pathname === "" || pathname === "/") && request.method === "GET") {
+      const body = JSON.stringify({
+        routes: init.routes().map((r) => ({ prefix: r.prefix, upstream: r.describe })),
+      });
+      return new Response(body, { headers: { "content-type": "application/json" } });
+    }
+
+    // `matchRoute` is the PROVEN matcher, imported rather than copied: it is
+    // what enforces segment boundaries, so `/files` does not swallow
+    // `/filesystem`. It expects `{prefix, upstream, headers}`-shaped records,
+    // so the route is presented to it with `upstream` as its description.
+    const shaped = init.routes().map((r) => ({
+      prefix: r.prefix,
+      upstream: r.describe,
+      headers: {},
+    }));
+    const found = matchRoute(shaped, pathname);
+    if (found == null) {
+      return new Response(`no route for ${pathname}`, {
+        status: 404,
+        headers: { [MARKER]: "no-route" },
+      });
+    }
+
+    const route = init.routes().find((r) => r.prefix === found.route.prefix);
+    if (route == null) {
+      return new Response(`no route for ${pathname}`, {
+        status: 404,
+        headers: { [MARKER]: "no-route" },
+      });
+    }
+
+    // The rest of the path, plus the query, as a request the upstream sees.
+    // The URL's origin is carried over so a handler upstream still gets a
+    // well-formed absolute URL; a `urlUpstream` replaces it entirely.
+    const rewritten = new URL(`${found.rest || "/"}${url.search}`, url.origin);
+    const forwarded = new Request(rewritten, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      ...(request.body != null ? { duplex: "half" as const } : {}),
+      signal: request.signal,
+    });
+
+    return route.upstream(forwarded);
+  };
+}
+
+export interface UrlUpstreamInit {
+  /**
+   * Request headers to drop before re-issuing upstream, beyond the ones this
+   * proxy always drops (`authorization` and the hop-by-hop set).
+   *
+   * For anything the surrounding system treats as proven identity and that a
+   * third-party origin has no business seeing.
+   */
+  stripRequestHeaders?: readonly string[];
+
+  /** Origin (and optional base path) every request is re-issued against. */
+  base: string;
+  /** Static headers for this destination, applied after the caller's. */
+  headers?: Record<string, string>;
+  /** A credential for this destination, read per request so it need not be held in the route. */
+  credential?: () => Record<string, string> | undefined;
+  /** Injected by tests; defaults to the platform's. */
+  fetchImpl?: typeof fetch;
+  /** `Via` value; omitted, no `Via` is added. */
+  via?: string;
+}
+
+/**
+ * Re-issue the request to a URL — the "reverse proxy" half.
+ *
+ * THE HYGIENE IS HERE AND NOT IN THE TABLE, because it applies only when a
+ * request LEAVES the mesh. Calling a local handler must not strip the caller's
+ * identity; re-issuing to a third party must.
+ */
+export function urlUpstream(init: UrlUpstreamInit): Upstream {
+  const doFetch = init.fetchImpl ?? globalThis.fetch;
+
+  return async (request: Request): Promise<Response> => {
+    const from = new URL(request.url);
+    const target = new URL(`.${from.pathname}${from.search}`, ensureSlash(init.base));
+
+    const headers = new Headers(request.headers);
+    // The mesh's own credential is consumed by this hop, the way
+    // `Proxy-Authorization` is consumed by the proxy it names. Forwarding it
+    // handed mesh tokens to third parties (an upstream echoed one back) and
+    // turned every call into a preflighted one.
+    headers.delete("authorization");
+    // WHATEVER ELSE THE CALLER'S SYSTEM TREATS AS IDENTITY. This proxy knows
+    // nothing about the caller's trust model, so the names are configuration:
+    // httpeers passes its proven-peer header here, because re-issuing to a
+    // third party must not tell an outside origin which mesh peer called.
+    // Without this a caller would have to post-process the request, by which
+    // point it has already gone.
+    for (const name of init.stripRequestHeaders ?? []) headers.delete(name);
+    // Hop-by-hop headers (RFC 9110 §7.6.1) are not the upstream's business.
+    for (const hop of HOP_BY_HOP) headers.delete(hop);
+    if (init.via != null) headers.set("via", init.via);
+    // Operator configuration last, so it wins over anything a caller sent.
+    for (const [name, value] of Object.entries(init.headers ?? {})) headers.set(name, value);
+    for (const [name, value] of Object.entries(init.credential?.() ?? {})) headers.set(name, value);
+
+    const outbound = new Request(target, {
+      method: request.method,
+      headers,
+      body: request.body,
+      ...(request.body != null ? { duplex: "half" as const } : {}),
+      signal: request.signal,
+      redirect: "manual",
+    });
+
+    try {
+      const upstream = await doFetch(outbound);
+      // AN OPAQUE REDIRECT HAS STATUS 0, and `new Response(body, {status: 0})`
+      // throws — which is how the shipping proxy reports a redirecting
+      // upstream as `502 upstream-unreachable`. Reported as what it is.
+      if (upstream.type === "opaqueredirect" || upstream.status === 0) {
+        return new Response("upstream redirected; the proxy does not follow redirects", {
+          status: 502,
+          headers: { [MARKER]: "upstream-redirect" },
+        });
+      }
+      return new Response(upstream.body, {
+        status: upstream.status,
+        statusText: upstream.statusText,
+        headers: upstream.headers,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return new Response(
+        `upstream ${init.base} could not be reached: ${message}\n` +
+          "If the upstream is up, it most likely does not permit cross-origin requests.",
+        { status: 502, headers: { [MARKER]: "upstream-unreachable" } },
+      );
+    }
+  };
+}
+
+const HOP_BY_HOP = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+];
+
+function ensureSlash(base: string): string {
+  return base.endsWith("/") ? base : `${base}/`;
+}

package/src/routes.ts

@@ -0,0 +1,48 @@
+/**
+ * Which configured upstream a mesh-side path belongs to.
+ *
+ * THE UPSTREAM IS NEVER TAKEN FROM THE REQUEST. `cors-anywhere` puts the
+ * destination in the URL (`/https://example.com/`), which is why its public
+ * instance is permanently abused. Here a caller selects among upstreams the
+ * operator configured and can reach nothing else, so this module must never
+ * gain a wildcard or passthrough mode.
+ */
+
+export interface ProxyRoute {
+  /** Mesh-side prefix, leading slash, no trailing slash: `/openai`. */
+  prefix: string;
+  /** Upstream base: `https://api.openai.com/v1`. */
+  upstream: string;
+  /** Applied to every forwarded request, last, so operator config wins. */
+  headers: Record<string, string>;
+}
+
+/**
+ * The route owning `pathname`, and what follows its prefix.
+ *
+ * LONGEST PREFIX WINS, so `/openai/admin` can go somewhere other than
+ * `/openai`, and the answer does not depend on the order routes were added --
+ * an ordering dependency would make the UI's list order silently meaningful.
+ */
+export function matchRoute(
+  routes: readonly ProxyRoute[],
+  pathname: string,
+): { route: ProxyRoute; rest: string } | null {
+  let best: { route: ProxyRoute; rest: string } | null = null;
+  for (const route of routes) {
+    if (!pathname.startsWith(route.prefix)) continue;
+    const rest = pathname.slice(route.prefix.length);
+    // A prefix is a SEGMENT, not a string prefix: `/open` must not swallow
+    // `/openai/models`, or adding a short route would silently capture longer
+    // unrelated ones.
+    if (rest !== "" && !rest.startsWith("/")) continue;
+    if (best == null || route.prefix.length > best.route.prefix.length) best = { route, rest };
+  }
+  return best;
+}
+
+/** The absolute upstream URL for a matched route, carrying `search` unchanged. */
+export function upstreamUrl(route: ProxyRoute, rest: string, search: string): string {
+  const base = route.upstream.endsWith("/") ? route.upstream.slice(0, -1) : route.upstream;
+  return `${base}${rest}${search}`;
+}

package/src/store.ts

@@ -0,0 +1,111 @@
+/**
+ * Persisting routes — and refusing, mechanically, to persist a secret.
+ *
+ * THE RULE THIS FILE EXISTS TO ENFORCE. A route may carry a credential: an
+ * upstream API key, a bearer token, whatever the operator typed into the proxy
+ * page. The header's NAME is configuration and is saved. The header's VALUE is
+ * a secret, lives in memory, and is merged per request.
+ *
+ * That distinction cannot be left to callers. An earlier shape of this API
+ * stored a whole `Route`, and building the proxy page on it would have written
+ * bearer keys into `localStorage` — where they survive a reload, a shared
+ * machine, and anyone who opens devtools. So `StoredRoute` has no field a
+ * value could go in, and `save()` throws rather than silently dropping one:
+ * silently dropping would mean a route that worked before a reload and
+ * mysteriously 401s after it.
+ *
+ * `load()` RETURNS `undefined` FOR "NEVER WRITTEN", which is not the same as
+ * an empty array and the difference is visible to a user. A first visit should
+ * seed the demo routes; a visit after the operator deleted all of them should
+ * not bring them back. One value distinguishes the two.
+ */
+
+import type { Route, Upstream } from "./proxy.js";
+
+/**
+ * A route as it is persisted: the upstream as a URL, and the header NAME only.
+ *
+ * There is deliberately no field for a header value. The type is the
+ * enforcement; `save()`'s check is the belt to its braces.
+ */
+export interface StoredRoute {
+  prefix: string;
+  /** The upstream base URL. A route whose upstream is a live handler cannot be stored. */
+  upstream: string;
+  describe: string;
+  /** The name of the header carrying a credential, or `null` for none. */
+  secretHeader: string | null;
+}
+
+export interface RouteStore {
+  /** `undefined` means NEVER WRITTEN — distinct from `[]`, which means "the operator deleted them all". */
+  load(): Promise<StoredRoute[] | undefined>;
+  /** Throws if any route carries a credential VALUE. */
+  save(routes: StoredRoute[]): Promise<void>;
+}
+
+/** Thrown when a caller tries to persist something that looks like a secret. */
+export class SecretNotPersistableError extends Error {
+  constructor(public readonly prefix: string) {
+    super(
+      `webrun-http-proxy: refusing to persist a credential value for route ${JSON.stringify(prefix)}. ` +
+        "Store the header NAME (`secretHeader`) and keep the value in memory — a persisted " +
+        "credential survives a reload, a shared machine, and devtools.",
+    );
+    this.name = "SecretNotPersistableError";
+  }
+}
+
+/**
+ * The check `save()` implementations run. Exported so an adapter written
+ * elsewhere enforces the same rule rather than reimplementing its own idea of
+ * what a secret looks like.
+ */
+export function assertNoSecrets(routes: readonly StoredRoute[]): void {
+  for (const route of routes) {
+    const carrier = route as unknown as Record<string, unknown>;
+    // Any shape a value could arrive in. A caller passing a whole `Route`
+    // through by mistake is the case this catches, and it is the likely one.
+    if (
+      typeof carrier.secret === "string" ||
+      typeof carrier.secretValue === "string" ||
+      (carrier.headers != null && typeof carrier.headers === "object")
+    ) {
+      throw new SecretNotPersistableError(route.prefix);
+    }
+  }
+}
+
+/** Keep only the persistable fields, dropping anything else a caller passed. */
+export function toStoredRoute(route: {
+  prefix: string;
+  upstream: string;
+  describe: string;
+  secretHeader?: string | null;
+}): StoredRoute {
+  return {
+    prefix: route.prefix,
+    upstream: route.upstream,
+    describe: route.describe,
+    secretHeader: route.secretHeader ?? null,
+  };
+}
+
+export interface RehydrateInit {
+  /** Build the live upstream for a stored route. Where the secret VALUE is re-supplied. */
+  upstreamFor: (stored: StoredRoute) => Upstream;
+}
+
+/**
+ * Stored routes back into live ones.
+ *
+ * The secret re-enters here, from wherever the caller keeps it in memory —
+ * which is the only place it ever was.
+ */
+export function rehydrate(stored: readonly StoredRoute[], init: RehydrateInit): Route[] {
+  return stored.map((route) => ({
+    prefix: route.prefix,
+    describe: route.describe,
+    upstream: init.upstreamFor(route),
+  }));
+}