@webpieces/http-client-node 0.4.699 → 0.4.700

package/src/HostPolicy.d.ts

@@ -0,0 +1,118 @@
+import { AuthMeta } from '@webpieces/core-util';
+import { ClientFilterDefinition } from '@webpieces/http-client-core';
+import { AddressResolver } from './AddressResolver';
+/**
+ * WHERE a client's requests go — the second half of a {@link ClientConfig}, and a REQUIRED one.
+ *
+ * There are exactly two kinds of destination, and conflating them is what made outbound partner
+ * webhooks fall out of the typed world entirely:
+ *
+ * - a service WE DEPLOY, named by `svcName` and resolved through {@link ClientRegistry}
+ *   → {@link DeployedServiceHost}
+ * - a host that is DATA — a URL a partner registered, an OAuth callback, a per-tenant or
+ *   self-hosted instance — supplied per call through the RequestContext
+ *   → {@link RuntimeHostFromContext}
+ *
+ * Naming one is not optional, because the two carry completely different risk. A deployed peer is
+ * an address we chose; a runtime host is attacker-influenced data, and the framework owes it an
+ * SSRF policy. Making the choice a class the caller writes down means
+ * `grep -rn RuntimeHostFromContext` enumerates every client in the codebase that can be re-pointed
+ * at all — which is the question a security review actually asks.
+ */
+export declare abstract class HostPolicy {
+    /**
+     * The base URL this call STARTS from, before any filter re-points it.
+     *
+     * For a deployed service that is the whole answer. For a runtime host it is the empty string:
+     * there is nothing to resolve at this point, and {@link ContextBaseUrlOverrideFilter} — which
+     * this policy also installs — supplies the real destination inside the chain, or refuses. The
+     * empty seed is never sent: the override filter throws when the context carries no URL, and the
+     * SSRF guard refuses anything that is not an absolute https URL.
+     */
+    abstract resolveBaseUrl(svcName: string): Promise<string>;
+    /** The framework filters this policy installs, in addition to whatever the app passed. */
+    abstract builtInFilters(): ClientFilterDefinition[];
+    /**
+     * Reject, at BIND time, an endpoint this policy cannot honestly satisfy.
+     *
+     * @throws Error naming the endpoint and why. The default accepts everything.
+     */
+    assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string, _contractName: string): void;
+}
+/**
+ * TODAY'S BEHAVIOUR, unchanged and byte for byte: the destination is a service we deploy, and its
+ * URL comes from {@link ClientRegistry} — a registered mapping, else the installed deriver, else a
+ * throw.
+ *
+ * It installs NO filters, reads no context key, and performs no DNS lookups, so a client written
+ * this way runs the exact code path it ran before the outbound chain existed. This is the one to
+ * reach for; the runtime ones are for the case where the address genuinely is not knowable at
+ * build time.
+ */
+export declare class DeployedServiceHost extends HostPolicy {
+    resolveBaseUrl(svcName: string): Promise<string>;
+    builtInFilters(): ClientFilterDefinition[];
+}
+/**
+ * The destination is supplied PER CALL, through
+ * `RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, url)`, and the framework's
+ * SSRF policy is ON.
+ *
+ * ```ts
+ * const partner = factory.createRpcClient(
+ *     PartnerWebhookApi,
+ *     new ClientConfig('partner-webhooks', new RuntimeHostFromContext(new DnsAddressResolver())),
+ *     [new ClientFilterDefinition(500, new HmacSigningFilter(secret))],
+ * );
+ *
+ * for (const webhook of webhooks) {
+ *     await RequestContext.run(() => {
+ *         RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);
+ *         return partner.deliver(envelope);
+ *     });
+ * }
+ * ```
+ *
+ * `svcName` is still required, and still means something: it is the IDENTITY this client gets as a
+ * node on the runtime architecture graph. That is the whole point of routing partner deliveries
+ * back through a generated client — the most security-sensitive hop in the system stops being
+ * invisible.
+ *
+ * Endpoints whose auth mode is `@AuthOidc` or `@AuthSharedSecret` are REFUSED at bind time. Both
+ * mint a credential for a specific audience/peer that we chose, and there is no honest audience for
+ * a host we will not know until the call happens — minting one for a partner's URL would hand them
+ * a token. Authenticate a runtime-host call the way a webhook is actually authenticated: a signing
+ * filter over the exact bytes.
+ */
+export declare class RuntimeHostFromContext extends HostPolicy {
+    private readonly addressResolver;
+    constructor(addressResolver: AddressResolver);
+    resolveBaseUrl(_svcName: string): Promise<string>;
+    builtInFilters(): ClientFilterDefinition[];
+    assertEndpointSupported(authMeta: AuthMeta | undefined, methodName: string, contractName: string): void;
+    /** HTTPS only, no internal addresses, at most one redirect — each hop re-judged. */
+    private static readonly STRICT;
+}
+/**
+ * {@link RuntimeHostFromContext}, with the internal-address refusals SWITCHED OFF and plaintext
+ * http allowed — for a local emulator, an on-cluster service, or a test harness whose "partner" is
+ * `http://127.0.0.1:9123`.
+ *
+ * The long name is the feature. This is the permissive branch, so it is a NOUN a reviewer can grep
+ * (`grep -rn AllowingInternalAddresses` lists every client that can reach inside the network with a
+ * runtime-supplied URL) rather than a boolean, an omitted argument, or an empty allow-list — a
+ * widening that reads as an ABSENCE is invisible exactly where it matters most.
+ *
+ * The `reason` is required and is quoted back in this client's refusal messages, so the
+ * justification travels with the decision instead of living in a commit message.
+ */
+export declare class RuntimeHostFromContextAllowingInternalAddresses extends HostPolicy {
+    private readonly addressResolver;
+    private readonly policy;
+    constructor(
+    /** WHY this client may reach internal addresses, in prose. Required. */
+    reason: string, addressResolver: AddressResolver);
+    resolveBaseUrl(_svcName: string): Promise<string>;
+    builtInFilters(): ClientFilterDefinition[];
+    assertEndpointSupported(authMeta: AuthMeta | undefined, methodName: string, contractName: string): void;
+}

