@webpieces/http-client-node 0.4.698 → 0.4.700

package/src/NodeProxyClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"NodeProxyClient.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/NodeProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, optional } from 'inversify';\nimport {\n    AuthMeta,\n    ClientRegistry,\n    DestinationTrust,\n    HttpInternalServerError,\n    RecordedEndpoint,\n    RecordedError,\n    RouteMetadata,\n    Secrets,\n    SECRETS,\n    TestCaseRecorder,\n    toError,\n} from '@webpieces/core-util';\nimport { RequestContext, RequestContextHeaders, provideFrameworkTransient } from '@webpieces/core-context';\nimport { GcpOidc } from '@webpieces/gcp-identity';\nimport { ApiPrototype, ProxyClient, TranslatedFailure } from '@webpieces/http-client-core';\nimport { ClientConfig } from './ClientConfig';\n\n/**\n * The server-side {@link ProxyClient}. Everything a browser cannot do lives here: reading the\n * ambient RequestContext, minting OIDC tokens, holding shared secrets, and recording test cases.\n *\n * TRANSIENT on purpose. Every `createRpcClient(api, config)` needs its own instance, because `init()`\n * binds one instance to exactly one API contract and one target. {@link ProxyClientProvider} hands\n * them out — see its doc.\n */\n@provideFrameworkTransient()\nexport class NodeProxyClient extends ProxyClient {\n    private config!: ClientConfig;\n\n    constructor(\n        // webpieces-disable inject-annotation-not-needed-for-concrete-class -- DI-resolved param; the esbuild/vitest path elides type-only imports (no design:paramtypes), so the explicit token is required\n        @inject(RequestContextHeaders) private readonly headers: RequestContextHeaders,\n        // webpieces-disable inject-annotation-not-needed-for-concrete-class -- DI-resolved param; the esbuild/vitest path elides type-only imports (no design:paramtypes), so the explicit token is required\n        @inject(GcpOidc) private readonly gcpOidc: GcpOidc,\n        // @optional: only @AuthSharedSecret endpoints need it; the client sends its bound value.\n        // webpieces-disable inject-annotation-not-needed-for-concrete-class -- DI-resolved param; the esbuild/vitest path elides type-only imports (no design:paramtypes), so the explicit token is required\n        @optional() @inject(SECRETS) private readonly secrets?: Secrets,\n    ) {\n        super();\n    }\n\n    /** Bind this client to one API contract + target. */\n    init(apiPrototype: ApiPrototype<object>, config: ClientConfig): void {\n        this.config = config;\n        this.initRoutes(apiPrototype);\n    }\n\n    /**\n     * The same chain every client runs — a ClientRegistry mapping, else the installed deriver — but\n     * with NODE's fallback: THROW. A server has no \"own origin\" to fall back to the way a browser\n     * does, so an unresolvable peer is a setup bug and must fail loudly (the error names the fixes).\n     *\n     * Resolved per call, never at construction, so building a client stays synchronous. Any metadata\n     * read beneath a deriver is memoized process-wide, so only the first call pays.\n     */\n    protected override resolveBaseUrl(): Promise<string> {\n        return ClientRegistry.resolve(this.config.svcName);\n    }\n\n    /**\n     * Straight from the RequestContext. Throws when there is no active request scope.\n     *\n     * `destination` rides through unchanged: this is the ONE client that can legitimately propagate a\n     * verified identity, and it does so exactly when the callee will authenticate us (@AuthOidc /\n     * @AuthSharedSecret). Calling a peer's @Public or @AuthJwt endpoint now omits `x-user-id` and\n     * friends instead of shipping headers that endpoint's AuthFilter is obliged to reject.\n     */\n    protected override outboundContextHeaders(destination: DestinationTrust): Map<string, string> {\n        return this.headers.buildOutboundHeaders(destination);\n    }\n\n    /**\n     * Attach the outbound credential for the endpoint's AuthMode: an @AuthOidc bearer minted as\n     * this caller's runtime SA (audience = the callee base URL — the server verifies the signature\n     * + caller allow-list), or the @AuthSharedSecret(key) value THIS client sends from its bound\n     * {@link Secrets}. Both ride in the ONE `Authorization` header under their own scheme —\n     * `Bearer <oidc>` / `Webpieces <secret>` — which is never a context key, so it cannot leak onto\n     * the next hop. Never reads process.env.\n     */\n    protected override async attachOutboundAuth(\n        route: RouteMetadata,\n        baseUrl: string,\n        httpHeaders: Record<string, string>,\n    ): Promise<void> {\n        const mode = route.authMeta?.mode;\n        if (mode?.kind === 'oidc') {\n            httpHeaders['Authorization'] = `Bearer ${await this.gcpOidc.mintIdToken(baseUrl)}`;\n        } else if (mode?.kind === 'shared-secret') {\n            const secret = this.secrets?.get(mode.secretKey);\n            if (!secret) {\n                throw new Error(\n                    `No shared secret configured for @AuthSharedSecret('${mode.secretKey}') endpoint ${route.methodName}`,\n                );\n            }\n            // Same header as a JWT/OIDC token, but its OWN scheme, so a secret can never be\n            // mistaken for a token nor accepted where one was expected.\n            httpHeaders['Authorization'] = `Webpieces ${secret}`;\n        }\n    }\n\n    /**\n     * Test-case recording hook (mirror of Java HttpsJsonClientInvokeHandler): if a recorder is\n     * travelling in the magic context, capture this outbound call + its result so it becomes a mock\n     * in the generated test. Absent a recorder this is exactly the base behavior.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    protected override async execute(\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        const recorder = this.headers.findRecorder();\n        if (!recorder) {\n            return super.execute(route, requestDto, method);\n        }\n        return this.recordCall(recorder, route, requestDto, method);\n    }\n\n    /**\n     * Execute the call while recording it (args + masked ctx snapshot + result).\n     *\n     * The snapshot is a FIXTURE field, not a log line, so it is built here rather than handed down\n     * from the call path — a logging backend stamps its own fields and never sees this.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    private async recordCall(\n        recorder: TestCaseRecorder,\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        const ctxSnapshot: Record<string, string> = {};\n        for (const entry of RequestContext.buildLogFields().entries()) {\n            ctxSnapshot[entry[0]] = entry[1];\n        }\n        const recorded = new RecordedEndpoint(this.contractName(), route.methodName, [requestDto], ctxSnapshot);\n        recorder.addEndpointInfo(recorded);\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- capture failure into the recording, then rethrow unchanged\n        try {\n            const response = await super.execute(route, requestDto, method);\n            recorded.successResponse = response;\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            recorded.failureResponse = new RecordedError(error.name, error.message);\n            throw err;\n        }\n    }\n\n    /** A server can satisfy every auth mode, so nothing is rejected at bind time. */\n    protected override assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string): void {}\n\n    /**\n     * SERVER-TO-SERVER: a 4xx received from a dependency becomes THIS server's own 500.\n     *\n     * THE INVARIANT:\n     *\n     *   A status received from a downstream dependency describes OUR request to it. It is never the\n     *   status we return to OUR caller. The server that answered 404 is correct; the server that\n     *   asked for a route that does not exist is broken, and must say so as a 500.\n     *\n     * Every 4xx is a CALLER-side defect on this hop: 404 = wrong path / wrong base URL / a dependency\n     * that is not deployed yet, 400 = we sent a malformed request, 401/403 = our service credentials\n     * or the callee's caller allow-list are wrong. None of them is an answer for whoever called US, and\n     * relaying one lets an internal misconfiguration impersonate a legitimate response. That is not\n     * hypothetical: a partner-facing Management API reported an EMPTY store estate for an org with six\n     * live storefronts, because its dependency had not been promoted and Express served an HTML 404\n     * which arrived here as `HttpNotFoundError` and went straight back out. A 500 would have been\n     * loud, correct, and attributable to the one server that actually had the bug — which is the whole\n     * point: only ONE server should be paged for this.\n     *\n     * DELIBERATELY 4xx ONLY. 5xx (502/503/504) already mean \"the dependency is unavailable\", which is\n     * honest and useful outward, and 500 is already a 500. `HttpUserError` (266, a 2xx code carrying\n     * user validation) and `HttpVendorError` (598) are not statuses about our request at all. All of\n     * them pass through untouched.\n     *\n     * THE OPT-OUT IS `appRegistered`, not a config key. A thin proxy or gateway that genuinely wants to\n     * relay a downstream status as its own registers a `ClientRegistry` error translation for it at\n     * startup — one greppable line saying so out loud — and that translation wins here. Only the\n     * framework's built-in default mapping gets wrapped. There is no flag, because a flag would make\n     * the dangerous choice invisible in the code that suffers from it.\n     *\n     * The downstream diagnostic is NOT lost: the original error (which for the incident above names the\n     * method, the status, the `text/html` content-type and a snippet of the body) is both quoted in the\n     * message and kept as `httpCause`.\n     *\n     * How much \"Downstream said:\" is worth depends on WHO answered, and both halves are by design:\n     * - a NON-webpieces answer (an lb's html 404, a proxy's plain-text 502) is described CLIENT-side by\n     *   `ResponseBodyReader.describeForeignBody`, so the full diagnostic is ours to quote — this is the\n     *   mealco incident's exact shape, and it is the case that mattered.\n     * - a WEBPIECES peer deliberately sends only the generic reason phrase for its status (see\n     *   `HttpErrorWireMapper` in http-server — only `HttpUserError`'s message is caller-facing), so this\n     *   reads \"Downstream said: Not Found\". That is correct and not a regression: the peer's real\n     *   message is in the PEER's log, correlated by request id, which is the only place it was ever\n     *   safe to read it.\n     *\n     * This whole string is an operator-facing message on an `HttpInternalServerError`, so when THIS\n     * server answers its own caller none of it goes on the wire — it goes to this server's log.\n     */\n    protected override adaptDownstreamFailure(failure: TranslatedFailure, callId: string): Error {\n        if (failure.appRegistered) {\n            return failure.error;\n        }\n        if (failure.statusCode < 400 || failure.statusCode >= 500) {\n            return failure.error;\n        }\n        return new HttpInternalServerError(\n            `${callId}: dependency answered HTTP ${failure.statusCode}. That status describes OUR ` +\n            `request to it, not an answer for our caller, so this server owns it as a 500 — check the ` +\n            `path, the base URL, whether the dependency is deployed, and our service credentials. ` +\n            `Downstream said: ${failure.error.message}`,\n            failure.error,\n        );\n    }\n}\n\n/**\n * DI token for the `Provider<NodeProxyClient>` that hands out RPC clients — one per API contract.\n * `Provider<T>` is erased at runtime, so it cannot be its own token; this Symbol names T.\n *\n * Because NodeProxyClient is bound TRANSIENT, every `get()` constructs a new one. (Were it bound\n * `@provideFrameworkSingleton`, the very same Provider would instead hand back one lazily-created\n * instance — the provider caches nothing, so the target's scope decides.)\n */\n// webpieces-disable no-symbol-di-tokens -- Provider<T> is erased at runtime; the Symbol names T\nexport const NODE_PROXY_CLIENT_PROVIDER = Symbol.for('Provider<NodeProxyClient>');\n"]}
+{"version":3,"file":"NodeProxyClient.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/NodeProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, optional } from 'inversify';\nimport {\n    AuthMeta,\n    ClientRegistry,\n    DestinationTrust,\n    HttpInternalServerError,\n    RecordedEndpoint,\n    RecordedError,\n    RouteMetadata,\n    Secrets,\n    SECRETS,\n    TestCaseRecorder,\n    toError,\n} from '@webpieces/core-util';\nimport { RequestContext, RequestContextHeaders, provideFrameworkTransient } from '@webpieces/core-context';\nimport { GcpOidc } from '@webpieces/gcp-identity';\nimport { ApiPrototype, ClientFilterDefinition, ProxyClient, TranslatedFailure } from '@webpieces/http-client-core';\nimport { ClientConfig } from './ClientConfig';\n\n/**\n * The server-side {@link ProxyClient}. Everything a browser cannot do lives here: reading the\n * ambient RequestContext, minting OIDC tokens, holding shared secrets, and recording test cases.\n *\n * TRANSIENT on purpose. Every `createRpcClient(api, config)` needs its own instance, because `init()`\n * binds one instance to exactly one API contract and one target. {@link ProxyClientProvider} hands\n * them out — see its doc.\n */\n@provideFrameworkTransient()\nexport class NodeProxyClient extends ProxyClient {\n    private config!: ClientConfig;\n\n    constructor(\n        // webpieces-disable inject-annotation-not-needed-for-concrete-class -- DI-resolved param; the esbuild/vitest path elides type-only imports (no design:paramtypes), so the explicit token is required\n        @inject(RequestContextHeaders) private readonly headers: RequestContextHeaders,\n        // webpieces-disable inject-annotation-not-needed-for-concrete-class -- DI-resolved param; the esbuild/vitest path elides type-only imports (no design:paramtypes), so the explicit token is required\n        @inject(GcpOidc) private readonly gcpOidc: GcpOidc,\n        // @optional: only @AuthSharedSecret endpoints need it; the client sends its bound value.\n        // webpieces-disable inject-annotation-not-needed-for-concrete-class -- DI-resolved param; the esbuild/vitest path elides type-only imports (no design:paramtypes), so the explicit token is required\n        @optional() @inject(SECRETS) private readonly secrets?: Secrets,\n    ) {\n        super();\n    }\n\n    /**\n     * Bind this client to one API contract + target, with the app's outbound filters.\n     *\n     * `appFilters` is REQUIRED, not defaulted: an empty array is a statement that this client signs\n     * nothing and rewrites nothing, and it should be written down rather than inferred from an\n     * omitted argument.\n     */\n    init(apiPrototype: ApiPrototype<object>, config: ClientConfig, appFilters: ClientFilterDefinition[]): void {\n        this.config = config;\n        this.initRoutes(apiPrototype, appFilters);\n    }\n\n    /**\n     * The same chain every client runs — a ClientRegistry mapping, else the installed deriver — but\n     * with NODE's fallback: THROW. A server has no \"own origin\" to fall back to the way a browser\n     * does, so an unresolvable peer is a setup bug and must fail loudly (the error names the fixes).\n     *\n     * Resolved per call, never at construction, so building a client stays synchronous. Any metadata\n     * read beneath a deriver is memoized process-wide, so only the first call pays.\n     */\n    protected override resolveBaseUrl(): Promise<string> {\n        return this.config.hostPolicy.resolveBaseUrl(this.config.svcName);\n    }\n\n    /**\n     * The framework filters this client's {@link HostPolicy} demands — none for a deployed service,\n     * the context override plus the SSRF guard for a runtime host. Delegated rather than decided\n     * here so the two halves of \"where does this go\" (resolution and enforcement) cannot drift\n     * apart into different policies.\n     */\n    protected override clientFilters(): ClientFilterDefinition[] {\n        return this.config.hostPolicy.builtInFilters();\n    }\n\n    /**\n     * Straight from the RequestContext. Throws when there is no active request scope.\n     *\n     * `destination` rides through unchanged: this is the ONE client that can legitimately propagate a\n     * verified identity, and it does so exactly when the callee will authenticate us (@AuthOidc /\n     * @AuthSharedSecret). Calling a peer's @Public or @AuthJwt endpoint now omits `x-user-id` and\n     * friends instead of shipping headers that endpoint's AuthFilter is obliged to reject.\n     */\n    protected override outboundContextHeaders(destination: DestinationTrust): Map<string, string> {\n        return this.headers.buildOutboundHeaders(destination);\n    }\n\n    /**\n     * Attach the outbound credential for the endpoint's AuthMode: an @AuthOidc bearer minted as\n     * this caller's runtime SA (audience = the callee base URL — the server verifies the signature\n     * + caller allow-list), or the @AuthSharedSecret(key) value THIS client sends from its bound\n     * {@link Secrets}. Both ride in the ONE `Authorization` header under their own scheme —\n     * `Bearer <oidc>` / `Webpieces <secret>` — which is never a context key, so it cannot leak onto\n     * the next hop. Never reads process.env.\n     */\n    protected override async attachOutboundAuth(\n        route: RouteMetadata,\n        baseUrl: string,\n        httpHeaders: Map<string, string>,\n    ): Promise<void> {\n        const mode = route.authMeta?.mode;\n        if (mode?.kind === 'oidc') {\n            httpHeaders.set('Authorization', `Bearer ${await this.gcpOidc.mintIdToken(baseUrl)}`);\n        } else if (mode?.kind === 'shared-secret') {\n            const secret = this.secrets?.get(mode.secretKey);\n            if (!secret) {\n                throw new Error(\n                    `No shared secret configured for @AuthSharedSecret('${mode.secretKey}') endpoint ${route.methodName}`,\n                );\n            }\n            // Same header as a JWT/OIDC token, but its OWN scheme, so a secret can never be\n            // mistaken for a token nor accepted where one was expected.\n            httpHeaders.set('Authorization', `Webpieces ${secret}`);\n        }\n    }\n\n    /**\n     * Test-case recording hook (mirror of Java HttpsJsonClientInvokeHandler): if a recorder is\n     * travelling in the magic context, capture this outbound call + its result so it becomes a mock\n     * in the generated test. Absent a recorder this is exactly the base behavior.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    protected override async execute(\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        const recorder = this.headers.findRecorder();\n        if (!recorder) {\n            return super.execute(route, requestDto, method);\n        }\n        return this.recordCall(recorder, route, requestDto, method);\n    }\n\n    /**\n     * Execute the call while recording it (args + masked ctx snapshot + result).\n     *\n     * The snapshot is a FIXTURE field, not a log line, so it is built here rather than handed down\n     * from the call path — a logging backend stamps its own fields and never sees this.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    private async recordCall(\n        recorder: TestCaseRecorder,\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        const ctxSnapshot: Record<string, string> = {};\n        for (const entry of RequestContext.buildLogFields().entries()) {\n            ctxSnapshot[entry[0]] = entry[1];\n        }\n        const recorded = new RecordedEndpoint(this.contractName(), route.methodName, [requestDto], ctxSnapshot);\n        recorder.addEndpointInfo(recorded);\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- capture failure into the recording, then rethrow unchanged\n        try {\n            const response = await super.execute(route, requestDto, method);\n            recorded.successResponse = response;\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            recorded.failureResponse = new RecordedError(error.name, error.message);\n            throw err;\n        }\n    }\n\n    /**\n     * A server can satisfy every auth mode when it is talking to a peer it CHOSE, so the deployed\n     * policy rejects nothing. A runtime-host policy does reject: an OIDC token's audience and a\n     * shared secret both name a peer, and a destination that arrives per call has no honest one —\n     * see {@link HostPolicy.assertEndpointSupported}.\n     */\n    protected override assertEndpointSupported(authMeta: AuthMeta | undefined, methodName: string): void {\n        this.config.hostPolicy.assertEndpointSupported(authMeta, methodName, this.contractName());\n    }\n\n    /**\n     * SERVER-TO-SERVER: a 4xx received from a dependency becomes THIS server's own 500.\n     *\n     * THE INVARIANT:\n     *\n     *   A status received from a downstream dependency describes OUR request to it. It is never the\n     *   status we return to OUR caller. The server that answered 404 is correct; the server that\n     *   asked for a route that does not exist is broken, and must say so as a 500.\n     *\n     * Every 4xx is a CALLER-side defect on this hop: 404 = wrong path / wrong base URL / a dependency\n     * that is not deployed yet, 400 = we sent a malformed request, 401/403 = our service credentials\n     * or the callee's caller allow-list are wrong. None of them is an answer for whoever called US, and\n     * relaying one lets an internal misconfiguration impersonate a legitimate response. That is not\n     * hypothetical: a partner-facing Management API reported an EMPTY store estate for an org with six\n     * live storefronts, because its dependency had not been promoted and Express served an HTML 404\n     * which arrived here as `HttpNotFoundError` and went straight back out. A 500 would have been\n     * loud, correct, and attributable to the one server that actually had the bug — which is the whole\n     * point: only ONE server should be paged for this.\n     *\n     * DELIBERATELY 4xx ONLY. 5xx (502/503/504) already mean \"the dependency is unavailable\", which is\n     * honest and useful outward, and 500 is already a 500. `HttpUserError` (266, a 2xx code carrying\n     * user validation) and `HttpVendorError` (598) are not statuses about our request at all. All of\n     * them pass through untouched.\n     *\n     * THE OPT-OUT IS `appRegistered`, not a config key. A thin proxy or gateway that genuinely wants to\n     * relay a downstream status as its own registers a `ClientRegistry` error translation for it at\n     * startup — one greppable line saying so out loud — and that translation wins here. Only the\n     * framework's built-in default mapping gets wrapped. There is no flag, because a flag would make\n     * the dangerous choice invisible in the code that suffers from it.\n     *\n     * The downstream diagnostic is NOT lost: the original error (which for the incident above names the\n     * method, the status, the `text/html` content-type and a snippet of the body) is both quoted in the\n     * message and kept as `httpCause`.\n     *\n     * How much \"Downstream said:\" is worth depends on WHO answered, and both halves are by design:\n     * - a NON-webpieces answer (an lb's html 404, a proxy's plain-text 502) is described CLIENT-side by\n     *   `ResponseBodyReader.describeForeignBody`, so the full diagnostic is ours to quote — this is the\n     *   mealco incident's exact shape, and it is the case that mattered.\n     * - a WEBPIECES peer deliberately sends only the generic reason phrase for its status (see\n     *   `HttpErrorWireMapper` in http-server — only `HttpUserError`'s message is caller-facing), so this\n     *   reads \"Downstream said: Not Found\". That is correct and not a regression: the peer's real\n     *   message is in the PEER's log, correlated by request id, which is the only place it was ever\n     *   safe to read it.\n     *\n     * This whole string is an operator-facing message on an `HttpInternalServerError`, so when THIS\n     * server answers its own caller none of it goes on the wire — it goes to this server's log.\n     */\n    protected override adaptDownstreamFailure(failure: TranslatedFailure, callId: string): Error {\n        if (failure.appRegistered) {\n            return failure.error;\n        }\n        if (failure.statusCode < 400 || failure.statusCode >= 500) {\n            return failure.error;\n        }\n        return new HttpInternalServerError(\n            `${callId}: dependency answered HTTP ${failure.statusCode}. That status describes OUR ` +\n            `request to it, not an answer for our caller, so this server owns it as a 500 — check the ` +\n            `path, the base URL, whether the dependency is deployed, and our service credentials. ` +\n            `Downstream said: ${failure.error.message}`,\n            failure.error,\n        );\n    }\n}\n\n/**\n * DI token for the `Provider<NodeProxyClient>` that hands out RPC clients — one per API contract.\n * `Provider<T>` is erased at runtime, so it cannot be its own token; this Symbol names T.\n *\n * Because NodeProxyClient is bound TRANSIENT, every `get()` constructs a new one. (Were it bound\n * `@provideFrameworkSingleton`, the very same Provider would instead hand back one lazily-created\n * instance — the provider caches nothing, so the target's scope decides.)\n */\n// webpieces-disable no-symbol-di-tokens -- Provider<T> is erased at runtime; the Symbol names T\nexport const NODE_PROXY_CLIENT_PROVIDER = Symbol.for('Provider<NodeProxyClient>');\n"]}

