@filamentjs/proxy 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Thomas
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @filamentjs/proxy
+
+A strict reverse proxy for explicitly registered FilamentJS routes and trusted,
+named HTTP upstreams. It is not an open forward proxy: clients cannot choose an
+origin, host, protocol, or arbitrary path.
+
+## Key features
+
+- Fixed named HTTP(S) upstreams and exact Filament route mappings.
+- Independently encoded path parameters and configurable query forwarding.
+- Conservative request/response header allowlists and no automatic redirects.
+- Bounded response buffering, total timeouts, generic 502/504 errors, and
+  constrained pre-response retries for idempotent methods.
+- Setup-time rejection of open-proxy inputs, route collisions, and unsafe
+  header configuration.
+
+## Quick start
+
+```sh
+npm install @filamentjs/proxy filamentjs
+```
+
+```ts
+import { createApp, type FrameworkMeta } from "filamentjs";
+import { setup } from "@filamentjs/proxy";
+
+const app = createApp<FrameworkMeta>(
+  { application: { maxRequestSize: "1MiB" } },
+  {},
+);
+setup(app, {
+  upstreams: {
+    catalog: { origin: "https://catalog.internal", basePath: "/v1" },
+  },
+  routes: [
+    {
+      method: "GET",
+      path: "/products/:id",
+      upstream: "catalog",
+      upstreamPath: "/items/:id",
+    },
+  ],
+});
+```
+
+Requires Node 24+ and the exact supported peer `filamentjs@0.6.0`.
+
+## How it works and options
+
+Named parameters are independently percent-encoded. Query fields are forwarded
+by default and can be disabled per mapping. Filament has no wildcard route, so
+every proxy path must be registered explicitly.
+
+The default request allowlist is `Accept`, `Accept-Language`, `Content-Type`,
+and `User-Agent`. Authorization and cookies require deliberate allowlisting;
+host, forwarding identity, content length, and hop-by-hop fields are always
+rejected. Responses use a small end-to-end allowlist and omit `Location` and
+`Set-Cookie` by default. Redirects are returned without being followed.
+
+Responses are buffered up to 8 MiB by default so upstream failure cannot leak a
+partial downstream response. The default total timeout is 10 seconds. Failures
+return generic 502/504 bodies and go to `onError`. Retries default to zero, are
+limited to two, and are permitted only for GET/HEAD before response bytes are
+sent. Incoming bodies are available only for the methods Filament buffers.
+
+Downstream disconnect cancellation and truly streaming proxy responses require
+additional Filament lifecycle support and are not claimed by this release.
+
+### Public API
+
+| Surface | Meaning |
+| --- | --- |
+| `setup(app, options)` | Validates mappings and registers exact proxy routes; returns registered paths. |
+| `SetupOptions` | Trusted upstream map, route list, optional fetch implementation and error hook. |
+| `Upstream` | Fixed HTTP(S) origin, optional base path, and trusted added headers. |
+| `ProxyRoute` | Method/path mapping, templates, query/header policy, timeout, size, retries, and metadata. |
+
+Proxy handlers own the response and therefore stop later routes/transformers.
+Authentication/authorization should run before a sensitive proxy route; rate
+limiting may run before or after authentication depending on whether the key is
+safe. A 502 denotes an upstream/protocol failure and 504 a timeout. No response
+bytes are committed before the bounded upstream response succeeds.
+
+## Development and demo
+
+From a source checkout:
+
+```sh
+npm test
+npm run example
+npm run demo
+```
+
+The unattended demo creates a loopback upstream, proxies a live parameterized
+request, prints the upstream-observed path, closes both servers, and exits. No
+external service is contacted. There is no pre-0.1 migration contract.
+
+## License
+
+ISC

package/dist/proxy.d.ts

@@ -0,0 +1,3 @@
+export { setup } from "./src/proxy.js";
+export type { ProxyRoute, SetupOptions, SetupResult, Upstream, } from "./src/types.js";
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,GACT,MAAM,gBAAgB,CAAC"}

package/dist/proxy.js

@@ -0,0 +1,2 @@
+export { setup } from "./src/proxy.js";
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/proxy.d.ts

@@ -0,0 +1,4 @@
+import type { Application, ContextMeta, FrameworkMeta } from "filamentjs";
+import type { SetupOptions, SetupResult } from "./types.js";
+export declare function setup<A extends FrameworkMeta, C extends ContextMeta>(app: Application<A, C>, options: SetupOptions<A>): SetupResult;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/src/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EAGd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAEV,YAAY,EACZ,WAAW,EAEZ,MAAM,YAAY,CAAC;AA+KpB,wBAAgB,KAAK,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,WAAW,EAClE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EACtB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GACvB,WAAW,CA2Hb"}

package/dist/src/proxy.js

