@nifrajs/proxy 2.14.1 → 3.1.0

package/dist/index.d.ts

@@ -10,7 +10,8 @@
  * 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
+ * unless `forwardClientIp: true`, in which case only the observed caller IP is emitted by default.
+ * An inbound chain is preserved only with the explicit `trustForwardedFor: true` declaration. 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.
  */
@@ -20,6 +21,84 @@ export interface ProxyContext {
     readonly clientIp?: string | undefined;
     readonly signal?: AbortSignal | undefined;
 }
+/** The forwarded request, after hygiene, as handed to a {@link ProxyTransport}. */
+export interface ProxyUpstreamRequest {
+    readonly method: string;
+    /** Already sanitised: hop-by-hop, Connection-nominated, `Proxy-*`, `host`, and (unless opted in)
+     *  forwarding headers are gone, and static `headers` have been applied. Send them as given. */
+    readonly headers: Headers;
+    readonly body: ReadableStream<Uint8Array> | null;
+    /** Aborts on the deadline or on caller disconnect. A transport MUST honour it. */
+    readonly signal: AbortSignal;
+}
+/** What a {@link ProxyTransport} returns. Header hygiene on the way back is the proxy's job. */
+export interface ProxyUpstreamResponse {
+    readonly status: number;
+    /** Empty string is fine - HTTP/2 has no reason phrase, and nothing downstream depends on it. */
+    readonly statusText: string;
+    readonly headers: Headers;
+    readonly body: ReadableStream<Uint8Array> | null;
+    /**
+     * Whether `body` is still exactly the bytes the upstream sent, `Content-Encoding` intact. `fetch`
+     * transparently decodes a compressed response, so its body is identity and the stored
+     * `content-encoding`/`content-length` no longer describe it - both are dropped on relay (the
+     * default when this is omitted). A transport that does NOT decode (undici's `request` does not)
+     * MUST set this `true` so the encoding and length are relayed instead, letting the client decode
+     * the bytes it actually receives. Getting this wrong ships a gzip body labelled identity.
+     */
+    readonly bodyEncoded?: boolean;
+}
+/**
+ * How the forwarded request reaches the upstream. Defaults to the undici transport on Node when
+ * `undici` is installed (substantially faster there), and to `fetch` everywhere else.
+ *
+ * A transport is a security boundary, and swapping it moves three of this package's guarantees into
+ * your implementation. It MUST dial exactly `target` and nothing else, MUST NOT follow redirects
+ * (relay the 3xx as-is), and MUST leave TLS verification on. It MUST NOT add, drop, or rewrite the
+ * headers it is handed - they have already been sanitised, and re-adding `host` or a forwarding
+ * header undoes that work. If it does not decode `Content-Encoding`, it MUST set
+ * {@link ProxyUpstreamResponse.bodyEncoded} so the encoding is relayed rather than stripped.
+ *
+ * `@nifrajs/proxy/undici` ships the one selected by default on Node.
+ */
+export type ProxyTransport = (target: URL, request: ProxyUpstreamRequest) => Promise<ProxyUpstreamResponse>;
+/** Structural request view used only by the Node-native mount seam. The raw body stays the
+ * IncomingMessage; no Web Request, Headers, or Web stream is created before the transport sees it. */
+export interface NodeNativeProxyRequest {
+    readonly method: string;
+    /** Absolute URL assembled by the Node adapter from its trusted protocol/host policy. */
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    readonly raw: unknown;
+}
+/** Structural response view used by the Node-native mount seam. */
+export interface NodeNativeProxyResponse {
+    readonly destroyed?: boolean;
+    readonly writableEnded?: boolean;
+    readonly writable?: boolean;
+    readonly headersSent?: boolean;
+    setHeader(name: string, value: string | readonly string[]): void;
+    writeHead(status: number): void;
+    end(body?: string | Uint8Array): void;
+    once(event: string, listener: (...args: unknown[]) => void): unknown;
+    removeListener(event: string, listener: (...args: unknown[]) => void): unknown;
+    destroy(error?: unknown): unknown;
+}
+export interface NativeProxyTransportRequest {
+    readonly method: string;
+    /** Flat name/value pairs already sanitized by the proxy. */
+    readonly headers: readonly string[];
+    readonly body: unknown;
+    readonly signal: AbortSignal;
+    readonly headersTimeout: number;
+}
+export interface NativeProxyUpstreamResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    readonly body: unknown;
+    dump(): Promise<void>;
+}
+export type NativeProxyTransport = (target: URL, request: NativeProxyTransportRequest) => Promise<NativeProxyUpstreamResponse>;
 export interface ProxyOptions {
     /**
      * The upstream to forward every request to, as a **bare origin** (`https://api.internal:8443`).
@@ -32,19 +111,62 @@ export interface ProxyOptions {
     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.
+     * are stripped, so a client-forged chain never reaches the upstream. When true, the observed caller
+     * IP replaces inbound `X-Forwarded-For` by default (pass a `ProxyContext` so `c.clientIp` - already
+     * filtered by the app's trust declaration - is the value emitted). 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`. */
+    /**
+     * Preserve an inbound `X-Forwarded-For` chain before appending the observed caller IP. Set this only
+     * when a proxy you operate has already stripped and rebuilt the inbound chain; otherwise a directly
+     * reachable caller can forge the leading entries. Requires `forwardClientIp: true`.
+     */
+    readonly trustForwardedFor?: boolean;
+    /**
+     * Deadline in milliseconds for the upstream to *begin* answering. Default `30_000`; expiry
+     * answers `504`. It covers up to the response headers, which is the only window in which a `504`
+     * is still sendable - once the status has been relayed the exchange cannot be turned into one. A
+     * body that starts and then stalls is the transport's timeout to enforce; both built-in transports
+     * cap the idle gap between chunks at 30s (undici's `bodyTimeout`, and an equivalent per-chunk timer
+     * on the portable one) and error the relayed stream past it. A custom transport owes the same
+     * bound. Caller disconnect still tears the upstream down at any point.
+     */
     readonly timeoutMs?: number;
     /** Static headers to set on every forwarded request (after hygiene, so they always win). */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * How to reach the upstream. Omit to use the default: the undici transport on Node when `undici`
+     * is installed (the fast path there, resolved lazily so the base package stays dependency-free),
+     * `fetch` on every other runtime and when `undici` is absent. See {@link ProxyTransport} - a
+     * transport carries security obligations. Pass one explicitly to pin the choice or tune it (e.g.
+     * `undiciTransport({ dispatcher })`).
+     */
+    readonly transport?: ProxyTransport;
 }
 /** Forward a request (or a nifra context) to the configured upstream. */
 export type ProxyHandler = (input: Request | ProxyContext) => Promise<Response>;