package/src/RuntimeHostErrors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The two ways a RUNTIME-HOST client refuses before any bytes leave, each its own type for the same
+ * reason {@link SsrfRefusedError} is: a delivery worker has to tell these apart, and they have
+ * different owners and different cures.
+ *
+ * - {@link RuntimeHostEndpointUnsupportedError} — BIND time, OUR bug. The contract declares an auth
+ *   mode no runtime-host client can honestly satisfy. It fires when the client is built, so it takes
+ *   the process down at startup rather than at the first delivery, which is the point.
+ * - {@link MissingRuntimeBaseUrlError} — CALL time, the CALLER's bug. This call was made with no
+ *   destination in scope. Retrying is pointless; the fix is at the call site.
+ *
+ * Neither is an {@link SsrfRefusedError}: nothing about the destination was judged and found hostile.
+ * A worker that dead-letters on SSRF should usually PAGE on these instead — they mean the sender is
+ * misconfigured, not that a partner registered something dangerous.
+ */
+/**
+ * A runtime-host client was pointed at an endpoint whose auth mode mints a credential for an
+ * audience WE choose (`@AuthOidc`, `@AuthSharedSecret`). Thrown at BIND time, from
+ * `HostPolicy.assertEndpointSupported`.
+ */
+export declare class RuntimeHostEndpointUnsupportedError extends Error {
+    /** `Contract.method`, so a startup failure names the endpoint without reading a stack. */
+    readonly endpoint: string;
+    constructor(message: string, 
+    /** `Contract.method`, so a startup failure names the endpoint without reading a stack. */
+    endpoint: string);
+}
+/**
+ * A runtime-host client was called with no `WebpiecesCoreHeaders.OVERRIDE_BASE_URL` in the ambient
+ * RequestContext, so there is no destination for this call.
+ *
+ * It is a THROW rather than a fallback to a derived service URL, deliberately: a silent fallback
+ * would send a partner's payload to one of our own services, which is a worse outcome than a loud
+ * failure by every measure.
+ */
+export declare class MissingRuntimeBaseUrlError extends Error {
+    /** `Contract.method`, so the log line names the call that had nowhere to go. */
+    readonly endpoint: string;
+    constructor(message: string, 
+    /** `Contract.method`, so the log line names the call that had nowhere to go. */
+    endpoint: string);
+}