package/src/HostPolicy.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeHostFromContextAllowingInternalAddresses = exports.RuntimeHostFromContext = exports.DeployedServiceHost = exports.HostPolicy = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const http_client_core_1 = require("@webpieces/http-client-core");
+const ContextBaseUrlOverrideFilter_1 = require("./ContextBaseUrlOverrideFilter");
+const SsrfGuardFilter_1 = require("./SsrfGuardFilter");
+const SsrfPolicy_1 = require("./SsrfPolicy");
+const RuntimeHostErrors_1 = require("./RuntimeHostErrors");
+/**
+ * WHERE a client's requests go — the second half of a {@link ClientConfig}, and a REQUIRED one.
+ *
+ * There are exactly two kinds of destination, and conflating them is what made outbound partner
+ * webhooks fall out of the typed world entirely:
+ *
+ * - a service WE DEPLOY, named by `svcName` and resolved through {@link ClientRegistry}
+ *   → {@link DeployedServiceHost}
+ * - a host that is DATA — a URL a partner registered, an OAuth callback, a per-tenant or
+ *   self-hosted instance — supplied per call through the RequestContext
+ *   → {@link RuntimeHostFromContext}
+ *
+ * Naming one is not optional, because the two carry completely different risk. A deployed peer is
+ * an address we chose; a runtime host is attacker-influenced data, and the framework owes it an
+ * SSRF policy. Making the choice a class the caller writes down means
+ * `grep -rn RuntimeHostFromContext` enumerates every client in the codebase that can be re-pointed
+ * at all — which is the question a security review actually asks.
+ */
+class HostPolicy {
+    /**
+     * Reject, at BIND time, an endpoint this policy cannot honestly satisfy.
+     *
+     * @throws Error naming the endpoint and why. The default accepts everything.
+     */
+    assertEndpointSupported(_authMeta, _methodName, _contractName) { }
+}
+exports.HostPolicy = HostPolicy;
+/**
+ * TODAY'S BEHAVIOUR, unchanged and byte for byte: the destination is a service we deploy, and its
+ * URL comes from {@link ClientRegistry} — a registered mapping, else the installed deriver, else a
+ * throw.
+ *
+ * It installs NO filters, reads no context key, and performs no DNS lookups, so a client written
+ * this way runs the exact code path it ran before the outbound chain existed. This is the one to
+ * reach for; the runtime ones are for the case where the address genuinely is not knowable at
+ * build time.
+ */
+class DeployedServiceHost extends HostPolicy {
+    resolveBaseUrl(svcName) {
+        return core_util_1.ClientRegistry.resolve(svcName);
+    }
+    builtInFilters() {
+        return [];
+    }
+}
+exports.DeployedServiceHost = DeployedServiceHost;
+/**
+ * The destination is supplied PER CALL, through
+ * `RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, url)`, and the framework's
+ * SSRF policy is ON.
+ *
+ * ```ts
+ * const partner = factory.createRpcClient(
+ *     PartnerWebhookApi,
+ *     new ClientConfig('partner-webhooks', new RuntimeHostFromContext(new DnsAddressResolver())),
+ *     [new ClientFilterDefinition(500, new HmacSigningFilter(secret))],
+ * );
+ *
+ * for (const webhook of webhooks) {
+ *     await RequestContext.run(() => {
+ *         RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);
+ *         return partner.deliver(envelope);
+ *     });
+ * }
+ * ```
+ *
+ * `svcName` is still required, and still means something: it is the IDENTITY this client gets as a
+ * node on the runtime architecture graph. That is the whole point of routing partner deliveries
+ * back through a generated client — the most security-sensitive hop in the system stops being
+ * invisible.
+ *
+ * Endpoints whose auth mode is `@AuthOidc` or `@AuthSharedSecret` are REFUSED at bind time. Both
+ * mint a credential for a specific audience/peer that we chose, and there is no honest audience for
+ * a host we will not know until the call happens — minting one for a partner's URL would hand them
+ * a token. Authenticate a runtime-host call the way a webhook is actually authenticated: a signing
+ * filter over the exact bytes.
+ */
+class RuntimeHostFromContext extends HostPolicy {
+    addressResolver;
+    constructor(addressResolver) {
+        super();
+        this.addressResolver = addressResolver;
+    }
+    async resolveBaseUrl(_svcName) {
+        return '';
+    }
+    builtInFilters() {
+        return runtimeHostFilters(this.addressResolver, RuntimeHostFromContext.STRICT);
+    }
+    assertEndpointSupported(authMeta, methodName, contractName) {
+        assertNoServiceCredential(authMeta, methodName, contractName);
+    }
+    /** HTTPS only, no internal addresses, at most one redirect — each hop re-judged. */
+    static STRICT = new SsrfPolicy_1.SsrfPolicy(new Set(['https:']), false, 1, undefined);
+}
+exports.RuntimeHostFromContext = RuntimeHostFromContext;
+/**
+ * {@link RuntimeHostFromContext}, with the internal-address refusals SWITCHED OFF and plaintext
+ * http allowed — for a local emulator, an on-cluster service, or a test harness whose "partner" is
+ * `http://127.0.0.1:9123`.
+ *
+ * The long name is the feature. This is the permissive branch, so it is a NOUN a reviewer can grep
+ * (`grep -rn AllowingInternalAddresses` lists every client that can reach inside the network with a
+ * runtime-supplied URL) rather than a boolean, an omitted argument, or an empty allow-list — a
+ * widening that reads as an ABSENCE is invisible exactly where it matters most.
+ *
+ * The `reason` is required and is quoted back in this client's refusal messages, so the
+ * justification travels with the decision instead of living in a commit message.
+ */
+class RuntimeHostFromContextAllowingInternalAddresses extends HostPolicy {
+    addressResolver;
+    policy;
+    constructor(
+    /** WHY this client may reach internal addresses, in prose. Required. */
+    reason, addressResolver) {
+        super();
+        this.addressResolver = addressResolver;
+        this.policy = new SsrfPolicy_1.SsrfPolicy(new Set(['https:', 'http:']), true, 1, reason);
+    }
+    async resolveBaseUrl(_svcName) {
+        return '';
+    }
+    builtInFilters() {
+        return runtimeHostFilters(this.addressResolver, this.policy);
+    }
+    assertEndpointSupported(authMeta, methodName, contractName) {
+        assertNoServiceCredential(authMeta, methodName, contractName);
+    }
+}
+exports.RuntimeHostFromContextAllowingInternalAddresses = RuntimeHostFromContextAllowingInternalAddresses;
+/**
+ * The two built-ins every runtime-host client gets: settle the destination from the context, then
+ * judge it. Shared by both runtime policies so the ORDER cannot drift between them — a guard that
+ * ran before the override would be judging the wrong URL.
+ */
+// webpieces-disable no-function-outside-class -- shared construction of two filter definitions; it holds no state a class could own
+function runtimeHostFilters(addressResolver, policy) {
+    return [
+        new http_client_core_1.ClientFilterDefinition(ContextBaseUrlOverrideFilter_1.BASE_URL_OVERRIDE_PRIORITY, new ContextBaseUrlOverrideFilter_1.ContextBaseUrlOverrideFilter()),
+        new http_client_core_1.ClientFilterDefinition(ContextBaseUrlOverrideFilter_1.SSRF_GUARD_PRIORITY, new SsrfGuardFilter_1.SsrfGuardFilter(policy, addressResolver)),
+    ];
+}
+/**
+ * @throws Error when the endpoint expects a credential minted for an audience we choose. Shared by
+ *         both runtime policies for the same reason {@link runtimeHostFilters} is.
+ */
+// webpieces-disable no-function-outside-class -- shared bind-time assertion; it holds no state a class could own
+function assertNoServiceCredential(authMeta, methodName, contractName) {
+    const kind = authMeta?.mode?.kind;
+    if (kind !== 'oidc' && kind !== 'shared-secret') {
+        return;
+    }
+    throw new RuntimeHostErrors_1.RuntimeHostEndpointUnsupportedError(`${contractName}.${methodName} is authenticated with '${kind}', which cannot be used by a ` +
+        `runtime-host client. Both mint a credential for a peer WE chose — an OIDC token's audience is ` +
+        `the callee's base URL, and a shared secret is one we agreed with a named service — and the ` +
+        `destination here is not known until the call happens, so minting either one would hand our ` +
+        `credential to whoever registered the URL. Authenticate this hop the way a webhook actually is ` +
+        `authenticated: an app filter that signs the exact serialized bytes (ClientRequest.body).`, `${contractName}.${methodName}`);
+}
+//# sourceMappingURL=HostPolicy.js.map