+/** Options for {@link fetchTransport}. */
+export interface FetchTransportOptions {
+    /**
+     * Milliseconds of silence tolerated *within* the response body before the relayed stream is
+     * errored and the upstream read cancelled. `createProxy`'s own `timeoutMs` only covers the wait
+     * for response headers - after the status is relayed a `504` is no longer sendable - so this is
+     * what protects against a body that starts and then stalls. Default `30_000` (undici's
+     * `bodyTimeout` default, so the choice of transport does not change the bound); `0` disables it.
+     */
+    readonly bodyTimeoutMs?: number;
+}
+/**
+ * Create the portable `fetch`-backed {@link ProxyTransport} - the default off Node, and the fallback
+ * everywhere the undici transport cannot be used. `redirect: "manual"` is not a preference: following
+ * an upstream redirect would let the upstream choose the proxy's next destination, so it is pinned
+ * here and a 3xx is relayed to the caller untouched.
+ *
+ * Pass it explicitly only to tune {@link FetchTransportOptions.bodyTimeoutMs} or to pin the choice
+ * on Node; leaving `transport` unset picks the right one per runtime.
+ */
+export declare function fetchTransport(options?: FetchTransportOptions): ProxyTransport;
 /**
  * Create a proxy handler bound to one upstream origin.
  *

package/dist/index.d.ts.map

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