package/src/RuntimeHostErrors.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * The two ways a RUNTIME-HOST client refuses before any bytes leave, each its own type for the same
+ * reason {@link SsrfRefusedError} is: a delivery worker has to tell these apart, and they have
+ * different owners and different cures.
+ *
+ * - {@link RuntimeHostEndpointUnsupportedError} — BIND time, OUR bug. The contract declares an auth
+ *   mode no runtime-host client can honestly satisfy. It fires when the client is built, so it takes
+ *   the process down at startup rather than at the first delivery, which is the point.
+ * - {@link MissingRuntimeBaseUrlError} — CALL time, the CALLER's bug. This call was made with no
+ *   destination in scope. Retrying is pointless; the fix is at the call site.
+ *
+ * Neither is an {@link SsrfRefusedError}: nothing about the destination was judged and found hostile.
+ * A worker that dead-letters on SSRF should usually PAGE on these instead — they mean the sender is
+ * misconfigured, not that a partner registered something dangerous.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingRuntimeBaseUrlError = exports.RuntimeHostEndpointUnsupportedError = void 0;
+/**
+ * A runtime-host client was pointed at an endpoint whose auth mode mints a credential for an
+ * audience WE choose (`@AuthOidc`, `@AuthSharedSecret`). Thrown at BIND time, from
+ * `HostPolicy.assertEndpointSupported`.
+ */
+class RuntimeHostEndpointUnsupportedError extends Error {
+    endpoint;
+    constructor(message, 
+    /** `Contract.method`, so a startup failure names the endpoint without reading a stack. */
+    endpoint) {
+        super(message);
+        this.endpoint = endpoint;
+        this.name = 'RuntimeHostEndpointUnsupportedError';
+    }
+}
+exports.RuntimeHostEndpointUnsupportedError = RuntimeHostEndpointUnsupportedError;
+/**
+ * A runtime-host client was called with no `WebpiecesCoreHeaders.OVERRIDE_BASE_URL` in the ambient
+ * RequestContext, so there is no destination for this call.
+ *
+ * It is a THROW rather than a fallback to a derived service URL, deliberately: a silent fallback
+ * would send a partner's payload to one of our own services, which is a worse outcome than a loud
+ * failure by every measure.
+ */
+class MissingRuntimeBaseUrlError extends Error {
+    endpoint;
+    constructor(message, 
+    /** `Contract.method`, so the log line names the call that had nowhere to go. */
+    endpoint) {
+        super(message);
+        this.endpoint = endpoint;
+        this.name = 'MissingRuntimeBaseUrlError';
+    }
+}
+exports.MissingRuntimeBaseUrlError = MissingRuntimeBaseUrlError;
+//# sourceMappingURL=RuntimeHostErrors.js.map