package/src/HostPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HostPolicy.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/HostPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["import { AuthMeta, ClientRegistry } from '@webpieces/core-util';\nimport { ClientFilterDefinition } from '@webpieces/http-client-core';\nimport { AddressResolver } from './AddressResolver';\nimport { BASE_URL_OVERRIDE_PRIORITY, ContextBaseUrlOverrideFilter, SSRF_GUARD_PRIORITY } from './ContextBaseUrlOverrideFilter';\nimport { SsrfGuardFilter } from './SsrfGuardFilter';\nimport { SsrfPolicy } from './SsrfPolicy';\nimport { RuntimeHostEndpointUnsupportedError } from './RuntimeHostErrors';\n\n/**\n * WHERE a client's requests go — the second half of a {@link ClientConfig}, and a REQUIRED one.\n *\n * There are exactly two kinds of destination, and conflating them is what made outbound partner\n * webhooks fall out of the typed world entirely:\n *\n * - a service WE DEPLOY, named by `svcName` and resolved through {@link ClientRegistry}\n *   → {@link DeployedServiceHost}\n * - a host that is DATA — a URL a partner registered, an OAuth callback, a per-tenant or\n *   self-hosted instance — supplied per call through the RequestContext\n *   → {@link RuntimeHostFromContext}\n *\n * Naming one is not optional, because the two carry completely different risk. A deployed peer is\n * an address we chose; a runtime host is attacker-influenced data, and the framework owes it an\n * SSRF policy. Making the choice a class the caller writes down means\n * `grep -rn RuntimeHostFromContext` enumerates every client in the codebase that can be re-pointed\n * at all — which is the question a security review actually asks.\n */\nexport abstract class HostPolicy {\n    /**\n     * The base URL this call STARTS from, before any filter re-points it.\n     *\n     * For a deployed service that is the whole answer. For a runtime host it is the empty string:\n     * there is nothing to resolve at this point, and {@link ContextBaseUrlOverrideFilter} — which\n     * this policy also installs — supplies the real destination inside the chain, or refuses. The\n     * empty seed is never sent: the override filter throws when the context carries no URL, and the\n     * SSRF guard refuses anything that is not an absolute https URL.\n     */\n    abstract resolveBaseUrl(svcName: string): Promise<string>;\n\n    /** The framework filters this policy installs, in addition to whatever the app passed. */\n    abstract builtInFilters(): ClientFilterDefinition[];\n\n    /**\n     * Reject, at BIND time, an endpoint this policy cannot honestly satisfy.\n     *\n     * @throws Error naming the endpoint and why. The default accepts everything.\n     */\n    assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string, _contractName: string): void {}\n}\n\n/**\n * TODAY'S BEHAVIOUR, unchanged and byte for byte: the destination is a service we deploy, and its\n * URL comes from {@link ClientRegistry} — a registered mapping, else the installed deriver, else a\n * throw.\n *\n * It installs NO filters, reads no context key, and performs no DNS lookups, so a client written\n * this way runs the exact code path it ran before the outbound chain existed. This is the one to\n * reach for; the runtime ones are for the case where the address genuinely is not knowable at\n * build time.\n */\nexport class DeployedServiceHost extends HostPolicy {\n    override resolveBaseUrl(svcName: string): Promise<string> {\n        return ClientRegistry.resolve(svcName);\n    }\n\n    override builtInFilters(): ClientFilterDefinition[] {\n        return [];\n    }\n}\n\n/**\n * The destination is supplied PER CALL, through\n * `RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, url)`, and the framework's\n * SSRF policy is ON.\n *\n * ```ts\n * const partner = factory.createRpcClient(\n *     PartnerWebhookApi,\n *     new ClientConfig('partner-webhooks', new RuntimeHostFromContext(new DnsAddressResolver())),\n *     [new ClientFilterDefinition(500, new HmacSigningFilter(secret))],\n * );\n *\n * for (const webhook of webhooks) {\n *     await RequestContext.run(() => {\n *         RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);\n *         return partner.deliver(envelope);\n *     });\n * }\n * ```\n *\n * `svcName` is still required, and still means something: it is the IDENTITY this client gets as a\n * node on the runtime architecture graph. That is the whole point of routing partner deliveries\n * back through a generated client — the most security-sensitive hop in the system stops being\n * invisible.\n *\n * Endpoints whose auth mode is `@AuthOidc` or `@AuthSharedSecret` are REFUSED at bind time. Both\n * mint a credential for a specific audience/peer that we chose, and there is no honest audience for\n * a host we will not know until the call happens — minting one for a partner's URL would hand them\n * a token. Authenticate a runtime-host call the way a webhook is actually authenticated: a signing\n * filter over the exact bytes.\n */\nexport class RuntimeHostFromContext extends HostPolicy {\n    constructor(private readonly addressResolver: AddressResolver) {\n        super();\n    }\n\n    override async resolveBaseUrl(_svcName: string): Promise<string> {\n        return '';\n    }\n\n    override builtInFilters(): ClientFilterDefinition[] {\n        return runtimeHostFilters(this.addressResolver, RuntimeHostFromContext.STRICT);\n    }\n\n    override assertEndpointSupported(\n        authMeta: AuthMeta | undefined,\n        methodName: string,\n        contractName: string,\n    ): void {\n        assertNoServiceCredential(authMeta, methodName, contractName);\n    }\n\n    /** HTTPS only, no internal addresses, at most one redirect — each hop re-judged. */\n    private static readonly STRICT = new SsrfPolicy(new Set(['https:']), false, 1, undefined);\n}\n\n/**\n * {@link RuntimeHostFromContext}, with the internal-address refusals SWITCHED OFF and plaintext\n * http allowed — for a local emulator, an on-cluster service, or a test harness whose \"partner\" is\n * `http://127.0.0.1:9123`.\n *\n * The long name is the feature. This is the permissive branch, so it is a NOUN a reviewer can grep\n * (`grep -rn AllowingInternalAddresses` lists every client that can reach inside the network with a\n * runtime-supplied URL) rather than a boolean, an omitted argument, or an empty allow-list — a\n * widening that reads as an ABSENCE is invisible exactly where it matters most.\n *\n * The `reason` is required and is quoted back in this client's refusal messages, so the\n * justification travels with the decision instead of living in a commit message.\n */\nexport class RuntimeHostFromContextAllowingInternalAddresses extends HostPolicy {\n    private readonly policy: SsrfPolicy;\n\n    constructor(\n        /** WHY this client may reach internal addresses, in prose. Required. */\n        reason: string,\n        private readonly addressResolver: AddressResolver,\n    ) {\n        super();\n        this.policy = new SsrfPolicy(new Set(['https:', 'http:']), true, 1, reason);\n    }\n\n    override async resolveBaseUrl(_svcName: string): Promise<string> {\n        return '';\n    }\n\n    override builtInFilters(): ClientFilterDefinition[] {\n        return runtimeHostFilters(this.addressResolver, this.policy);\n    }\n\n    override assertEndpointSupported(\n        authMeta: AuthMeta | undefined,\n        methodName: string,\n        contractName: string,\n    ): void {\n        assertNoServiceCredential(authMeta, methodName, contractName);\n    }\n}\n\n/**\n * The two built-ins every runtime-host client gets: settle the destination from the context, then\n * judge it. Shared by both runtime policies so the ORDER cannot drift between them — a guard that\n * ran before the override would be judging the wrong URL.\n */\n// webpieces-disable no-function-outside-class -- shared construction of two filter definitions; it holds no state a class could own\nfunction runtimeHostFilters(addressResolver: AddressResolver, policy: SsrfPolicy): ClientFilterDefinition[] {\n    return [\n        new ClientFilterDefinition(BASE_URL_OVERRIDE_PRIORITY, new ContextBaseUrlOverrideFilter()),\n        new ClientFilterDefinition(SSRF_GUARD_PRIORITY, new SsrfGuardFilter(policy, addressResolver)),\n    ];\n}\n\n/**\n * @throws Error when the endpoint expects a credential minted for an audience we choose. Shared by\n *         both runtime policies for the same reason {@link runtimeHostFilters} is.\n */\n// webpieces-disable no-function-outside-class -- shared bind-time assertion; it holds no state a class could own\nfunction assertNoServiceCredential(\n    authMeta: AuthMeta | undefined,\n    methodName: string,\n    contractName: string,\n): void {\n    const kind = authMeta?.mode?.kind;\n    if (kind !== 'oidc' && kind !== 'shared-secret') {\n        return;\n    }\n    throw new RuntimeHostEndpointUnsupportedError(\n        `${contractName}.${methodName} is authenticated with '${kind}', which cannot be used by a ` +\n            `runtime-host client. Both mint a credential for a peer WE chose — an OIDC token's audience is ` +\n            `the callee's base URL, and a shared secret is one we agreed with a named service — and the ` +\n            `destination here is not known until the call happens, so minting either one would hand our ` +\n            `credential to whoever registered the URL. Authenticate this hop the way a webhook actually is ` +\n            `authenticated: an app filter that signs the exact serialized bytes (ClientRequest.body).`,\n        `${contractName}.${methodName}`,\n    );\n}\n"]}