@@ -0,0 +1,235 @@
+const installed = new WeakSet();
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+const NEVER_FORWARD_REQUEST = new Set([
+    ...HOP_BY_HOP,
+    "host",
+    "forwarded",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-proto",
+    "content-length",
+]);
+const DEFAULT_REQUEST = [
+    "accept",
+    "accept-language",
+    "content-type",
+    "user-agent",
+];
+const DEFAULT_RESPONSE = [
+    "cache-control",
+    "content-language",
+    "content-type",
+    "etag",
+    "expires",
+    "last-modified",
+    "vary",
+    "www-authenticate",
+];
+function positiveInteger(value, label, maximum = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`${label} must be a positive integer no greater than ${maximum}`);
+    return value;
+}
+function headerNames(values, response = false) {
+    const result = values.map((value) => value.toLowerCase());
+    if (result.some((value) => !/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(value) ||
+        HOP_BY_HOP.has(value) ||
+        (!response && NEVER_FORWARD_REQUEST.has(value))))
+        throw new TypeError("header allowlist contains a forbidden header");
+    return [...new Set(result)];
+}
+function trustedUpstream(value) {
+    const url = new URL(value.origin);
+    if (!/^https?:$/.test(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/")
+        throw new TypeError("upstream origin must be a credential-free HTTP(S) origin");
+    const basePath = value.basePath ?? "";
+    if (basePath !== "" &&
+        (!basePath.startsWith("/") ||
+            basePath.includes("?") ||
+            basePath.includes("#") ||
+            basePath.split("/").some((part) => part === "." || part === "..")))
+        throw new TypeError("upstream basePath is unsafe");
+    const headers = new Headers(value.headers);
+    for (const name of headers.keys())
+        if (NEVER_FORWARD_REQUEST.has(name.toLowerCase()))
+            throw new TypeError("upstream headers contain a forbidden header");
+    return { origin: url, basePath: basePath.replace(/\/$/, ""), headers };
+}
+function validateTemplate(template) {
+    if (!template.startsWith("/") ||
+        template.startsWith("//") ||
+        template.includes("?") ||
+        template.includes("#") ||
+        template.includes("\\"))
+        throw new TypeError("upstreamPath must be an absolute path template");
+    if (template.split("/").some((part) => part === "." || part === ".."))
+        throw new TypeError("upstreamPath contains traversal");
+}
+function rewrite(template, req) {
+    validateTemplate(template);
+    const result = template.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_all, name) => {
+        const value = req.params[name];
+        if (value === undefined)
+            throw new Error(`Missing route parameter ${name}`);
+        return encodeURIComponent(value);
+    });
+    if (result.split("/").some((part) => part === "." || part === ".."))
+        throw new TypeError("rewritten path contains traversal");
+    return result;
+}
+function query(req) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(req.query))
+        for (const item of Array.isArray(value) ? value : [value])
+            params.append(name, item);
+    const text = params.toString();
+    return text === "" ? "" : `?${text}`;
+}
+function requestHeaders(req, allowed, fixed) {
+    const result = new Headers(fixed);
+    for (const name of allowed) {
+        const value = req.headers.get(name);
+        if (Array.isArray(value))
+            for (const item of value)
+                result.append(name, item);
+        else if (value !== null)
+            result.set(name, value);
+    }
+    return result;
+}
+async function boundedBody(response, maximum, abort) {
+    const declared = response.headers.get("content-length");
+    if (declared !== null &&
+        (!/^\d+$/.test(declared) || Number(declared) > maximum))
+        throw new RangeError("upstream response exceeds maxResponseBytes");
+    if (response.body === null)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of response.body) {
+        length += chunk.byteLength;
+        if (length > maximum) {
+            abort.abort();
+            throw new RangeError("upstream response exceeds maxResponseBytes");
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks, length);
+}
+function retryable(method, status) {
+    return ((method === "GET" || method === "HEAD") &&
+        (status === undefined || status === 502 || status === 503 || status === 504));
+}
+export function setup(app, options) {
+    if (installed.has(app))
+        throw new Error("proxy is already installed on this application");
+    if (options.routes.length === 0)
+        throw new TypeError("at least one proxy route is required");
+    const upstreams = new Map(Object.entries(options.upstreams).map(([name, value]) => [
+        name,
+        trustedUpstream(value),
+    ]));
+    const seen = new Set();
+    const registrations = [];
+    for (const route of options.routes) {
+        const identity = `${route.method} ${route.path}`;
+        if (seen.has(identity))
+            throw new Error(`Proxy route collision: ${identity}`);
+        seen.add(identity);
+        const upstream = upstreams.get(route.upstream);
+        if (upstream === undefined)
+            throw new TypeError(`Unknown upstream: ${route.upstream}`);
+        const timeoutMs = positiveInteger(route.timeoutMs ?? 10_000, "timeoutMs", 300_000);
+        const maximum = positiveInteger(route.maxResponseBytes ?? 8 * 1024 * 1024, "maxResponseBytes");
+        const retries = route.retries ?? 0;
+        if (!Number.isSafeInteger(retries) ||
+            retries < 0 ||
+            retries > 2 ||
+            (retries > 0 && !retryable(route.method)))
+            throw new RangeError("retries must be 0..2 and require GET or HEAD");
+        const reqAllowed = headerNames(route.requestHeaders ?? DEFAULT_REQUEST);
+        const resAllowed = headerNames(route.responseHeaders ?? DEFAULT_RESPONSE, true);
+        validateTemplate(route.upstreamPath ?? route.path);
+        const handler = async function proxyRouteHandler(req, res) {
+            const path = rewrite(route.upstreamPath ?? req.path, req);
+            const target = new URL(`${upstream.basePath}${path}${route.forwardQuery === false ? "" : query(req)}`, upstream.origin);
+            if (target.origin !== upstream.origin.origin)
+                throw new Error("resolved proxy target escaped the trusted origin");
+            let lastStatus;
+            for (let attempt = 0; attempt <= retries; attempt++) {
+                const abort = new AbortController();
+                const timer = setTimeout(() => abort.abort(), timeoutMs);
+                try {
+                    const init = {
+                        method: req.method,
+                        headers: requestHeaders(req, reqAllowed, upstream.headers),
+                        redirect: "manual",
+                        signal: abort.signal,
+                    };
+                    if (req.body !== undefined)
+                        init.body = req.body;
+                    const upstreamResponse = await (options.fetch ?? fetch)(target, init);
+                    lastStatus = upstreamResponse.status;
+                    if (attempt < retries && retryable(req.method, lastStatus)) {
+                        await upstreamResponse.body?.cancel();
+                        continue;
+                    }
+                    const body = await boundedBody(upstreamResponse, maximum, abort);
+                    res.statusCode = upstreamResponse.status;
+                    for (const name of resAllowed) {
+                        const value = upstreamResponse.headers.get(name);
+                        if (value !== null)
+                            res.headers.set(name, value);
+                    }
+                    if (req.method === "HEAD" ||
+                        upstreamResponse.status === 204 ||
+                        upstreamResponse.status === 304)
+                        await res.end();
+                    else
+                        await res.send(body);
+                    return;
+                }
+                catch (error) {
+                    options.onError?.(error, {
+                        route: route.path,
+                        upstream: route.upstream,
+                        attempt,
+                    });
+                    if (attempt < retries && retryable(req.method))
+                        continue;
+                    res.statusCode =
+                        error instanceof DOMException && error.name === "AbortError"
+                            ? 504
+                            : 502;
+                    await res.send(res.statusCode === 504 ? "Gateway Timeout" : "Bad Gateway");
+                    return;
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            res.statusCode = lastStatus ?? 502;
+            await res.send("Bad Gateway");
+        };
+        registrations.push({ route, handler });
+    }
+    installed.add(app);
+    for (const { route, handler } of registrations)
+        app.route(route.method, route.path, ...(route.metadata === undefined ? [] : [route.metadata]), handler);
+    return Object.freeze({ routes: Object.freeze([...seen]) });
+}
+//# sourceMappingURL=proxy.js.map

package/dist/src/proxy.js.map

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

package/dist/src/types.d.ts

@@ -0,0 +1,35 @@
+import type { FrameworkMeta, HttpMethod } from "filamentjs";
+export interface Upstream {
+    /** Fixed trusted HTTP(S) origin. Credentials, query, and fragments are rejected. */
+    readonly origin: string;
+    readonly basePath?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface ProxyRoute<A extends FrameworkMeta = FrameworkMeta> {
+    readonly path: string;
+    readonly method: HttpMethod;
+    readonly upstream: string;
+    /** Literal path template. `:name` placeholders use encoded route parameters. */
+    readonly upstreamPath?: string;
+    readonly forwardQuery?: boolean;
+    readonly requestHeaders?: readonly string[];
+    readonly responseHeaders?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly maxResponseBytes?: number;
+    readonly retries?: number;
+    readonly metadata?: Partial<A>;
+}
+export interface SetupOptions<A extends FrameworkMeta = FrameworkMeta> {
+    readonly upstreams: Readonly<Record<string, Upstream>>;
+    readonly routes: readonly ProxyRoute<A>[];
+    readonly fetch?: typeof globalThis.fetch;
+    readonly onError?: (error: unknown, context: {
+        readonly route: string;
+        readonly upstream: string;
+        readonly attempt: number;
+    }) => void;
+}
+export interface SetupResult {
+    readonly routes: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,QAAQ;IACvB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACnE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;QACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,KACE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@filamentjs/proxy",
+  "version": "0.1.0",
+  "description": "Strict exact-route reverse proxy policy for FilamentJS",
+  "type": "module",
+  "main": "./dist/proxy.js",
+  "types": "./dist/proxy.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/proxy.d.ts",
+      "import": "./dist/proxy.js"
+    }
+  },
+  "files": [
+    "dist/proxy.js",
+    "dist/proxy.js.map",
+    "dist/proxy.d.ts",
+    "dist/proxy.d.ts.map",
+    "dist/src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node ./node_modules/typescript/bin/tsc -p tsconfig.json",
+    "link:local-filament": "node scripts/link-local-filament.mjs",
+    "test": "npm run link:local-filament && npm run build && node --test dist/test/*.test.js",
+    "example": "npm run link:local-filament && npm run build && node dist/example/example.js",
+    "demo": "npm run link:local-filament && npm run build && node dist/demo/demo.js",
+    "prepack": "npm test"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "filamentjs": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "filamentjs",
+    "reverse-proxy",
+    "gateway"
+  ],
+  "license": "ISC"
+}