package/src/RuntimeHostErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeHostErrors.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/RuntimeHostErrors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH;;;;GAIG;AACH,MAAa,mCAAoC,SAAQ,KAAK;IAItC;IAHpB,YACI,OAAe;IACf,0FAA0F;IAC1E,QAAgB;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,aAAQ,GAAR,QAAQ,CAAQ;QAGhC,IAAI,CAAC,IAAI,GAAG,qCAAqC,CAAC;IACtD,CAAC;CACJ;AATD,kFASC;AAED;;;;;;;GAOG;AACH,MAAa,0BAA2B,SAAQ,KAAK;IAI7B;IAHpB,YACI,OAAe;IACf,gFAAgF;IAChE,QAAgB;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,aAAQ,GAAR,QAAQ,CAAQ;QAGhC,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC7C,CAAC;CACJ;AATD,gEASC","sourcesContent":["/**\n * The two ways a RUNTIME-HOST client refuses before any bytes leave, each its own type for the same\n * reason {@link SsrfRefusedError} is: a delivery worker has to tell these apart, and they have\n * different owners and different cures.\n *\n * - {@link RuntimeHostEndpointUnsupportedError} — BIND time, OUR bug. The contract declares an auth\n *   mode no runtime-host client can honestly satisfy. It fires when the client is built, so it takes\n *   the process down at startup rather than at the first delivery, which is the point.\n * - {@link MissingRuntimeBaseUrlError} — CALL time, the CALLER's bug. This call was made with no\n *   destination in scope. Retrying is pointless; the fix is at the call site.\n *\n * Neither is an {@link SsrfRefusedError}: nothing about the destination was judged and found hostile.\n * A worker that dead-letters on SSRF should usually PAGE on these instead — they mean the sender is\n * misconfigured, not that a partner registered something dangerous.\n */\n\n/**\n * A runtime-host client was pointed at an endpoint whose auth mode mints a credential for an\n * audience WE choose (`@AuthOidc`, `@AuthSharedSecret`). Thrown at BIND time, from\n * `HostPolicy.assertEndpointSupported`.\n */\nexport class RuntimeHostEndpointUnsupportedError extends Error {\n    constructor(\n        message: string,\n        /** `Contract.method`, so a startup failure names the endpoint without reading a stack. */\n        public readonly endpoint: string,\n    ) {\n        super(message);\n        this.name = 'RuntimeHostEndpointUnsupportedError';\n    }\n}\n\n/**\n * A runtime-host client was called with no `WebpiecesCoreHeaders.OVERRIDE_BASE_URL` in the ambient\n * RequestContext, so there is no destination for this call.\n *\n * It is a THROW rather than a fallback to a derived service URL, deliberately: a silent fallback\n * would send a partner's payload to one of our own services, which is a worse outcome than a loud\n * failure by every measure.\n */\nexport class MissingRuntimeBaseUrlError extends Error {\n    constructor(\n        message: string,\n        /** `Contract.method`, so the log line names the call that had nowhere to go. */\n        public readonly endpoint: string,\n    ) {\n        super(message);\n        this.name = 'MissingRuntimeBaseUrlError';\n    }\n}\n"]}