package/src/InternalAddressRules.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which IP addresses count as INTERNAL — i.e. reachable only because of where our process happens
+ * to sit, and therefore never a legitimate destination for a URL a partner supplied.
+ *
+ * Pure and dependency-free (it judges an address string, it does not resolve one), so it is unit
+ * testable without DNS and is shared by the URL check and the redirect check.
+ *
+ * The list is deliberately WIDER than "RFC1918". A consumer running on a VPC connector can reach a
+ * great deal more than 10/8, and the address that actually gets stolen in practice is
+ * `169.254.169.254` — the cloud metadata service, which hands out the runtime service account's
+ * tokens to anything that asks.
+ */
+export declare class InternalAddressRules {
+    /** IPv4 CIDRs that are internal, as [network, prefix length]. */
+    private static readonly V4_BLOCKS;
+    /**
+     * Hostnames that are internal by NAME, independent of what they resolve to. Checked before DNS
+     * because the metadata service answers to its name inside every GCP VM and the name is what
+     * appears in a copy-pasted URL.
+     */
+    private static readonly INTERNAL_HOSTNAMES;
+    /** True when `hostname` is internal by name alone (no DNS needed). */
+    isInternalHostname(hostname: string): boolean;
+    /**
+     * True when `address` is an internal IP. Accepts IPv4 dotted-quad and IPv6 (including the
+     * IPv4-mapped `::ffff:a.b.c.d` form, which is how a dual-stack resolver reports an IPv4 answer
+     * and therefore the obvious way to smuggle 127.0.0.1 past an IPv4-only check).
+     *
+     * An address it cannot parse is treated as INTERNAL. Unparseable means "we do not know what this
+     * is", and the safe answer to that on the SSRF path is refusal, not delivery.
+     */
+    isInternalAddress(address: string): boolean;
+    private isInternalV4;
+    private isInternalV6;
+    /** The dotted quad as a 32-bit number, or undefined when it is not a dotted quad at all. */
+    private toV4Number;
+}

