@nifrajs/proxy 2.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+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,38 @@
+# @nifrajs/proxy
+
+Reverse proxy for nifra - stream requests to one fixed upstream origin with hop-by-hop hygiene, SSRF-proof by construction. Dependency-free.
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+## Install
+
+```sh
+bun add @nifrajs/proxy
+```
+
+## Use
+
+```ts
+import { server } from "@nifrajs/core"
+import { createProxy } from "@nifrajs/proxy"
+
+const upstream = createProxy({ upstream: "http://127.0.0.1:8081" })
+const app = server().mountFetch("/api", upstream, { stripPrefix: true })
+```
+
+The upstream is a **bare origin** fixed at construction - the forwarded URL is built by mutating a clone of that origin, never by resolving request-derived strings, so no request input can change which host is dialed. Hop-by-hop and `Connection`-nominated headers are stripped in both directions, forwarding metadata (`X-Forwarded-*`) is dropped unless `forwardClientIp: true`, upstream redirects are never followed, and TLS verification has no off switch. Unreachable upstreams answer a flat `502`; the deadline (`timeoutMs`, default 30s) answers `504`.
+
+## Docs
+
+- Reference: <https://nifra.dev/docs>
+- AI-readable: <https://nifra.dev/llms.txt>
+
+MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Reverse proxy to ONE fixed upstream origin, secure by construction.
+ *
+ * The upstream is a bare origin declared at construction; the forwarded URL is built by *mutating a
+ * clone of that origin's path and query*, never by URL-resolving request-derived strings - so no
+ * request input (protocol-relative `//host` paths included) can change which host is dialed. SSRF
+ * through this proxy is unrepresentable, not filtered.
+ *
+ * Hop-by-hop hygiene runs in BOTH directions: the RFC 9110 hop-by-hop set, every header nominated
+ * by a `Connection` header, and `Proxy-*` headers are dropped from the forwarded request and from
+ * the relayed response (the Connection-nominated leak is the @fastify/http-proxy CVE-2026-33805 /
+ * Hono proxy CVE-2026-71849 class). Forwarding metadata (`Forwarded`, `X-Forwarded-*`) is stripped
+ * unless `forwardClientIp: true`, in which case the caller chain is appended truthfully. Upstream
+ * redirects are never followed (`redirect: "manual"`) - following one would let the upstream steer
+ * the proxy anywhere. TLS verification is always on; there is no knob to disable it.
+ */
+/** Structural slice of a nifra `Context` the proxy reads - a plain `Request` works too. */
+export interface ProxyContext {
+    readonly req: Request;
+    readonly clientIp?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface ProxyOptions {
+    /**
+     * The upstream to forward every request to, as a **bare origin** (`https://api.internal:8443`).
+     * A path, query, fragment, or credentials in the URL throws at construction; only `http:` and
+     * `https:` are accepted. The forwarded URL is this origin + the incoming path and query.
+     */
+    readonly upstream: string;
+    /** Mount prefix to remove from the incoming path before forwarding (`/api` + request
+     * `/api/users` → upstream `/users`). A path outside the prefix is forwarded unchanged. */
+    readonly stripPrefix?: string;
+    /**
+     * Forward caller metadata upstream. Default **false**: `Forwarded` and `X-Forwarded-*` headers
+     * are stripped, so a client-forged chain never reaches the upstream. When true, the inbound
+     * `X-Forwarded-For` is kept with the observed caller IP appended (pass a `ProxyContext` so
+     * `c.clientIp` - already filtered by the app's trust declaration - is what gets appended). With a
+     * bare `Request`, forwarding metadata is suppressed rather than passed through.
+     */
+    readonly forwardClientIp?: boolean;
+    /** Upstream response deadline in milliseconds. Default `30_000`; expiry answers `504`. */
+    readonly timeoutMs?: number;
+    /** Static headers to set on every forwarded request (after hygiene, so they always win). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Forward a request (or a nifra context) to the configured upstream. */
+export type ProxyHandler = (input: Request | ProxyContext) => Promise<Response>;
+/**
+ * Create a proxy handler bound to one upstream origin.
+ *
+ * ```ts
+ * const upstream = createProxy({ upstream: "http://127.0.0.1:8081" })
+ * app.mountFetch("/api", upstream, { stripPrefix: true })
+ * ```
+ *
+ * Streams both directions, preserves method/path/query/status, strips hop-by-hop and
+ * Connection-nominated headers both ways, never follows upstream redirects, and answers flat
+ * errors: `502 bad_gateway` when the upstream is unreachable, `504 gateway_timeout` on deadline.
+ * WebSocket upgrade is not proxied.
+ */
+export declare function createProxy(options: ProxyOptions): ProxyHandler;
+//# 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;;;;;;;;;;;;;;;GAeG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;8FAC0F;IAC1F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACpD;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AA0F/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAkF/D"}

package/dist/index.js

@@ -0,0 +1,191 @@
+/**
+ * Reverse proxy to ONE fixed upstream origin, secure by construction.
+ *
+ * The upstream is a bare origin declared at construction; the forwarded URL is built by *mutating a
+ * clone of that origin's path and query*, never by URL-resolving request-derived strings - so no
+ * request input (protocol-relative `//host` paths included) can change which host is dialed. SSRF
+ * through this proxy is unrepresentable, not filtered.
+ *
+ * Hop-by-hop hygiene runs in BOTH directions: the RFC 9110 hop-by-hop set, every header nominated
+ * by a `Connection` header, and `Proxy-*` headers are dropped from the forwarded request and from
+ * the relayed response (the Connection-nominated leak is the @fastify/http-proxy CVE-2026-33805 /
+ * Hono proxy CVE-2026-71849 class). Forwarding metadata (`Forwarded`, `X-Forwarded-*`) is stripped
+ * unless `forwardClientIp: true`, in which case the caller chain is appended truthfully. Upstream
+ * redirects are never followed (`redirect: "manual"`) - following one would let the upstream steer
+ * the proxy anywhere. TLS verification is always on; there is no knob to disable it.
+ */
+/** RFC 9110 hop-by-hop headers: they describe one connection, never end-to-end semantics. */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+/** Forwarding metadata is an explicit opt-in (`forwardClientIp`), never a passthrough. */
+const FORWARDING = new Set([
+    "forwarded",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-proto",
+]);
+const EMPTY = new Set();
+/** Header names nominated hop-by-hop by a `Connection` header (lowercased). */
+function connectionNominated(headers) {
+    const raw = headers.get("connection");
+    if (raw === null)
+        return EMPTY;
+    const out = new Set();
+    for (const token of raw.split(",")) {
+        const name = token.trim().toLowerCase();
+        if (name !== "")
+            out.add(name);
+    }
+    return out;
+}
+function dropHeader(name, nominated) {
+    return HOP_BY_HOP.has(name) || nominated.has(name) || name.startsWith("proxy-");
+}
+const flatError = (status, error) => new Response(JSON.stringify({ ok: false, error }), {
+    status,
+    headers: { "content-type": "application/json" },
+});
+function upstreamRequestHeaders(req, clientIp, options) {
+    const nominated = connectionNominated(req.headers);
+    const out = new Headers();
+    for (const [name, value] of req.headers) {
+        // `host` names the proxy, not the upstream - fetch derives the right one from the target URL.
+        if (name === "host" || dropHeader(name, nominated))
+            continue;
+        if (FORWARDING.has(name))
+            continue;
+        out.append(name, value);
+    }
+    if (options.forwardClientIp === true && clientIp !== undefined) {
+        const prior = req.headers.get("x-forwarded-for");
+        const chain = prior !== null ? `${prior}, ${clientIp}` : clientIp;
+        if (chain !== undefined)
+            out.set("x-forwarded-for", chain);
+        out.set("x-forwarded-proto", new URL(req.url).protocol.slice(0, -1));
+        const host = req.headers.get("host");
+        if (host !== null)
+            out.set("x-forwarded-host", host);
+    }
+    if (options.headers !== undefined) {
+        for (const [name, value] of Object.entries(options.headers))
+            out.set(name, value);
+    }
+    return out;
+}
+function relayedResponseHeaders(upstream) {
+    const nominated = connectionNominated(upstream.headers);
+    const out = new Headers();
+    for (const [name, value] of upstream.headers) {
+        if (dropHeader(name, nominated))
+            continue;
+        // fetch() already decoded the body per Content-Encoding, so the stored encoding and length no
+        // longer describe the bytes being relayed. (Re-compression is the compression() middleware's job.)
+        if (name === "content-encoding" || name === "content-length")
+            continue;
+        // Re-added below via getSetCookie() so multiple cookies survive on every runtime.
+        if (name === "set-cookie")
+            continue;
+        out.append(name, value);
+    }
+    for (const cookie of upstream.headers.getSetCookie())
+        out.append("set-cookie", cookie);
+    return out;
+}
+/**
+ * Create a proxy handler bound to one upstream origin.
+ *
+ * ```ts
+ * const upstream = createProxy({ upstream: "http://127.0.0.1:8081" })
+ * app.mountFetch("/api", upstream, { stripPrefix: true })
+ * ```
+ *
+ * Streams both directions, preserves method/path/query/status, strips hop-by-hop and
+ * Connection-nominated headers both ways, never follows upstream redirects, and answers flat
+ * errors: `502 bad_gateway` when the upstream is unreachable, `504 gateway_timeout` on deadline.
+ * WebSocket upgrade is not proxied.
+ */
+export function createProxy(options) {
+    const base = new URL(options.upstream);
+    if (base.protocol !== "http:" && base.protocol !== "https:") {
+        throw new Error(`[nifra/proxy] upstream must be http(s), got ${base.protocol}`);
+    }
+    if (base.pathname !== "/" ||
+        base.search !== "" ||
+        base.hash !== "" ||
+        base.username !== "" ||
+        base.password !== "") {
+        throw new Error("[nifra/proxy] upstream must be a bare origin (no path, query, fragment, or credentials)");
+    }
+    const stripPrefix = options.stripPrefix;
+    if (stripPrefix !== undefined && (!stripPrefix.startsWith("/") || stripPrefix.endsWith("/"))) {
+        throw new Error('[nifra/proxy] stripPrefix must start with "/" and not end with one');
+    }
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("[nifra/proxy] timeoutMs must be a positive number");
+    }
+    for (const name of Object.keys(options.headers ?? {})) {
+        const normalized = name.toLowerCase();
+        if (normalized === "host" ||
+            HOP_BY_HOP.has(normalized) ||
+            normalized.startsWith("proxy-") ||
+            FORWARDING.has(normalized)) {
+            throw new TypeError(`[nifra/proxy] static header is not allowed: ${name}`);
+        }
+    }
+    return async (input) => {
+        const req = input instanceof Request ? input : input.req;
+        const clientIp = input instanceof Request ? undefined : input.clientIp;
+        const callerSignal = input instanceof Request ? input.signal : (input.signal ?? input.req.signal);
+        const incoming = new URL(req.url);
+        let path = incoming.pathname;
+        if (stripPrefix !== undefined && (path === stripPrefix || path.startsWith(`${stripPrefix}/`))) {
+            const rest = path.slice(stripPrefix.length);
+            path = rest === "" || !rest.startsWith("/") ? `/${rest}` : rest;
+        }
+        // Mutating a clone of the configured origin - never URL-resolving a request-derived string -
+        // means no path (e.g. `//evil.example/x`) can change the host being dialed.
+        const target = new URL(base);
+        target.pathname = path;
+        target.search = incoming.search;
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = callerSignal !== undefined ? AbortSignal.any([timeout, callerSignal]) : timeout;
+        const body = req.method === "GET" || req.method === "HEAD" ? undefined : req.body;
+        const init = {
+            method: req.method,
+            headers: upstreamRequestHeaders(req, clientIp, options),
+            redirect: "manual",
+            signal,
+        };
+        if (body !== null && body !== undefined) {
+            init.body = body;
+            init.duplex = "half";
+        }
+        let upstream;
+        try {
+            upstream = await fetch(target, init);
+        }
+        catch (error) {
+            if (timeout.aborted)
+                return flatError(504, "gateway_timeout");
+            if (callerSignal?.aborted === true)
+                throw error;
+            return flatError(502, "bad_gateway");
+        }
+        return new Response(upstream.body, {
+            status: upstream.status,
+            statusText: upstream.statusText,
+            headers: relayedResponseHeaders(upstream),
+        });
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nifrajs/proxy",
+  "version": "2.12.0",
+  "description": "Reverse proxy for nifra - stream requests to one fixed upstream origin with hop-by-hop hygiene, SSRF-proof by construction. Dependency-free.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "proxy",
+    "reverse-proxy",
+    "http-proxy",
+    "streaming",
+    "upstream"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/proxy"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,235 @@
+/**
+ * Reverse proxy to ONE fixed upstream origin, secure by construction.
+ *
+ * The upstream is a bare origin declared at construction; the forwarded URL is built by *mutating a
+ * clone of that origin's path and query*, never by URL-resolving request-derived strings - so no
+ * request input (protocol-relative `//host` paths included) can change which host is dialed. SSRF
+ * through this proxy is unrepresentable, not filtered.
+ *
+ * Hop-by-hop hygiene runs in BOTH directions: the RFC 9110 hop-by-hop set, every header nominated
+ * by a `Connection` header, and `Proxy-*` headers are dropped from the forwarded request and from
+ * the relayed response (the Connection-nominated leak is the @fastify/http-proxy CVE-2026-33805 /
+ * Hono proxy CVE-2026-71849 class). Forwarding metadata (`Forwarded`, `X-Forwarded-*`) is stripped
+ * unless `forwardClientIp: true`, in which case the caller chain is appended truthfully. Upstream
+ * redirects are never followed (`redirect: "manual"`) - following one would let the upstream steer
+ * the proxy anywhere. TLS verification is always on; there is no knob to disable it.
+ */
+
+/** Structural slice of a nifra `Context` the proxy reads - a plain `Request` works too. */
+export interface ProxyContext {
+  readonly req: Request
+  readonly clientIp?: string | undefined
+  readonly signal?: AbortSignal | undefined
+}
+
+export interface ProxyOptions {
+  /**
+   * The upstream to forward every request to, as a **bare origin** (`https://api.internal:8443`).
+   * A path, query, fragment, or credentials in the URL throws at construction; only `http:` and
+   * `https:` are accepted. The forwarded URL is this origin + the incoming path and query.
+   */
+  readonly upstream: string
+  /** Mount prefix to remove from the incoming path before forwarding (`/api` + request
+   * `/api/users` → upstream `/users`). A path outside the prefix is forwarded unchanged. */
+  readonly stripPrefix?: string
+  /**
+   * Forward caller metadata upstream. Default **false**: `Forwarded` and `X-Forwarded-*` headers
+   * are stripped, so a client-forged chain never reaches the upstream. When true, the inbound
+   * `X-Forwarded-For` is kept with the observed caller IP appended (pass a `ProxyContext` so
+   * `c.clientIp` - already filtered by the app's trust declaration - is what gets appended). With a
+   * bare `Request`, forwarding metadata is suppressed rather than passed through.
+   */
+  readonly forwardClientIp?: boolean
+  /** Upstream response deadline in milliseconds. Default `30_000`; expiry answers `504`. */
+  readonly timeoutMs?: number
+  /** Static headers to set on every forwarded request (after hygiene, so they always win). */
+  readonly headers?: Readonly<Record<string, string>>
+}
+
+/** Forward a request (or a nifra context) to the configured upstream. */
+export type ProxyHandler = (input: Request | ProxyContext) => Promise<Response>
+
+/** RFC 9110 hop-by-hop headers: they describe one connection, never end-to-end semantics. */
+const HOP_BY_HOP: ReadonlySet<string> = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+])
+
+/** Forwarding metadata is an explicit opt-in (`forwardClientIp`), never a passthrough. */
+const FORWARDING: ReadonlySet<string> = new Set([
+  "forwarded",
+  "x-forwarded-for",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+])
+
+const EMPTY: ReadonlySet<string> = new Set()
+
+/** Header names nominated hop-by-hop by a `Connection` header (lowercased). */
+function connectionNominated(headers: Headers): ReadonlySet<string> {
+  const raw = headers.get("connection")
+  if (raw === null) return EMPTY
+  const out = new Set<string>()
+  for (const token of raw.split(",")) {
+    const name = token.trim().toLowerCase()
+    if (name !== "") out.add(name)
+  }
+  return out
+}
+
+function dropHeader(name: string, nominated: ReadonlySet<string>): boolean {
+  return HOP_BY_HOP.has(name) || nominated.has(name) || name.startsWith("proxy-")
+}
+
+const flatError = (status: number, error: string): Response =>
+  new Response(JSON.stringify({ ok: false, error }), {
+    status,
+    headers: { "content-type": "application/json" },
+  })
+
+function upstreamRequestHeaders(
+  req: Request,
+  clientIp: string | undefined,
+  options: ProxyOptions,
+): Headers {
+  const nominated = connectionNominated(req.headers)
+  const out = new Headers()
+  for (const [name, value] of req.headers) {
+    // `host` names the proxy, not the upstream - fetch derives the right one from the target URL.
+    if (name === "host" || dropHeader(name, nominated)) continue
+    if (FORWARDING.has(name)) continue
+    out.append(name, value)
+  }
+  if (options.forwardClientIp === true && clientIp !== undefined) {
+    const prior = req.headers.get("x-forwarded-for")
+    const chain = prior !== null ? `${prior}, ${clientIp}` : clientIp
+    if (chain !== undefined) out.set("x-forwarded-for", chain)
+    out.set("x-forwarded-proto", new URL(req.url).protocol.slice(0, -1))
+    const host = req.headers.get("host")
+    if (host !== null) out.set("x-forwarded-host", host)
+  }
+  if (options.headers !== undefined) {
+    for (const [name, value] of Object.entries(options.headers)) out.set(name, value)
+  }
+  return out
+}
+
+function relayedResponseHeaders(upstream: Response): Headers {
+  const nominated = connectionNominated(upstream.headers)
+  const out = new Headers()
+  for (const [name, value] of upstream.headers) {
+    if (dropHeader(name, nominated)) continue
+    // fetch() already decoded the body per Content-Encoding, so the stored encoding and length no
+    // longer describe the bytes being relayed. (Re-compression is the compression() middleware's job.)
+    if (name === "content-encoding" || name === "content-length") continue
+    // Re-added below via getSetCookie() so multiple cookies survive on every runtime.
+    if (name === "set-cookie") continue
+    out.append(name, value)
+  }
+  for (const cookie of upstream.headers.getSetCookie()) out.append("set-cookie", cookie)
+  return out
+}
+
+/**
+ * Create a proxy handler bound to one upstream origin.
+ *
+ * ```ts
+ * const upstream = createProxy({ upstream: "http://127.0.0.1:8081" })
+ * app.mountFetch("/api", upstream, { stripPrefix: true })
+ * ```
+ *
+ * Streams both directions, preserves method/path/query/status, strips hop-by-hop and
+ * Connection-nominated headers both ways, never follows upstream redirects, and answers flat
+ * errors: `502 bad_gateway` when the upstream is unreachable, `504 gateway_timeout` on deadline.
+ * WebSocket upgrade is not proxied.
+ */
+export function createProxy(options: ProxyOptions): ProxyHandler {
+  const base = new URL(options.upstream)
+  if (base.protocol !== "http:" && base.protocol !== "https:") {
+    throw new Error(`[nifra/proxy] upstream must be http(s), got ${base.protocol}`)
+  }
+  if (
+    base.pathname !== "/" ||
+    base.search !== "" ||
+    base.hash !== "" ||
+    base.username !== "" ||
+    base.password !== ""
+  ) {
+    throw new Error(
+      "[nifra/proxy] upstream must be a bare origin (no path, query, fragment, or credentials)",
+    )
+  }
+  const stripPrefix = options.stripPrefix
+  if (stripPrefix !== undefined && (!stripPrefix.startsWith("/") || stripPrefix.endsWith("/"))) {
+    throw new Error('[nifra/proxy] stripPrefix must start with "/" and not end with one')
+  }
+  const timeoutMs = options.timeoutMs ?? 30_000
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("[nifra/proxy] timeoutMs must be a positive number")
+  }
+  for (const name of Object.keys(options.headers ?? {})) {
+    const normalized = name.toLowerCase()
+    if (
+      normalized === "host" ||
+      HOP_BY_HOP.has(normalized) ||
+      normalized.startsWith("proxy-") ||
+      FORWARDING.has(normalized)
+    ) {
+      throw new TypeError(`[nifra/proxy] static header is not allowed: ${name}`)
+    }
+  }
+
+  return async (input) => {
+    const req = input instanceof Request ? input : input.req
+    const clientIp = input instanceof Request ? undefined : input.clientIp
+    const callerSignal =
+      input instanceof Request ? input.signal : (input.signal ?? input.req.signal)
+
+    const incoming = new URL(req.url)
+    let path = incoming.pathname
+    if (stripPrefix !== undefined && (path === stripPrefix || path.startsWith(`${stripPrefix}/`))) {
+      const rest = path.slice(stripPrefix.length)
+      path = rest === "" || !rest.startsWith("/") ? `/${rest}` : rest
+    }
+    // Mutating a clone of the configured origin - never URL-resolving a request-derived string -
+    // means no path (e.g. `//evil.example/x`) can change the host being dialed.
+    const target = new URL(base)
+    target.pathname = path
+    target.search = incoming.search
+
+    const timeout = AbortSignal.timeout(timeoutMs)
+    const signal = callerSignal !== undefined ? AbortSignal.any([timeout, callerSignal]) : timeout
+    const body = req.method === "GET" || req.method === "HEAD" ? undefined : req.body
+    const init: RequestInit & { duplex?: "half" } = {
+      method: req.method,
+      headers: upstreamRequestHeaders(req, clientIp, options),
+      redirect: "manual",
+      signal,
+    }
+    if (body !== null && body !== undefined) {
+      init.body = body
+      init.duplex = "half"
+    }
+
+    let upstream: Response
+    try {
+      upstream = await fetch(target, init)
+    } catch (error) {
+      if (timeout.aborted) return flatError(504, "gateway_timeout")
+      if (callerSignal?.aborted === true) throw error
+      return flatError(502, "bad_gateway")
+    }
+    return new Response(upstream.body, {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: relayedResponseHeaders(upstream),
+    })
+  }
+}