package/src/SsrfGuardFilter.d.ts

@@ -0,0 +1,50 @@
+import { Filter, Service } from '@webpieces/core-util';
+import { ClientRequest } from '@webpieces/http-client-core';
+import { AddressResolver } from './AddressResolver';
+import { SsrfPolicy } from './SsrfPolicy';
+/**
+ * Enforces {@link SsrfPolicy} on a call whose destination came from RUNTIME data.
+ *
+ * The moment the base URL is a database column a partner edited, "do not let our process be used as
+ * a proxy into our own network" stops being the caller's job and becomes the framework's. Every
+ * consumer was reinventing this, badly or not at all, and the one that did it best still only
+ * managed `maxRedirects: 0` by hand.
+ *
+ * ## What it enforces, per hop
+ *
+ * 1. the URL parses and its scheme is allowed (https only, by default);
+ * 2. the hostname is not internal BY NAME (`localhost`, `metadata.google.internal`, `*.internal`);
+ * 3. EVERY address the hostname resolves to is public — one private answer among several condemns
+ *    the request, which is what makes DNS rebinding a refusal rather than a coin toss;
+ * 4. redirects are not followed by the transport. The guard reads the `Location` itself, re-runs
+ *    (1)–(3) on it, and only then re-invokes the chain. A partner URL that 302s to
+ *    `http://169.254.169.254/…` is refused at the redirect, not obeyed — and because the whole
+ *    chain below re-runs, whatever signs the request signs it for the host it is actually going to.
+ *
+ * ## What it deliberately does NOT claim
+ *
+ * There is a TOCTOU window between resolving a name and the transport connecting: a hostile DNS
+ * server can answer differently for the two lookups. Closing it properly means pinning the resolved
+ * address into the socket, which node's transport gives no seam for. This guard raises the cost of
+ * the attack a great deal and is honest about not eliminating it; egress firewalling remains the
+ * control that actually cannot be tricked.
+ */
+export declare class SsrfGuardFilter extends Filter<ClientRequest, Response> {
+    private readonly policy;
+    private readonly addressResolver;
+    private readonly rules;
+    constructor(policy: SsrfPolicy, addressResolver: AddressResolver);
+    filter(request: ClientRequest, nextFilter: Service<ClientRequest, Response>): Promise<Response>;
+    /**
+     * @throws SsrfRefusedError naming what condemned the url and the ONE opt-out that would allow
+     *         it. Returns normally when the destination is acceptable.
+     */
+    private assertAllowed;
+    private refuseInternal;
+    /** Every address for `hostname`, or a refusal — a name that will not resolve is not a destination. */
+    private resolveOrRefuse;
+    private parse;
+    private isRedirect;
+    /** The redirect's absolute target, resolving a relative Location against the URL we just called. */
+    private redirectTargetOf;
+}

package/src/SsrfGuardFilter.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SsrfGuardFilter = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const InternalAddressRules_1 = require("./InternalAddressRules");
+const SsrfRefusedError_1 = require("./SsrfRefusedError");
+/**
+ * Enforces {@link SsrfPolicy} on a call whose destination came from RUNTIME data.
+ *
+ * The moment the base URL is a database column a partner edited, "do not let our process be used as
+ * a proxy into our own network" stops being the caller's job and becomes the framework's. Every
+ * consumer was reinventing this, badly or not at all, and the one that did it best still only
+ * managed `maxRedirects: 0` by hand.
+ *
+ * ## What it enforces, per hop
+ *
+ * 1. the URL parses and its scheme is allowed (https only, by default);
+ * 2. the hostname is not internal BY NAME (`localhost`, `metadata.google.internal`, `*.internal`);
+ * 3. EVERY address the hostname resolves to is public — one private answer among several condemns
+ *    the request, which is what makes DNS rebinding a refusal rather than a coin toss;
+ * 4. redirects are not followed by the transport. The guard reads the `Location` itself, re-runs
+ *    (1)–(3) on it, and only then re-invokes the chain. A partner URL that 302s to
+ *    `http://169.254.169.254/…` is refused at the redirect, not obeyed — and because the whole
+ *    chain below re-runs, whatever signs the request signs it for the host it is actually going to.
+ *
+ * ## What it deliberately does NOT claim
+ *
+ * There is a TOCTOU window between resolving a name and the transport connecting: a hostile DNS
+ * server can answer differently for the two lookups. Closing it properly means pinning the resolved
+ * address into the socket, which node's transport gives no seam for. This guard raises the cost of
+ * the attack a great deal and is honest about not eliminating it; egress firewalling remains the
+ * control that actually cannot be tricked.
+ */
+class SsrfGuardFilter extends core_util_1.Filter {
+    policy;
+    addressResolver;
+    rules = new InternalAddressRules_1.InternalAddressRules();
+    constructor(policy, addressResolver) {
+        super();
+        this.policy = policy;
+        this.addressResolver = addressResolver;
+    }
+    async filter(request, nextFilter) {
+        await this.assertAllowed(request.url);
+        // The transport must not follow a redirect on its own — that would be a hop this policy
+        // never saw. We read the Location and judge it ourselves, below.
+        request.followRedirects = false;
+        let response = await nextFilter.invoke(request);
+        for (let hop = 0; this.isRedirect(response); hop++) {
+            if (hop >= this.policy.maxRedirects) {
+                throw new SsrfRefusedError_1.SsrfRefusedError(`${request.contractName}.${request.route.methodName}: refused to follow more than ` +
+                    `${this.policy.maxRedirects} redirect(s) from a runtime-supplied destination. ` +
+                    `The last one was ${request.url}. A webhook endpoint that needs a longer redirect ` +
+                    `chain should be registered at its final URL instead.`, request.url);
+            }
+            const target = this.redirectTargetOf(response, request);
+            await this.assertAllowed(target);
+            request.followRedirectTo(target);
+            response = await nextFilter.invoke(request);
+        }
+        return response;
+    }
+    /**
+     * @throws SsrfRefusedError naming what condemned the url and the ONE opt-out that would allow
+     *         it. Returns normally when the destination is acceptable.
+     */
+    async assertAllowed(url) {
+        const parsed = this.parse(url);
+        if (!this.policy.allowedSchemes.has(parsed.protocol)) {
+            const allowed = [...this.policy.allowedSchemes].join(', ');
+            throw new SsrfRefusedError_1.SsrfRefusedError(`Refusing to send to ${url}: scheme '${parsed.protocol}' is not allowed (allowed: ${allowed}). ` +
+                `A destination supplied at runtime must be reached over TLS — a plaintext hop leaks the ` +
+                `payload and its signature to anything on the path.`, url);
+        }
+        if (this.policy.allowInternalAddresses) {
+            return;
+        }
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+        if (this.rules.isInternalHostname(hostname)) {
+            throw this.refuseInternal(url, `'${hostname}' names infrastructure inside our own network`);
+        }
+        for (const address of await this.resolveOrRefuse(url, hostname)) {
+            if (this.rules.isInternalAddress(address)) {
+                throw this.refuseInternal(url, `it resolves to the internal address ${address}`);
+            }
+        }
+    }
+    refuseInternal(url, because) {
+        return new SsrfRefusedError_1.SsrfRefusedError(`Refusing to send to ${url}: ${because}. A destination supplied at runtime is attacker-influenced ` +
+            `data, so loopback, RFC1918, link-local and cloud-metadata addresses are refused — reaching ` +
+            `169.254.169.254 would hand this process's own service-account tokens to whoever registered ` +
+            `the URL. If this client genuinely must reach an internal host (a local emulator, an ` +
+            `on-cluster service), say so at the construction site with ` +
+            `new RuntimeHostFromContextAllowingInternalAddresses('<why>', new DnsAddressResolver()) ` +
+            `instead of new RuntimeHostFromContext(new DnsAddressResolver()).`, url);
+    }
+    /** Every address for `hostname`, or a refusal — a name that will not resolve is not a destination. */
+    async resolveOrRefuse(url, hostname) {
+        // An IP LITERAL never went to DNS, so judge it directly; hostnames go to the resolver.
+        if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.includes(':')) {
+            return [hostname];
+        }
+        // webpieces-disable no-unmanaged-exceptions -- turn an unresolvable name into the SAME refusal a bad address gets
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return await this.addressResolver.resolve(hostname);
+        }
+        catch (err) {
+            const error = (0, core_util_1.toError)(err);
+            throw new SsrfRefusedError_1.SsrfRefusedError(`Refusing to send to ${url}: '${hostname}' did not resolve (${error.message}). ` +
+                `An unresolvable destination is refused rather than attempted, so a partner row that has ` +
+                `gone stale fails as a delivery error instead of as a network timeout.`, url);
+        }
+    }
+    parse(url) {
+        // webpieces-disable no-unmanaged-exceptions -- an unparseable url is a refusal, in this filter's own vocabulary
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return new URL(url);
+        }
+        catch (err) {
+            const error = (0, core_util_1.toError)(err);
+            throw new SsrfRefusedError_1.SsrfRefusedError(`Refusing to send to '${url}': it is not a parseable absolute URL (${error.message}). ` +
+                `A runtime-supplied base URL must be absolute, e.g. 'https://api.partner.example'.`, url);
+        }
+    }
+    isRedirect(response) {
+        return response.status >= 300 && response.status < 400 && response.headers.get('location') !== null;
+    }
+    /** The redirect's absolute target, resolving a relative Location against the URL we just called. */
+    redirectTargetOf(response, request) {
+        const location = response.headers.get('location') ?? '';
+        // webpieces-disable no-unmanaged-exceptions -- a malformed Location is a refusal, in this filter's own vocabulary
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return new URL(location, request.url).toString();
+        }
+        catch (err) {
+            const error = (0, core_util_1.toError)(err);
+            throw new SsrfRefusedError_1.SsrfRefusedError(`Refusing to follow the redirect from ${request.url}: its Location header ` +
+                `'${location}' is not a usable URL (${error.message}).`, request.url);
+        }
+    }
+}
+exports.SsrfGuardFilter = SsrfGuardFilter;
+//# sourceMappingURL=SsrfGuardFilter.js.map