package/src/InternalAddressRules.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternalAddressRules = void 0;
+/**
+ * Which IP addresses count as INTERNAL — i.e. reachable only because of where our process happens
+ * to sit, and therefore never a legitimate destination for a URL a partner supplied.
+ *
+ * Pure and dependency-free (it judges an address string, it does not resolve one), so it is unit
+ * testable without DNS and is shared by the URL check and the redirect check.
+ *
+ * The list is deliberately WIDER than "RFC1918". A consumer running on a VPC connector can reach a
+ * great deal more than 10/8, and the address that actually gets stolen in practice is
+ * `169.254.169.254` — the cloud metadata service, which hands out the runtime service account's
+ * tokens to anything that asks.
+ */
+class InternalAddressRules {
+    /** IPv4 CIDRs that are internal, as [network, prefix length]. */
+    static V4_BLOCKS = [
+        ['0.0.0.0', 8], //        "this network" — 0.x is routed to localhost by some stacks
+        ['10.0.0.0', 8], //       RFC1918 private
+        ['100.64.0.0', 10], //    RFC6598 carrier-grade NAT — a shared-tenant range, never ours to trust
+        ['127.0.0.0', 8], //      loopback
+        ['169.254.0.0', 16], //   link-local, and with it 169.254.169.254 CLOUD METADATA
+        ['172.16.0.0', 12], //    RFC1918 private
+        ['192.0.0.0', 24], //     IETF protocol assignments
+        ['192.0.2.0', 24], //     TEST-NET-1
+        ['192.168.0.0', 16], //   RFC1918 private
+        ['198.18.0.0', 15], //    benchmarking
+        ['198.51.100.0', 24], //  TEST-NET-2
+        ['203.0.113.0', 24], //   TEST-NET-3
+        ['224.0.0.0', 4], //      multicast
+        ['240.0.0.0', 4], //      reserved, incl. 255.255.255.255 broadcast
+    ];
+    /**
+     * Hostnames that are internal by NAME, independent of what they resolve to. Checked before DNS
+     * because the metadata service answers to its name inside every GCP VM and the name is what
+     * appears in a copy-pasted URL.
+     */
+    static INTERNAL_HOSTNAMES = new Set([
+        'localhost',
+        'metadata',
+        'metadata.google.internal',
+        'metadata.goog',
+        'instance-data',
+    ]);
+    /** True when `hostname` is internal by name alone (no DNS needed). */
+    isInternalHostname(hostname) {
+        const lower = hostname.toLowerCase().replace(/\.$/, '');
+        if (InternalAddressRules.INTERNAL_HOSTNAMES.has(lower)) {
+            return true;
+        }
+        // Any *.internal / *.localhost name is infrastructure-local by convention.
+        return lower.endsWith('.internal') || lower.endsWith('.localhost');
+    }
+    /**
+     * True when `address` is an internal IP. Accepts IPv4 dotted-quad and IPv6 (including the
+     * IPv4-mapped `::ffff:a.b.c.d` form, which is how a dual-stack resolver reports an IPv4 answer
+     * and therefore the obvious way to smuggle 127.0.0.1 past an IPv4-only check).
+     *
+     * An address it cannot parse is treated as INTERNAL. Unparseable means "we do not know what this
+     * is", and the safe answer to that on the SSRF path is refusal, not delivery.
+     */
+    isInternalAddress(address) {
+        const bare = address.replace(/^\[|\]$/g, '').split('%')[0];
+        if (bare.includes(':')) {
+            return this.isInternalV6(bare);
+        }
+        return this.isInternalV4(bare);
+    }
+    isInternalV4(address) {
+        const value = this.toV4Number(address);
+        if (value === undefined) {
+            return true;
+        }
+        for (const block of InternalAddressRules.V4_BLOCKS) {
+            const network = this.toV4Number(block[0]);
+            if (network === undefined) {
+                continue;
+            }
+            // A /0 mask would shift by 32, which is a no-op in JS — no block here uses one.
+            const mask = (0xffffffff << (32 - block[1])) >>> 0;
+            if ((value & mask) >>> 0 === (network & mask) >>> 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    isInternalV6(address) {
+        const lower = address.toLowerCase();
+        // A dual-stack resolver reports IPv4 as ::ffff:a.b.c.d — judge it as the IPv4 it is.
+        const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+        if (mapped) {
+            return this.isInternalV4(mapped[1]);
+        }
+        // …and the URL parser NORMALIZES that same address to its hex form, `::ffff:7f00:1`. Both
+        // spellings name 127.0.0.1, so both have to be judged as it — checking only the dotted form
+        // would let `https://[::ffff:127.0.0.1]` through the moment it went through `new URL()`.
+        const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(lower);
+        if (mappedHex) {
+            const high = parseInt(mappedHex[1], 16);
+            const low = parseInt(mappedHex[2], 16);
+            const dotted = `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
+            return this.isInternalV4(dotted);
+        }
+        if (lower === '::1' || lower === '::') {
+            return true;
+        }
+        // fc00::/7 unique-local, fe80::/10 link-local, ff00::/8 multicast.
+        return /^f[cd]/.test(lower) || /^fe[89ab]/.test(lower) || lower.startsWith('ff');
+    }
+    /** The dotted quad as a 32-bit number, or undefined when it is not a dotted quad at all. */
+    toV4Number(address) {
+        const parts = address.split('.');
+        if (parts.length !== 4) {
+            return undefined;
+        }
+        let value = 0;
+        for (const part of parts) {
+            if (!/^\d{1,3}$/.test(part)) {
+                return undefined;
+            }
+            const octet = Number(part);
+            if (octet > 255) {
+                return undefined;
+            }
+            value = (value * 256 + octet) >>> 0;
+        }
+        return value;
+    }
+}
+exports.InternalAddressRules = InternalAddressRules;
+//# sourceMappingURL=InternalAddressRules.js.map

package/src/InternalAddressRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InternalAddressRules.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/InternalAddressRules.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which IP addresses count as INTERNAL — i.e. reachable only because of where our process happens\n * to sit, and therefore never a legitimate destination for a URL a partner supplied.\n *\n * Pure and dependency-free (it judges an address string, it does not resolve one), so it is unit\n * testable without DNS and is shared by the URL check and the redirect check.\n *\n * The list is deliberately WIDER than \"RFC1918\". A consumer running on a VPC connector can reach a\n * great deal more than 10/8, and the address that actually gets stolen in practice is\n * `169.254.169.254` — the cloud metadata service, which hands out the runtime service account's\n * tokens to anything that asks.\n */\nexport class InternalAddressRules {\n    /** IPv4 CIDRs that are internal, as [network, prefix length]. */\n    private static readonly V4_BLOCKS: ReadonlyArray<readonly [string, number]> = [\n        ['0.0.0.0', 8], //        \"this network\" — 0.x is routed to localhost by some stacks\n        ['10.0.0.0', 8], //       RFC1918 private\n        ['100.64.0.0', 10], //    RFC6598 carrier-grade NAT — a shared-tenant range, never ours to trust\n        ['127.0.0.0', 8], //      loopback\n        ['169.254.0.0', 16], //   link-local, and with it 169.254.169.254 CLOUD METADATA\n        ['172.16.0.0', 12], //    RFC1918 private\n        ['192.0.0.0', 24], //     IETF protocol assignments\n        ['192.0.2.0', 24], //     TEST-NET-1\n        ['192.168.0.0', 16], //   RFC1918 private\n        ['198.18.0.0', 15], //    benchmarking\n        ['198.51.100.0', 24], //  TEST-NET-2\n        ['203.0.113.0', 24], //   TEST-NET-3\n        ['224.0.0.0', 4], //      multicast\n        ['240.0.0.0', 4], //      reserved, incl. 255.255.255.255 broadcast\n    ];\n\n    /**\n     * Hostnames that are internal by NAME, independent of what they resolve to. Checked before DNS\n     * because the metadata service answers to its name inside every GCP VM and the name is what\n     * appears in a copy-pasted URL.\n     */\n    private static readonly INTERNAL_HOSTNAMES: ReadonlySet<string> = new Set([\n        'localhost',\n        'metadata',\n        'metadata.google.internal',\n        'metadata.goog',\n        'instance-data',\n    ]);\n\n    /** True when `hostname` is internal by name alone (no DNS needed). */\n    isInternalHostname(hostname: string): boolean {\n        const lower = hostname.toLowerCase().replace(/\\.$/, '');\n        if (InternalAddressRules.INTERNAL_HOSTNAMES.has(lower)) {\n            return true;\n        }\n        // Any *.internal / *.localhost name is infrastructure-local by convention.\n        return lower.endsWith('.internal') || lower.endsWith('.localhost');\n    }\n\n    /**\n     * True when `address` is an internal IP. Accepts IPv4 dotted-quad and IPv6 (including the\n     * IPv4-mapped `::ffff:a.b.c.d` form, which is how a dual-stack resolver reports an IPv4 answer\n     * and therefore the obvious way to smuggle 127.0.0.1 past an IPv4-only check).\n     *\n     * An address it cannot parse is treated as INTERNAL. Unparseable means \"we do not know what this\n     * is\", and the safe answer to that on the SSRF path is refusal, not delivery.\n     */\n    isInternalAddress(address: string): boolean {\n        const bare = address.replace(/^\\[|\\]$/g, '').split('%')[0];\n        if (bare.includes(':')) {\n            return this.isInternalV6(bare);\n        }\n        return this.isInternalV4(bare);\n    }\n\n    private isInternalV4(address: string): boolean {\n        const value = this.toV4Number(address);\n        if (value === undefined) {\n            return true;\n        }\n        for (const block of InternalAddressRules.V4_BLOCKS) {\n            const network = this.toV4Number(block[0]);\n            if (network === undefined) {\n                continue;\n            }\n            // A /0 mask would shift by 32, which is a no-op in JS — no block here uses one.\n            const mask = (0xffffffff << (32 - block[1])) >>> 0;\n            if ((value & mask) >>> 0 === (network & mask) >>> 0) {\n                return true;\n            }\n        }\n        return false;\n    }\n\n    private isInternalV6(address: string): boolean {\n        const lower = address.toLowerCase();\n        // A dual-stack resolver reports IPv4 as ::ffff:a.b.c.d — judge it as the IPv4 it is.\n        const mapped = /^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/.exec(lower);\n        if (mapped) {\n            return this.isInternalV4(mapped[1]);\n        }\n        // …and the URL parser NORMALIZES that same address to its hex form, `::ffff:7f00:1`. Both\n        // spellings name 127.0.0.1, so both have to be judged as it — checking only the dotted form\n        // would let `https://[::ffff:127.0.0.1]` through the moment it went through `new URL()`.\n        const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(lower);\n        if (mappedHex) {\n            const high = parseInt(mappedHex[1], 16);\n            const low = parseInt(mappedHex[2], 16);\n            const dotted = `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;\n            return this.isInternalV4(dotted);\n        }\n        if (lower === '::1' || lower === '::') {\n            return true;\n        }\n        // fc00::/7 unique-local, fe80::/10 link-local, ff00::/8 multicast.\n        return /^f[cd]/.test(lower) || /^fe[89ab]/.test(lower) || lower.startsWith('ff');\n    }\n\n    /** The dotted quad as a 32-bit number, or undefined when it is not a dotted quad at all. */\n    private toV4Number(address: string): number | undefined {\n        const parts = address.split('.');\n        if (parts.length !== 4) {\n            return undefined;\n        }\n        let value = 0;\n        for (const part of parts) {\n            if (!/^\\d{1,3}$/.test(part)) {\n                return undefined;\n            }\n            const octet = Number(part);\n            if (octet > 255) {\n                return undefined;\n            }\n            value = (value * 256 + octet) >>> 0;\n        }\n        return value;\n    }\n}\n"]}

package/src/NodeProxyClient.d.ts

@@ -1,7 +1,7 @@
 import { AuthMeta, DestinationTrust, RouteMetadata, Secrets } from '@webpieces/core-util';
 import { RequestContextHeaders } from '@webpieces/core-context';
 import { GcpOidc } from '@webpieces/gcp-identity';
-import { ApiPrototype, ProxyClient, TranslatedFailure } from '@webpieces/http-client-core';
+import { ApiPrototype, ClientFilterDefinition, ProxyClient, TranslatedFailure } from '@webpieces/http-client-core';
 import { ClientConfig } from './ClientConfig';
 /**
  * The server-side {@link ProxyClient}. Everything a browser cannot do lives here: reading the
@@ -17,8 +17,14 @@ export declare class NodeProxyClient extends ProxyClient {
     private readonly secrets?;
     private config;
     constructor(headers: RequestContextHeaders, gcpOidc: GcpOidc, secrets?: Secrets | undefined);
-    /** Bind this client to one API contract + target. */
-    init(apiPrototype: ApiPrototype<object>, config: ClientConfig): void;
+    /**
+     * Bind this client to one API contract + target, with the app's outbound filters.
+     *
+     * `appFilters` is REQUIRED, not defaulted: an empty array is a statement that this client signs
+     * nothing and rewrites nothing, and it should be written down rather than inferred from an
+     * omitted argument.
+     */
+    init(apiPrototype: ApiPrototype<object>, config: ClientConfig, appFilters: ClientFilterDefinition[]): void;
     /**
      * The same chain every client runs — a ClientRegistry mapping, else the installed deriver — but
      * with NODE's fallback: THROW. A server has no "own origin" to fall back to the way a browser
@@ -28,6 +34,13 @@ export declare class NodeProxyClient extends ProxyClient {
      * read beneath a deriver is memoized process-wide, so only the first call pays.
      */
     protected resolveBaseUrl(): Promise<string>;
+    /**
+     * The framework filters this client's {@link HostPolicy} demands — none for a deployed service,
+     * the context override plus the SSRF guard for a runtime host. Delegated rather than decided
+     * here so the two halves of "where does this go" (resolution and enforcement) cannot drift
+     * apart into different policies.
+     */
+    protected clientFilters(): ClientFilterDefinition[];
     /**
      * Straight from the RequestContext. Throws when there is no active request scope.
      *
@@ -45,7 +58,7 @@ export declare class NodeProxyClient extends ProxyClient {
      * `Bearer <oidc>` / `Webpieces <secret>` — which is never a context key, so it cannot leak onto
      * the next hop. Never reads process.env.
      */
-    protected attachOutboundAuth(route: RouteMetadata, baseUrl: string, httpHeaders: Record<string, string>): Promise<void>;
+    protected attachOutboundAuth(route: RouteMetadata, baseUrl: string, httpHeaders: Map<string, string>): Promise<void>;
     /**
      * Test-case recording hook (mirror of Java HttpsJsonClientInvokeHandler): if a recorder is
      * travelling in the magic context, capture this outbound call + its result so it becomes a mock
@@ -59,8 +72,13 @@ export declare class NodeProxyClient extends ProxyClient {
      * from the call path — a logging backend stamps its own fields and never sees this.
      */
     private recordCall;
-    /** A server can satisfy every auth mode, so nothing is rejected at bind time. */
-    protected assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string): void;
+    /**
+     * A server can satisfy every auth mode when it is talking to a peer it CHOSE, so the deployed
+     * policy rejects nothing. A runtime-host policy does reject: an OIDC token's audience and a
+     * shared secret both name a peer, and a destination that arrives per call has no honest one —
+     * see {@link HostPolicy.assertEndpointSupported}.
+     */
+    protected assertEndpointSupported(authMeta: AuthMeta | undefined, methodName: string): void;
     /**
      * SERVER-TO-SERVER: a 4xx received from a dependency becomes THIS server's own 500.
      *

package/src/NodeProxyClient.js

@@ -26,10 +26,16 @@ let NodeProxyClient = class NodeProxyClient extends http_client_core_1.ProxyClie
         this.gcpOidc = gcpOidc;
         this.secrets = secrets;
     }
-    /** Bind this client to one API contract + target. */
-    init(apiPrototype, config) {
+    /**
+     * Bind this client to one API contract + target, with the app's outbound filters.
+     *
+     * `appFilters` is REQUIRED, not defaulted: an empty array is a statement that this client signs
+     * nothing and rewrites nothing, and it should be written down rather than inferred from an
+     * omitted argument.
+     */
+    init(apiPrototype, config, appFilters) {
         this.config = config;
-        this.initRoutes(apiPrototype);
+        this.initRoutes(apiPrototype, appFilters);
     }
     /**
      * The same chain every client runs — a ClientRegistry mapping, else the installed deriver — but
@@ -40,7 +46,16 @@ let NodeProxyClient = class NodeProxyClient extends http_client_core_1.ProxyClie
      * read beneath a deriver is memoized process-wide, so only the first call pays.
      */
     resolveBaseUrl() {
-        return core_util_1.ClientRegistry.resolve(this.config.svcName);
+        return this.config.hostPolicy.resolveBaseUrl(this.config.svcName);
+    }
+    /**
+     * The framework filters this client's {@link HostPolicy} demands — none for a deployed service,
+     * the context override plus the SSRF guard for a runtime host. Delegated rather than decided
+     * here so the two halves of "where does this go" (resolution and enforcement) cannot drift
+     * apart into different policies.
+     */
+    clientFilters() {
+        return this.config.hostPolicy.builtInFilters();
     }
     /**
      * Straight from the RequestContext. Throws when there is no active request scope.
@@ -64,7 +79,7 @@ let NodeProxyClient = class NodeProxyClient extends http_client_core_1.ProxyClie
     async attachOutboundAuth(route, baseUrl, httpHeaders) {
         const mode = route.authMeta?.mode;
         if (mode?.kind === 'oidc') {
-            httpHeaders['Authorization'] = `Bearer ${await this.gcpOidc.mintIdToken(baseUrl)}`;
+            httpHeaders.set('Authorization', `Bearer ${await this.gcpOidc.mintIdToken(baseUrl)}`);
         }
         else if (mode?.kind === 'shared-secret') {
             const secret = this.secrets?.get(mode.secretKey);
@@ -73,7 +88,7 @@ let NodeProxyClient = class NodeProxyClient extends http_client_core_1.ProxyClie
             }
             // Same header as a JWT/OIDC token, but its OWN scheme, so a secret can never be
             // mistaken for a token nor accepted where one was expected.
-            httpHeaders['Authorization'] = `Webpieces ${secret}`;
+            httpHeaders.set('Authorization', `Webpieces ${secret}`);
         }
     }
     /**
@@ -119,8 +134,15 @@ let NodeProxyClient = class NodeProxyClient extends http_client_core_1.ProxyClie
             throw err;
         }
     }
-    /** A server can satisfy every auth mode, so nothing is rejected at bind time. */
-    assertEndpointSupported(_authMeta, _methodName) { }
+    /**
+     * A server can satisfy every auth mode when it is talking to a peer it CHOSE, so the deployed
+     * policy rejects nothing. A runtime-host policy does reject: an OIDC token's audience and a
+     * shared secret both name a peer, and a destination that arrives per call has no honest one —
+     * see {@link HostPolicy.assertEndpointSupported}.
+     */
+    assertEndpointSupported(authMeta, methodName) {
+        this.config.hostPolicy.assertEndpointSupported(authMeta, methodName, this.contractName());
+    }
     /**
      * SERVER-TO-SERVER: a 4xx received from a dependency becomes THIS server's own 500.
      *