package/src/SsrfGuardFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SsrfGuardFilter.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/SsrfGuardFilter.ts"],"names":[],"mappings":"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","sourcesContent":["import { Filter, Service, toError } from '@webpieces/core-util';\nimport { ClientRequest } from '@webpieces/http-client-core';\nimport { AddressResolver } from './AddressResolver';\nimport { InternalAddressRules } from './InternalAddressRules';\nimport { SsrfPolicy } from './SsrfPolicy';\nimport { SsrfRefusedError } from './SsrfRefusedError';\n\n/**\n * Enforces {@link SsrfPolicy} on a call whose destination came from RUNTIME data.\n *\n * The moment the base URL is a database column a partner edited, \"do not let our process be used as\n * a proxy into our own network\" stops being the caller's job and becomes the framework's. Every\n * consumer was reinventing this, badly or not at all, and the one that did it best still only\n * managed `maxRedirects: 0` by hand.\n *\n * ## What it enforces, per hop\n *\n * 1. the URL parses and its scheme is allowed (https only, by default);\n * 2. the hostname is not internal BY NAME (`localhost`, `metadata.google.internal`, `*.internal`);\n * 3. EVERY address the hostname resolves to is public — one private answer among several condemns\n *    the request, which is what makes DNS rebinding a refusal rather than a coin toss;\n * 4. redirects are not followed by the transport. The guard reads the `Location` itself, re-runs\n *    (1)–(3) on it, and only then re-invokes the chain. A partner URL that 302s to\n *    `http://169.254.169.254/…` is refused at the redirect, not obeyed — and because the whole\n *    chain below re-runs, whatever signs the request signs it for the host it is actually going to.\n *\n * ## What it deliberately does NOT claim\n *\n * There is a TOCTOU window between resolving a name and the transport connecting: a hostile DNS\n * server can answer differently for the two lookups. Closing it properly means pinning the resolved\n * address into the socket, which node's transport gives no seam for. This guard raises the cost of\n * the attack a great deal and is honest about not eliminating it; egress firewalling remains the\n * control that actually cannot be tricked.\n */\nexport class SsrfGuardFilter extends Filter<ClientRequest, Response> {\n    private readonly rules = new InternalAddressRules();\n\n    constructor(\n        private readonly policy: SsrfPolicy,\n        private readonly addressResolver: AddressResolver,\n    ) {\n        super();\n    }\n\n    override async filter(request: ClientRequest, nextFilter: Service<ClientRequest, Response>): Promise<Response> {\n        await this.assertAllowed(request.url);\n\n        // The transport must not follow a redirect on its own — that would be a hop this policy\n        // never saw. We read the Location and judge it ourselves, below.\n        request.followRedirects = false;\n\n        let response = await nextFilter.invoke(request);\n        for (let hop = 0; this.isRedirect(response); hop++) {\n            if (hop >= this.policy.maxRedirects) {\n                throw new SsrfRefusedError(\n                    `${request.contractName}.${request.route.methodName}: refused to follow more than ` +\n                        `${this.policy.maxRedirects} redirect(s) from a runtime-supplied destination. ` +\n                        `The last one was ${request.url}. A webhook endpoint that needs a longer redirect ` +\n                        `chain should be registered at its final URL instead.`,\n                    request.url,\n                );\n            }\n            const target = this.redirectTargetOf(response, request);\n            await this.assertAllowed(target);\n            request.followRedirectTo(target);\n            response = await nextFilter.invoke(request);\n        }\n        return response;\n    }\n\n    /**\n     * @throws SsrfRefusedError naming what condemned the url and the ONE opt-out that would allow\n     *         it. Returns normally when the destination is acceptable.\n     */\n    private async assertAllowed(url: string): Promise<void> {\n        const parsed = this.parse(url);\n        if (!this.policy.allowedSchemes.has(parsed.protocol)) {\n            const allowed = [...this.policy.allowedSchemes].join(', ');\n            throw new SsrfRefusedError(\n                `Refusing to send to ${url}: scheme '${parsed.protocol}' is not allowed (allowed: ${allowed}). ` +\n                    `A destination supplied at runtime must be reached over TLS — a plaintext hop leaks the ` +\n                    `payload and its signature to anything on the path.`,\n                url,\n            );\n        }\n        if (this.policy.allowInternalAddresses) {\n            return;\n        }\n        const hostname = parsed.hostname.replace(/^\\[|\\]$/g, '');\n        if (this.rules.isInternalHostname(hostname)) {\n            throw this.refuseInternal(url, `'${hostname}' names infrastructure inside our own network`);\n        }\n        for (const address of await this.resolveOrRefuse(url, hostname)) {\n            if (this.rules.isInternalAddress(address)) {\n                throw this.refuseInternal(url, `it resolves to the internal address ${address}`);\n            }\n        }\n    }\n\n    private refuseInternal(url: string, because: string): SsrfRefusedError {\n        return new SsrfRefusedError(\n            `Refusing to send to ${url}: ${because}. A destination supplied at runtime is attacker-influenced ` +\n                `data, so loopback, RFC1918, link-local and cloud-metadata addresses are refused — reaching ` +\n                `169.254.169.254 would hand this process's own service-account tokens to whoever registered ` +\n                `the URL. If this client genuinely must reach an internal host (a local emulator, an ` +\n                `on-cluster service), say so at the construction site with ` +\n                `new RuntimeHostFromContextAllowingInternalAddresses('<why>', new DnsAddressResolver()) ` +\n                `instead of new RuntimeHostFromContext(new DnsAddressResolver()).`,\n            url,\n        );\n    }\n\n    /** Every address for `hostname`, or a refusal — a name that will not resolve is not a destination. */\n    private async resolveOrRefuse(url: string, hostname: string): Promise<string[]> {\n        // An IP LITERAL never went to DNS, so judge it directly; hostnames go to the resolver.\n        if (/^\\d{1,3}(\\.\\d{1,3}){3}$/.test(hostname) || hostname.includes(':')) {\n            return [hostname];\n        }\n        // webpieces-disable no-unmanaged-exceptions -- turn an unresolvable name into the SAME refusal a bad address gets\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await this.addressResolver.resolve(hostname);\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw new SsrfRefusedError(\n                `Refusing to send to ${url}: '${hostname}' did not resolve (${error.message}). ` +\n                    `An unresolvable destination is refused rather than attempted, so a partner row that has ` +\n                    `gone stale fails as a delivery error instead of as a network timeout.`,\n                url,\n            );\n        }\n    }\n\n    private parse(url: string): URL {\n        // webpieces-disable no-unmanaged-exceptions -- an unparseable url is a refusal, in this filter's own vocabulary\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return new URL(url);\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw new SsrfRefusedError(\n                `Refusing to send to '${url}': it is not a parseable absolute URL (${error.message}). ` +\n                    `A runtime-supplied base URL must be absolute, e.g. 'https://api.partner.example'.`,\n                url,\n            );\n        }\n    }\n\n    private isRedirect(response: Response): boolean {\n        return response.status >= 300 && response.status < 400 && response.headers.get('location') !== null;\n    }\n\n    /** The redirect's absolute target, resolving a relative Location against the URL we just called. */\n    private redirectTargetOf(response: Response, request: ClientRequest): string {\n        const location = response.headers.get('location') ?? '';\n        // webpieces-disable no-unmanaged-exceptions -- a malformed Location is a refusal, in this filter's own vocabulary\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return new URL(location, request.url).toString();\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw new SsrfRefusedError(\n                `Refusing to follow the redirect from ${request.url}: its Location header ` +\n                    `'${location}' is not a usable URL (${error.message}).`,\n                request.url,\n            );\n        }\n    }\n}\n"]}

package/src/SsrfPolicy.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What a runtime-supplied destination has to satisfy before this client will send to it.
+ *
+ * DATA ONLY — the enforcement is {@link SsrfGuardFilter}. It is constructed by a
+ * {@link HostPolicy}, never by app code directly, because the CHOICE between the strict policy and
+ * the internal-addresses one is made by naming a host-policy class at the `new ClientConfig(...)`
+ * call site. That keeps the permissive answer a greppable noun rather than a boolean somebody
+ * flipped.
+ */
+export declare class SsrfPolicy {
+    /**
+     * URL schemes that may be sent to, with their colons ('https:'). HTTPS-only by default: a
+     * partner-registered destination reached over plaintext http leaks the payload and its
+     * signature to anything on the path, and "the partner has not got TLS yet" is their bug to
+     * fix, not ours to accommodate silently.
+     */
+    readonly allowedSchemes: ReadonlySet<string>;
+    /**
+     * TRUE only under {@link RuntimeHostFromContextAllowingInternalAddresses}. When true, the
+     * loopback / RFC1918 / link-local / metadata refusals are skipped — scheme checking and the
+     * redirect cap still apply.
+     */
+    readonly allowInternalAddresses: boolean;
+    /**
+     * How many redirects may be followed, each one re-judged under this same policy. Small on
+     * purpose: a legitimate webhook endpoint does not need a redirect chain, and every hop is
+     * another chance for the destination to move somewhere we did not agree to.
+     */
+    readonly maxRedirects: number;
+    /**
+     * WHY internal addresses are allowed, in prose, when they are. Required by
+     * {@link RuntimeHostFromContextAllowingInternalAddresses} and quoted in the log line the
+     * guard writes, so the reason travels with the decision instead of living in a commit
+     * message nobody will find.
+     */
+    readonly allowInternalReason: string | undefined;
+    constructor(
+    /**
+     * URL schemes that may be sent to, with their colons ('https:'). HTTPS-only by default: a
+     * partner-registered destination reached over plaintext http leaks the payload and its
+     * signature to anything on the path, and "the partner has not got TLS yet" is their bug to
+     * fix, not ours to accommodate silently.
+     */
+    allowedSchemes: ReadonlySet<string>, 
+    /**
+     * TRUE only under {@link RuntimeHostFromContextAllowingInternalAddresses}. When true, the
+     * loopback / RFC1918 / link-local / metadata refusals are skipped — scheme checking and the
+     * redirect cap still apply.
+     */
+    allowInternalAddresses: boolean, 
+    /**
+     * How many redirects may be followed, each one re-judged under this same policy. Small on
+     * purpose: a legitimate webhook endpoint does not need a redirect chain, and every hop is
+     * another chance for the destination to move somewhere we did not agree to.
+     */
+    maxRedirects: number, 
+    /**
+     * WHY internal addresses are allowed, in prose, when they are. Required by
+     * {@link RuntimeHostFromContextAllowingInternalAddresses} and quoted in the log line the
+     * guard writes, so the reason travels with the decision instead of living in a commit
+     * message nobody will find.
+     */
+    allowInternalReason: string | undefined);
+}

package/src/SsrfPolicy.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SsrfPolicy = void 0;
+/**
+ * What a runtime-supplied destination has to satisfy before this client will send to it.
+ *
+ * DATA ONLY — the enforcement is {@link SsrfGuardFilter}. It is constructed by a
+ * {@link HostPolicy}, never by app code directly, because the CHOICE between the strict policy and
+ * the internal-addresses one is made by naming a host-policy class at the `new ClientConfig(...)`
+ * call site. That keeps the permissive answer a greppable noun rather than a boolean somebody
+ * flipped.
+ */
+class SsrfPolicy {
+    allowedSchemes;
+    allowInternalAddresses;
+    maxRedirects;
+    allowInternalReason;
+    constructor(
+    /**
+     * URL schemes that may be sent to, with their colons ('https:'). HTTPS-only by default: a
+     * partner-registered destination reached over plaintext http leaks the payload and its
+     * signature to anything on the path, and "the partner has not got TLS yet" is their bug to
+     * fix, not ours to accommodate silently.
+     */
+    allowedSchemes, 
+    /**
+     * TRUE only under {@link RuntimeHostFromContextAllowingInternalAddresses}. When true, the
+     * loopback / RFC1918 / link-local / metadata refusals are skipped — scheme checking and the
+     * redirect cap still apply.
+     */
+    allowInternalAddresses, 
+    /**
+     * How many redirects may be followed, each one re-judged under this same policy. Small on
+     * purpose: a legitimate webhook endpoint does not need a redirect chain, and every hop is
+     * another chance for the destination to move somewhere we did not agree to.
+     */
+    maxRedirects, 
+    /**
+     * WHY internal addresses are allowed, in prose, when they are. Required by
+     * {@link RuntimeHostFromContextAllowingInternalAddresses} and quoted in the log line the
+     * guard writes, so the reason travels with the decision instead of living in a commit
+     * message nobody will find.
+     */
+    allowInternalReason) {
+        this.allowedSchemes = allowedSchemes;
+        this.allowInternalAddresses = allowInternalAddresses;
+        this.maxRedirects = maxRedirects;
+        this.allowInternalReason = allowInternalReason;
+    }
+}
+exports.SsrfPolicy = SsrfPolicy;
+//# sourceMappingURL=SsrfPolicy.js.map

package/src/SsrfPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SsrfPolicy.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/SsrfPolicy.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,UAAU;IAQC;IAMA;IAMA;IAOA;IA1BpB;IACI;;;;;OAKG;IACa,cAAmC;IACnD;;;;OAIG;IACa,sBAA+B;IAC/C;;;;OAIG;IACa,YAAoB;IACpC;;;;;OAKG;IACa,mBAAuC;QAnBvC,mBAAc,GAAd,cAAc,CAAqB;QAMnC,2BAAsB,GAAtB,sBAAsB,CAAS;QAM/B,iBAAY,GAAZ,YAAY,CAAQ;QAOpB,wBAAmB,GAAnB,mBAAmB,CAAoB;IACxD,CAAC;CACP;AA7BD,gCA6BC","sourcesContent":["/**\n * What a runtime-supplied destination has to satisfy before this client will send to it.\n *\n * DATA ONLY — the enforcement is {@link SsrfGuardFilter}. It is constructed by a\n * {@link HostPolicy}, never by app code directly, because the CHOICE between the strict policy and\n * the internal-addresses one is made by naming a host-policy class at the `new ClientConfig(...)`\n * call site. That keeps the permissive answer a greppable noun rather than a boolean somebody\n * flipped.\n */\nexport class SsrfPolicy {\n    constructor(\n        /**\n         * URL schemes that may be sent to, with their colons ('https:'). HTTPS-only by default: a\n         * partner-registered destination reached over plaintext http leaks the payload and its\n         * signature to anything on the path, and \"the partner has not got TLS yet\" is their bug to\n         * fix, not ours to accommodate silently.\n         */\n        public readonly allowedSchemes: ReadonlySet<string>,\n        /**\n         * TRUE only under {@link RuntimeHostFromContextAllowingInternalAddresses}. When true, the\n         * loopback / RFC1918 / link-local / metadata refusals are skipped — scheme checking and the\n         * redirect cap still apply.\n         */\n        public readonly allowInternalAddresses: boolean,\n        /**\n         * How many redirects may be followed, each one re-judged under this same policy. Small on\n         * purpose: a legitimate webhook endpoint does not need a redirect chain, and every hop is\n         * another chance for the destination to move somewhere we did not agree to.\n         */\n        public readonly maxRedirects: number,\n        /**\n         * WHY internal addresses are allowed, in prose, when they are. Required by\n         * {@link RuntimeHostFromContextAllowingInternalAddresses} and quoted in the log line the\n         * guard writes, so the reason travels with the decision instead of living in a commit\n         * message nobody will find.\n         */\n        public readonly allowInternalReason: string | undefined,\n    ) {}\n}\n"]}

package/src/SsrfRefusedError.d.ts

@@ -0,0 +1,20 @@
+/**
+ * We refused to SEND a request, because the destination failed this client's SSRF policy.
+ *
+ * Its own type rather than a bare Error so an app can tell "the partner's endpoint rejected us"
+ * (an HttpError carrying their status) from "we never contacted the partner at all" — those are
+ * different incidents with different owners, and only the second one means the URL in our database
+ * is hostile or wrong. A delivery worker typically dead-letters this instead of retrying: no number
+ * of retries makes 127.0.0.1 an acceptable destination.
+ *
+ * The message names the URL, the address it resolved to when that is what condemned it, and the
+ * ONE named opt-out that would allow it — so the reader does not have to go looking for whether an
+ * escape exists.
+ */
+export declare class SsrfRefusedError extends Error {
+    /** The URL that was refused, verbatim, so a log line identifies the offending row. */
+    readonly refusedUrl: string;
+    constructor(message: string, 
+    /** The URL that was refused, verbatim, so a log line identifies the offending row. */
+    refusedUrl: string);
+}

package/src/SsrfRefusedError.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SsrfRefusedError = void 0;
+/**
+ * We refused to SEND a request, because the destination failed this client's SSRF policy.
+ *
+ * Its own type rather than a bare Error so an app can tell "the partner's endpoint rejected us"
+ * (an HttpError carrying their status) from "we never contacted the partner at all" — those are
+ * different incidents with different owners, and only the second one means the URL in our database
+ * is hostile or wrong. A delivery worker typically dead-letters this instead of retrying: no number
+ * of retries makes 127.0.0.1 an acceptable destination.
+ *
+ * The message names the URL, the address it resolved to when that is what condemned it, and the
+ * ONE named opt-out that would allow it — so the reader does not have to go looking for whether an
+ * escape exists.
+ */
+class SsrfRefusedError extends Error {
+    refusedUrl;
+    constructor(message, 
+    /** The URL that was refused, verbatim, so a log line identifies the offending row. */
+    refusedUrl) {
+        super(message);
+        this.refusedUrl = refusedUrl;
+        this.name = 'SsrfRefusedError';
+    }
+}
+exports.SsrfRefusedError = SsrfRefusedError;
+//# sourceMappingURL=SsrfRefusedError.js.map

package/src/SsrfRefusedError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SsrfRefusedError.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/SsrfRefusedError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IAInB;IAHpB,YACI,OAAe;IACf,sFAAsF;IACtE,UAAkB;QAElC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,eAAU,GAAV,UAAU,CAAQ;QAGlC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACnC,CAAC;CACJ;AATD,4CASC","sourcesContent":["/**\n * We refused to SEND a request, because the destination failed this client's SSRF policy.\n *\n * Its own type rather than a bare Error so an app can tell \"the partner's endpoint rejected us\"\n * (an HttpError carrying their status) from \"we never contacted the partner at all\" — those are\n * different incidents with different owners, and only the second one means the URL in our database\n * is hostile or wrong. A delivery worker typically dead-letters this instead of retrying: no number\n * of retries makes 127.0.0.1 an acceptable destination.\n *\n * The message names the URL, the address it resolved to when that is what condemned it, and the\n * ONE named opt-out that would allow it — so the reader does not have to go looking for whether an\n * escape exists.\n */\nexport class SsrfRefusedError extends Error {\n    constructor(\n        message: string,\n        /** The URL that was refused, verbatim, so a log line identifies the offending row. */\n        public readonly refusedUrl: string,\n    ) {\n        super(message);\n        this.name = 'SsrfRefusedError';\n    }\n}\n"]}

package/src/index.d.ts

@@ -14,12 +14,26 @@
  * import { ClientHttpFactory, ClientConfig } from '@webpieces/http-client-node';
  *
  * // inject the factory, then one client per contract
- * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2'));
+ * const server2 = factory.createRpcClient(
+ *     Server2Api,
+ *     new ClientConfig('server2', new DeployedServiceHost()),
+ *     [],   // this client's outbound filters
+ * );
  * const response = await server2.fetchValue(req);
  * ```
  */
 export { ClientHttpFactory } from './ClientHttpFactory';
 export { NodeProxyClient, NODE_PROXY_CLIENT_PROVIDER } from './NodeProxyClient';
 export { ClientConfig } from './ClientConfig';
+export { HostPolicy, DeployedServiceHost, RuntimeHostFromContext, RuntimeHostFromContextAllowingInternalAddresses } from './HostPolicy';
+export { SsrfPolicy } from './SsrfPolicy';
+export { SsrfGuardFilter } from './SsrfGuardFilter';
+export { SsrfRefusedError } from './SsrfRefusedError';
+export { RuntimeHostEndpointUnsupportedError, MissingRuntimeBaseUrlError } from './RuntimeHostErrors';
+export { InternalAddressRules } from './InternalAddressRules';
+export { AddressResolver, DnsAddressResolver } from './AddressResolver';
+export { ContextBaseUrlOverrideFilter, BASE_URL_OVERRIDE_PRIORITY, SSRF_GUARD_PRIORITY } from './ContextBaseUrlOverrideFilter';
 export { ProxyClient, ClientErrorTranslator, TranslatedFailure } from '@webpieces/http-client-core';
+export { ClientRequest, ClientFilterDefinition } from '@webpieces/http-client-core';
+export type { ClientFilter } from '@webpieces/http-client-core';
 export type { ApiPrototype } from '@webpieces/http-client-core';