@webpieces/http-client-node 0.4.699 → 0.4.701

package/README.md

@@ -32,3 +32,108 @@ request-id chain loses the trace, and finding that out in production is worse th
 top-level server filter normally establishes the scope for you.
 
 The browser twin is [@webpieces/http-client-browser](../http-client-browser).
+
+## Outbound filters
+
+`createRpcClient`'s OPTIONAL third argument is this client's outbound filter chain — the same
+`Filter` / `Service` abstraction (from `@webpieces/core-util`) the server's inbound chain uses,
+pointed the other way. A filter receives a mutable `ClientRequest` and returns the `Response`, so it
+can rewrite the url, add or remove headers, log, or replace the serialized body:
+
+```ts
+class TenantHeaderFilter extends Filter<ClientRequest, Response> {
+    async filter(request: ClientRequest, next: Service<ClientRequest, Response>): Promise<Response> {
+        request.headers.set('x-tenant', currentTenant());
+        return next.invoke(request);
+    }
+}
+```
+
+Highest priority runs OUTERMOST, matching the server's `FilterMatcher`.
+
+**Priority orders YOUR filters against each other, and nothing else.** The framework's own built-ins
+— the SSRF guard, then the outbound credential minter — are appended BENEATH every app filter,
+structurally rather than by number, so no priority (not `Number.MAX_SAFE_INTEGER`) puts an app filter
+under them. They have to judge, and sign for, the URL that is actually about to be fetched.
+
+`request.body` is the EXACT serialized bytes the transport will send. That is the whole reason this
+seam exists: without it a webhook sender has to hand-serialize and post the payload itself, because a
+raw HTTP library that re-serializes internally signs one byte sequence and sends another.
+
+## A destination supplied at RUNTIME
+
+Some destinations are DATA, not deployment: a URL a partner registered (`OrganizationWebhook.url`),
+an OAuth callback, a per-tenant or self-hosted host. There is no `svcName` to resolve and nothing to
+register, but there IS a contract — the payload is fully specified and published to customers.
+
+It is not a different kind of client. It is ONE filter:
+
+```ts
+/** @externalSystem runtime partner-webhooks */
+@ApiPath('/ot-webhook')
+export class PartnerWebhookApi {
+    @Endpoint('/deliver')
+    @AuthWebhook('partner-hmac')
+    deliver(envelope: WebhookEnvelope): Promise<DeliveryAck>;
+}
+
+const partner = factory.createRpcClient(PartnerWebhookApi, new ClientConfig('partner-webhooks'), [
+    new ClientFilterDefinition(1000, new ContextBaseUrlFilter()),
+]);
+
+for (const webhook of webhooks) {
+    await RequestContext.run(() => {
+        RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);
+        return partner.deliver(envelope);
+    });
+}
+```
+
+- **Installing the filter IS the opt-in.** A client without a `ContextBaseUrlFilter` ignores an
+  ambient `OVERRIDE_BASE_URL` entirely, so a URL set for a partner delivery cannot re-point every
+  other client in the same request. `grep -rn ContextBaseUrlFilter` lists every client that can be
+  re-pointed at all.
+- **It cannot leak.** The override lives on the per-call request, never on the client, so one client
+  fans out across N partner URLs and each call goes exactly where its own scope said.
+- **SSRF is automatic, and it is the ACT of re-pointing that arms it.** A URL that came out of
+  `ClientRegistry` is an address we chose and is never judged — so a `localhost` emulator registered
+  with `ClientRegistry.addMapping` needs no opt-out of any kind, and an ordinary RPC costs nothing.
+  A re-pointed URL gets the full policy: https only; loopback / RFC1918 / CGNAT / link-local /
+  cloud-metadata refused, by name AND by every address the name resolves to; redirects taken away
+  from the transport and re-judged hop by hop, so a partner URL that 302s at `169.254.169.254` is
+  refused rather than obeyed. The one relaxation — testing the partner path against a local fake —
+  has to be said out loud, with a reason:
+  `new ContextBaseUrlFilter(new SsrfTestingPolicy('local fake in the delivery e2e'))`.
+- **Every auth mode still works.** `@AuthOidc` mints for the FINAL base URL, `@AuthSharedSecret`
+  sends the value this client holds (N services implementing one contract behind one agreed secret is
+  a real topology), and `@AuthWebhook(name)` calls your bound `WebhookSignerCallback`. The minter runs
+  BELOW the SSRF guard, so a destination that is going to be refused never causes a credential to be
+  created.
+- **The hop is VISIBLE.** `@externalSystem runtime <identity>` on the contract draws the destination
+  as its own node on the runtime architecture graph, and two services delivering over the same
+  contract converge on one box.
+
+## Signing an OUTBOUND webhook — `@AuthWebhook`, the other way round
+
+`@AuthWebhook(name)` names a signing SCHEME, not a direction. Inbound, a vendor signs and your bound
+`WebhookAuthCallback` (in `@webpieces/http-routing`) verifies. Outbound, WE are the vendor, so your
+bound `WebhookSignerCallback` produces the signature over the final URL and the exact wire bytes:
+
+```ts
+@provideSingleton()
+export class PartnerHmacSigner implements WebhookSignerCallback {
+    async sign(name: string, request: SignableRequest): Promise<Map<string, string>> {
+        const mac = createHmac('sha256', secretFor(name)).update(request.body ?? '').digest('hex');
+        return new Map([['x-partner-signature', `sha256=${mac}`]]);
+    }
+}
+
+// AppModule.ts
+options.bind(WEBHOOK_SIGNER_CALLBACK).to(PartnerHmacSigner);
+```
+
+The framework ships no vendor crypto, deliberately: Twilio signs the full URL with sorted params,
+Slack signs `v0:{ts}:{body}`, Meta signs the raw body. The scheme lives in your hook and the vendor on
+the contract. With **no** `WebhookSignerCallback` bound, every outbound `@AuthWebhook` call THROWS
+rather than delivering unsigned — the mirror of an unbound `WebhookAuthCallback` 401ing every inbound
+one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-client-node",
-  "version": "0.4.699",
+  "version": "0.4.701",
   "description": "Server-side HTTP client for webpieces: inversify-wired, reads RequestContext directly, mints OIDC/shared-secret delivery auth, resolves Cloud Run URLs from a service name",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,10 +22,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-context": "0.4.699",
-    "@webpieces/core-util": "0.4.699",
-    "@webpieces/gcp-identity": "0.4.699",
-    "@webpieces/http-client-core": "0.4.699",
+    "@webpieces/core-context": "0.4.701",
+    "@webpieces/core-util": "0.4.701",
+    "@webpieces/gcp-identity": "0.4.701",
+    "@webpieces/http-client-core": "0.4.701",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"
   }

package/src/AddressResolver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Turns a hostname into the IP addresses it actually resolves to — the half of the SSRF check that
+ * has to touch the network, kept behind its own class so the policy itself is unit-testable without
+ * DNS and a test can hand the guard a resolver that answers whatever the case needs.
+ *
+ * ABSTRACT rather than an interface because it is a collaborator with behavior, and because
+ * @webpieces/core-mock and app tests substitute it by TYPE.
+ *
+ * DI-BOUND, not threaded through constructors: {@link DnsAddressResolver} registers itself as the
+ * DEFAULT for this base, so every `NodeProxyClient` gets a working resolver with nobody writing a
+ * line, and an app or a test rebinds THIS type to substitute one. Passing a resolver in at each
+ * client construction site — which is what the deleted host-policy classes did — made the framework's
+ * own dependency the app's to remember, on every single client, forever.
+ */
+export declare abstract class AddressResolver {
+    /**
+     * Every address `hostname` resolves to, as strings. ALL of them matter: a hostname that answers
+     * with one public address and one 127.0.0.1 is the classic DNS-rebinding shape, and a guard that
+     * checks only the first answer waves it through.
+     *
+     * @throws Error when the name does not resolve. The guard treats that as a refusal, not as a
+     *         pass — a destination we cannot even name is not one we should POST a payload to.
+     */
+    abstract resolve(hostname: string): Promise<string[]>;
+}
+/**
+ * The real one: node's DNS resolver, asking for every address family. Registered as the OVERRIDABLE
+ * default for {@link AddressResolver}, so injecting the base type just works and a test rebinding
+ * that type wins.
+ */
+export declare class DnsAddressResolver extends AddressResolver {
+    resolve(hostname: string): Promise<string[]>;
+}

package/src/AddressResolver.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DnsAddressResolver = exports.AddressResolver = void 0;
+const tslib_1 = require("tslib");
+const promises_1 = require("node:dns/promises");
+const core_context_1 = require("@webpieces/core-context");
+/**
+ * Turns a hostname into the IP addresses it actually resolves to — the half of the SSRF check that
+ * has to touch the network, kept behind its own class so the policy itself is unit-testable without
+ * DNS and a test can hand the guard a resolver that answers whatever the case needs.
+ *
+ * ABSTRACT rather than an interface because it is a collaborator with behavior, and because
+ * @webpieces/core-mock and app tests substitute it by TYPE.
+ *
+ * DI-BOUND, not threaded through constructors: {@link DnsAddressResolver} registers itself as the
+ * DEFAULT for this base, so every `NodeProxyClient` gets a working resolver with nobody writing a
+ * line, and an app or a test rebinds THIS type to substitute one. Passing a resolver in at each
+ * client construction site — which is what the deleted host-policy classes did — made the framework's
+ * own dependency the app's to remember, on every single client, forever.
+ */
+class AddressResolver {
+}
+exports.AddressResolver = AddressResolver;
+/**
+ * The real one: node's DNS resolver, asking for every address family. Registered as the OVERRIDABLE
+ * default for {@link AddressResolver}, so injecting the base type just works and a test rebinding
+ * that type wins.
+ */
+let DnsAddressResolver = class DnsAddressResolver extends AddressResolver {
+    async resolve(hostname) {
+        const answers = await (0, promises_1.lookup)(hostname, { all: true, verbatim: true });
+        return answers.map((answer) => answer.address);
+    }
+};
+exports.DnsAddressResolver = DnsAddressResolver;
+exports.DnsAddressResolver = DnsAddressResolver = tslib_1.__decorate([
+    (0, core_context_1.provideFrameworkSingletonDefaultForApi)(AddressResolver)
+], DnsAddressResolver);
+//# sourceMappingURL=AddressResolver.js.map

package/src/AddressResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddressResolver.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/AddressResolver.ts"],"names":[],"mappings":";;;;AACA,gDAA2C;AAC3C,0DAAiF;AAEjF;;;;;;;;;;;;;GAaG;AACH,MAAsB,eAAe;CAUpC;AAVD,0CAUC;AAED;;;;GAIG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAmB,SAAQ,eAAe;IAC1C,KAAK,CAAC,OAAO,CAAC,QAAgB;QACnC,MAAM,OAAO,GAAoB,MAAM,IAAA,iBAAM,EAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACvF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAqB,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC;CACJ,CAAA;AALY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,qDAAsC,EAAC,eAAe,CAAC;GAC3C,kBAAkB,CAK9B","sourcesContent":["import type { LookupAddress } from 'node:dns';\nimport { lookup } from 'node:dns/promises';\nimport { provideFrameworkSingletonDefaultForApi } from '@webpieces/core-context';\n\n/**\n * Turns a hostname into the IP addresses it actually resolves to — the half of the SSRF check that\n * has to touch the network, kept behind its own class so the policy itself is unit-testable without\n * DNS and a test can hand the guard a resolver that answers whatever the case needs.\n *\n * ABSTRACT rather than an interface because it is a collaborator with behavior, and because\n * @webpieces/core-mock and app tests substitute it by TYPE.\n *\n * DI-BOUND, not threaded through constructors: {@link DnsAddressResolver} registers itself as the\n * DEFAULT for this base, so every `NodeProxyClient` gets a working resolver with nobody writing a\n * line, and an app or a test rebinds THIS type to substitute one. Passing a resolver in at each\n * client construction site — which is what the deleted host-policy classes did — made the framework's\n * own dependency the app's to remember, on every single client, forever.\n */\nexport abstract class AddressResolver {\n    /**\n     * Every address `hostname` resolves to, as strings. ALL of them matter: a hostname that answers\n     * with one public address and one 127.0.0.1 is the classic DNS-rebinding shape, and a guard that\n     * checks only the first answer waves it through.\n     *\n     * @throws Error when the name does not resolve. The guard treats that as a refusal, not as a\n     *         pass — a destination we cannot even name is not one we should POST a payload to.\n     */\n    abstract resolve(hostname: string): Promise<string[]>;\n}\n\n/**\n * The real one: node's DNS resolver, asking for every address family. Registered as the OVERRIDABLE\n * default for {@link AddressResolver}, so injecting the base type just works and a test rebinding\n * that type wins.\n */\n@provideFrameworkSingletonDefaultForApi(AddressResolver)\nexport class DnsAddressResolver extends AddressResolver {\n    override async resolve(hostname: string): Promise<string[]> {\n        const answers: LookupAddress[] = await lookup(hostname, { all: true, verbatim: true });\n        return answers.map((answer: LookupAddress) => answer.address);\n    }\n}\n"]}

package/src/ClientConfig.d.ts

@@ -4,23 +4,47 @@
  * differently and share nothing worth a base class.
  *
  * Collaborators (RequestContextHeaders, Secrets) are NOT config: they are dependencies of
- * {@link NodeProxyClient} and are shared by every client the factory builds. This is the RPC twin
- * of cloudtasks-client's TaskClientConfig, and takes the same single field.
+ * {@link NodeProxyClient} and are shared by every client the factory builds. Outbound FILTERS are
+ * not config either — they are per-client collaborators an app constructs, so they are the optional
+ * third argument to `createRpcClient` rather than a field here.
+ *
+ * ## Why WHERE a client points is not stated here
+ *
+ * A client resolves ONE address, out of {@link ClientRegistry}, from this `svcName`. A destination
+ * that is DATA instead — a URL a partner registered, a per-tenant host, an OAuth callback — is not
+ * a second KIND of config; it is a per-call edit made by a filter (`ContextBaseUrlFilter`), through
+ * the same seam an app's own header-rewriting or logging filter uses. Naming the two as alternative
+ * config shapes made a second extension mechanism sitting beside the filter chain and doing the
+ * same job, which is exactly the shape this repo rejects.
  */
 export declare class ClientConfig {
     /**
-     * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud
-     * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything
-     * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
+     * The service name, and the ONE thing that decides where this client points.
+     *
+     * The URL is DERIVED from it (on GCP: same project, same region — the Cloud Run service
+     * name, so you maintain no URL table), which works across demo/qa/prod. Anything the
+     * derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
      * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.
+     *
+     * It is also this client's IDENTITY on the runtime architecture graph. For a client that a
+     * `ContextBaseUrlFilter` re-points per call, the graph identity comes from the CONTRACT's
+     * `@externalSystem` tag instead, which is where the fact "this hop leaves our estate"
+     * belongs — on the contract every caller of it shares, not on one construction site.
      */
     readonly svcName: string;
     constructor(
     /**
-     * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud
-     * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything
-     * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
+     * The service name, and the ONE thing that decides where this client points.
+     *
+     * The URL is DERIVED from it (on GCP: same project, same region — the Cloud Run service
+     * name, so you maintain no URL table), which works across demo/qa/prod. Anything the
+     * derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
      * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.
+     *
+     * It is also this client's IDENTITY on the runtime architecture graph. For a client that a
+     * `ContextBaseUrlFilter` re-points per call, the graph identity comes from the CONTRACT's
+     * `@externalSystem` tag instead, which is where the fact "this hop leaves our estate"
+     * belongs — on the contract every caller of it shares, not on one construction site.
      */
     svcName: string);
 }

package/src/ClientConfig.js

@@ -7,17 +7,34 @@ exports.ClientConfig = void 0;
  * differently and share nothing worth a base class.
  *
  * Collaborators (RequestContextHeaders, Secrets) are NOT config: they are dependencies of
- * {@link NodeProxyClient} and are shared by every client the factory builds. This is the RPC twin
- * of cloudtasks-client's TaskClientConfig, and takes the same single field.
+ * {@link NodeProxyClient} and are shared by every client the factory builds. Outbound FILTERS are
+ * not config either — they are per-client collaborators an app constructs, so they are the optional
+ * third argument to `createRpcClient` rather than a field here.
+ *
+ * ## Why WHERE a client points is not stated here
+ *
+ * A client resolves ONE address, out of {@link ClientRegistry}, from this `svcName`. A destination
+ * that is DATA instead — a URL a partner registered, a per-tenant host, an OAuth callback — is not
+ * a second KIND of config; it is a per-call edit made by a filter (`ContextBaseUrlFilter`), through
+ * the same seam an app's own header-rewriting or logging filter uses. Naming the two as alternative
+ * config shapes made a second extension mechanism sitting beside the filter chain and doing the
+ * same job, which is exactly the shape this repo rejects.
  */
 class ClientConfig {
     svcName;
     constructor(
     /**
-     * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud
-     * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything
-     * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
+     * The service name, and the ONE thing that decides where this client points.
+     *
+     * The URL is DERIVED from it (on GCP: same project, same region — the Cloud Run service
+     * name, so you maintain no URL table), which works across demo/qa/prod. Anything the
+     * derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
      * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.
+     *
+     * It is also this client's IDENTITY on the runtime architecture graph. For a client that a
+     * `ContextBaseUrlFilter` re-points per call, the graph identity comes from the CONTRACT's
+     * `@externalSystem` tag instead, which is where the fact "this hop leaves our estate"
+     * belongs — on the contract every caller of it shares, not on one construction site.
      */
     svcName) {
         this.svcName = svcName;

package/src/ClientConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientConfig.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/ClientConfig.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,YAAY;IAQD;IAPpB;IACI;;;;;OAKG;IACa,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAChC,CAAC;CACP;AAVD,oCAUC","sourcesContent":["/**\n * Per-client STATE for a server-side HTTP client — nothing else. A plain class; it extends nothing\n * and is unrelated to the browser package's ClientConfig, because the two answer \"what URL?\"\n * differently and share nothing worth a base class.\n *\n * Collaborators (RequestContextHeaders, Secrets) are NOT config: they are dependencies of\n * {@link NodeProxyClient} and are shared by every client the factory builds. This is the RPC twin\n * of cloudtasks-client's TaskClientConfig, and takes the same single field.\n */\nexport class ClientConfig {\n    constructor(\n        /**\n         * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud\n         * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything\n         * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run\n         * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.\n         */\n        public readonly svcName: string,\n    ) {}\n}\n"]}
+{"version":3,"file":"ClientConfig.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/ClientConfig.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,YAAY;IAeD;IAdpB;IACI;;;;;;;;;;;;OAYG;IACa,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAChC,CAAC;CACP;AAjBD,oCAiBC","sourcesContent":["/**\n * Per-client STATE for a server-side HTTP client — nothing else. A plain class; it extends nothing\n * and is unrelated to the browser package's ClientConfig, because the two answer \"what URL?\"\n * differently and share nothing worth a base class.\n *\n * Collaborators (RequestContextHeaders, Secrets) are NOT config: they are dependencies of\n * {@link NodeProxyClient} and are shared by every client the factory builds. Outbound FILTERS are\n * not config either — they are per-client collaborators an app constructs, so they are the optional\n * third argument to `createRpcClient` rather than a field here.\n *\n * ## Why WHERE a client points is not stated here\n *\n * A client resolves ONE address, out of {@link ClientRegistry}, from this `svcName`. A destination\n * that is DATA instead — a URL a partner registered, a per-tenant host, an OAuth callback — is not\n * a second KIND of config; it is a per-call edit made by a filter (`ContextBaseUrlFilter`), through\n * the same seam an app's own header-rewriting or logging filter uses. Naming the two as alternative\n * config shapes made a second extension mechanism sitting beside the filter chain and doing the\n * same job, which is exactly the shape this repo rejects.\n */\nexport class ClientConfig {\n    constructor(\n        /**\n         * The service name, and the ONE thing that decides where this client points.\n         *\n         * The URL is DERIVED from it (on GCP: same project, same region — the Cloud Run service\n         * name, so you maintain no URL table), which works across demo/qa/prod. Anything the\n         * derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run\n         * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.\n         *\n         * It is also this client's IDENTITY on the runtime architecture graph. For a client that a\n         * `ContextBaseUrlFilter` re-points per call, the graph identity comes from the CONTRACT's\n         * `@externalSystem` tag instead, which is where the fact \"this hop leaves our estate\"\n         * belongs — on the contract every caller of it shares, not on one construction site.\n         */\n        public readonly svcName: string,\n    ) {}\n}\n"]}

package/src/ClientHttpFactory.d.ts

@@ -1,5 +1,6 @@
 import { Provider } from '@webpieces/core-context';
 import type { ApiPrototype } from '@webpieces/http-client-core';
+import type { ClientFilters } from '@webpieces/http-client-core';
 import { ClientConfig } from './ClientConfig';
 import { NodeProxyClient } from './NodeProxyClient';
 /**
@@ -23,6 +24,18 @@ import { NodeProxyClient } from './NodeProxyClient';
  * const response = await server2.fetchValue(req);   // inside a RequestContext
  * ```
  *
+ * A destination that is DATA rather than deployment — a URL a partner registered — is a FILTER, not
+ * a different kind of client. Install `ContextBaseUrlFilter` on the one client that may be
+ * re-pointed, and set the URL per call:
+ * ```typescript
+ * const partner = factory.createRpcClient(PartnerWebhookApi, new ClientConfig('partner-webhooks'), [
+ *     new ClientFilterDefinition(1000, new ContextBaseUrlFilter()),
+ * ]);
+ * ```
+ * The SSRF guard arms itself the moment that filter re-points a request, and the contract's
+ * `@AuthWebhook(name)` selects the app's bound `WebhookSignerCallback` to sign the exact bytes —
+ * neither is something the app registers, orders, or can displace.
+ *
  * Every client it builds shares one {@link NodeProxyClient} *shape* but never one instance: the
  * injected `Provider<NodeProxyClient>` hands out a fresh one per contract, which `createRpcClient`
  * then `init`s. Their collaborators (RequestContextHeaders, Secrets) come from the container, so
@@ -39,7 +52,23 @@ export declare class ClientHttpFactory {
      * Create a type-safe RPC (HTTP) client for one API contract.
      *
      * @param apiPrototype - The API prototype class with @ApiPath/@Endpoint decorators
-     * @param config - This client's state (its svcName)
+     * @param config - This client's state: its svcName, which is what `ClientRegistry` resolves
+     * @param filters - This client's own OUTBOUND filters, each with the priority it runs at
+     *        (highest OUTERMOST). They wrap the send, so a filter may rewrite the URL, add or remove
+     *        headers, log, or replace `ClientRequest.body` — the exact bytes transmitted. What goes
+     *        here is APP behaviour: url rewriting, headers, logging, and `ContextBaseUrlFilter` when
+     *        this client's destination arrives per call.
+     *
+     *        OPTIONAL, and omitting it is not a statement about security: the framework's own SSRF
+     *        guard and credential minter are installed on every client regardless, BENEATH anything
+     *        passed here, so there is nothing an app can decline by writing nothing.
+     *
+     *        ONE SPELLING PER DECISION. It is a NON-EMPTY tuple, so `createRpcClient(Api, cfg, [])`
+     *        does not compile: "this client has no app filters" is said by omitting the argument, and
+     *        `[]` would be a second way to say the identical thing. That is the same device
+     *        {@link JwtRoles}'s `roles` uses, for the same reason — the bad case is deleted by the
+     *        TYPE rather than left available and discouraged in a docstring. Pinned in
+     *        {@link CreateRpcClientCompileAssertions}.
      */
-    createRpcClient<T extends object>(apiPrototype: ApiPrototype<T>, config: ClientConfig): T;
+    createRpcClient<T extends object>(apiPrototype: ApiPrototype<T>, config: ClientConfig, filters?: ClientFilters): T;
 }

package/src/ClientHttpFactory.js

@@ -31,6 +31,18 @@ const NodeProxyClient_1 = require("./NodeProxyClient");
  * const response = await server2.fetchValue(req);   // inside a RequestContext
  * ```
  *
+ * A destination that is DATA rather than deployment — a URL a partner registered — is a FILTER, not
+ * a different kind of client. Install `ContextBaseUrlFilter` on the one client that may be
+ * re-pointed, and set the URL per call:
+ * ```typescript
+ * const partner = factory.createRpcClient(PartnerWebhookApi, new ClientConfig('partner-webhooks'), [
+ *     new ClientFilterDefinition(1000, new ContextBaseUrlFilter()),
+ * ]);
+ * ```
+ * The SSRF guard arms itself the moment that filter re-points a request, and the contract's
+ * `@AuthWebhook(name)` selects the app's bound `WebhookSignerCallback` to sign the exact bytes —
+ * neither is something the app registers, orders, or can displace.
+ *
  * Every client it builds shares one {@link NodeProxyClient} *shape* but never one instance: the
  * injected `Provider<NodeProxyClient>` hands out a fresh one per contract, which `createRpcClient`
  * then `init`s. Their collaborators (RequestContextHeaders, Secrets) come from the container, so
@@ -49,13 +61,29 @@ let ClientHttpFactory = class ClientHttpFactory {
      * Create a type-safe RPC (HTTP) client for one API contract.
      *
      * @param apiPrototype - The API prototype class with @ApiPath/@Endpoint decorators
-     * @param config - This client's state (its svcName)
+     * @param config - This client's state: its svcName, which is what `ClientRegistry` resolves
+     * @param filters - This client's own OUTBOUND filters, each with the priority it runs at
+     *        (highest OUTERMOST). They wrap the send, so a filter may rewrite the URL, add or remove
+     *        headers, log, or replace `ClientRequest.body` — the exact bytes transmitted. What goes
+     *        here is APP behaviour: url rewriting, headers, logging, and `ContextBaseUrlFilter` when
+     *        this client's destination arrives per call.
+     *
+     *        OPTIONAL, and omitting it is not a statement about security: the framework's own SSRF
+     *        guard and credential minter are installed on every client regardless, BENEATH anything
+     *        passed here, so there is nothing an app can decline by writing nothing.
+     *
+     *        ONE SPELLING PER DECISION. It is a NON-EMPTY tuple, so `createRpcClient(Api, cfg, [])`
+     *        does not compile: "this client has no app filters" is said by omitting the argument, and
+     *        `[]` would be a second way to say the identical thing. That is the same device
+     *        {@link JwtRoles}'s `roles` uses, for the same reason — the bad case is deleted by the
+     *        TYPE rather than left available and discouraged in a docstring. Pinned in
+     *        {@link CreateRpcClientCompileAssertions}.
      */
-    createRpcClient(apiPrototype, config) {
+    createRpcClient(apiPrototype, config, filters) {
         // Fresh instance per contract — NodeProxyClient is transient. init() binds it to this
         // contract + target; the collaborators already came from the container.
         const proxyClient = this.proxyClientProvider.get();
-        proxyClient.init(apiPrototype, config);
+        proxyClient.init(apiPrototype, config, filters === undefined ? [] : [...filters]);
         return (0, http_client_core_1.buildClientProxy)(apiPrototype, proxyClient);
     }
 };

package/src/ClientHttpFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientHttpFactory.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/ClientHttpFactory.ts"],"names":[],"mappings":";;;;AAAA,yCAAmC;AACnC,oDAAsD;AACtD,0DAAqG;AAErG,kEAA+D;AAE/D,uDAAgF;AAEhF,iGAAiG;AACjG,6EAA6E;AAC7E,IAAA,oCAAqB,EAAC,4CAA0B,EAAE,iCAAe,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGI,IAAM,iBAAiB,GAAvB,MAAM,iBAAiB;IAE+B;IADzD,YACyD,mBAA8C;QAA9C,wBAAmB,GAAnB,mBAAmB,CAA2B;IACpG,CAAC;IAEJ;;;;;OAKG;IACH,eAAe,CAAmB,YAA6B,EAAE,MAAoB;QACjF,sFAAsF;QACtF,wEAAwE;QACxE,MAAM,WAAW,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC;QACnD,WAAW,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO,IAAA,mCAAgB,EAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACvD,CAAC;CACJ,CAAA;AAlBY,8CAAiB;4BAAjB,iBAAiB;IAF7B,IAAA,0BAAc,GAAE;IAChB,IAAA,wCAAyB,GAAE;IAGnB,mBAAA,IAAA,kBAAM,EAAC,4CAA0B,CAAC,CAAA;6CAAuC,uBAAQ;GAF7E,iBAAiB,CAkB7B","sourcesContent":["import { inject } from 'inversify';\nimport { DocumentDesign } from '@webpieces/core-util';\nimport { Provider, bindFrameworkProvider, provideFrameworkSingleton } from '@webpieces/core-context';\nimport type { ApiPrototype } from '@webpieces/http-client-core';\nimport { buildClientProxy } from '@webpieces/http-client-core';\nimport { ClientConfig } from './ClientConfig';\nimport { NODE_PROXY_CLIENT_PROVIDER, NodeProxyClient } from './NodeProxyClient';\n\n// Teach the container how to hand out fresh NodeProxyClients. NodeProxyClient is bound TRANSIENT\n// (@provideFrameworkTransient), so each provider.get() constructs a new one.\nbindFrameworkProvider(NODE_PROXY_CLIENT_PROVIDER, NodeProxyClient);\n\n/**\n * ClientHttpFactory - builds type-safe HTTP clients from API prototypes carrying\n * @ApiPath/@Endpoint decorators. The SERVER-side factory.\n *\n * This is the client-side equivalent of ApiRoutingFactory:\n * - Server routing: ApiRoutingFactory reads decorators -> routes HTTP requests to controllers\n * - Server client:  ClientHttpFactory reads decorators -> generates HTTP requests from method calls\n *\n * Inject it and ask for a typed client per contract:\n * ```typescript\n * // same project + region as this container; the URL is derived, you maintain nothing\n * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2'));\n *\n * // to reach somewhere derivation cannot describe (other region/project, non-Cloud-Run, localhost),\n * // register it once at startup — the client still carries only the svcName:\n * //   ClientRegistry.addUrlMapping('legacy', 'https://legacy.corp');\n * const legacy = factory.createRpcClient(LegacyApi, new ClientConfig('legacy'));\n *\n * const response = await server2.fetchValue(req);   // inside a RequestContext\n * ```\n *\n * Every client it builds shares one {@link NodeProxyClient} *shape* but never one instance: the\n * injected `Provider<NodeProxyClient>` hands out a fresh one per contract, which `createRpcClient`\n * then `init`s. Their collaborators (RequestContextHeaders, Secrets) come from the container, so\n * the whole dependency graph is visible in this package's design.html.\n *\n * Unlike @webpieces/http-client-browser this package is Node-only, so the factory IS the inversify\n * entry point and the magic context is read straight from the RequestContext. A call made outside\n * `RequestContext.run(...)` throws rather than silently dropping the trace.\n */\n@DocumentDesign()\n@provideFrameworkSingleton()\nexport class ClientHttpFactory {\n    constructor(\n        @inject(NODE_PROXY_CLIENT_PROVIDER) private readonly proxyClientProvider: Provider<NodeProxyClient>,\n    ) {}\n\n    /**\n     * Create a type-safe RPC (HTTP) client for one API contract.\n     *\n     * @param apiPrototype - The API prototype class with @ApiPath/@Endpoint decorators\n     * @param config - This client's state (its svcName)\n     */\n    createRpcClient<T extends object>(apiPrototype: ApiPrototype<T>, config: ClientConfig): T {\n        // Fresh instance per contract — NodeProxyClient is transient. init() binds it to this\n        // contract + target; the collaborators already came from the container.\n        const proxyClient = this.proxyClientProvider.get();\n        proxyClient.init(apiPrototype, config);\n        return buildClientProxy(apiPrototype, proxyClient);\n    }\n}\n"]}
+{"version":3,"file":"ClientHttpFactory.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/ClientHttpFactory.ts"],"names":[],"mappings":";;;;AAAA,yCAAmC;AACnC,oDAAsD;AACtD,0DAAqG;AAErG,kEAA+D;AAG/D,uDAAgF;AAEhF,iGAAiG;AACjG,6EAA6E;AAC7E,IAAA,oCAAqB,EAAC,4CAA0B,EAAE,iCAAe,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGI,IAAM,iBAAiB,GAAvB,MAAM,iBAAiB;IAE+B;IADzD,YACyD,mBAA8C;QAA9C,wBAAmB,GAAnB,mBAAmB,CAA2B;IACpG,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,eAAe,CACX,YAA6B,EAC7B,MAAoB,EACpB,OAAuB;QAEvB,sFAAsF;QACtF,wEAAwE;QACxE,MAAM,WAAW,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC;QACnD,WAAW,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;QAClF,OAAO,IAAA,mCAAgB,EAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACvD,CAAC;CACJ,CAAA;AAtCY,8CAAiB;4BAAjB,iBAAiB;IAF7B,IAAA,0BAAc,GAAE;IAChB,IAAA,wCAAyB,GAAE;IAGnB,mBAAA,IAAA,kBAAM,EAAC,4CAA0B,CAAC,CAAA;6CAAuC,uBAAQ;GAF7E,iBAAiB,CAsC7B","sourcesContent":["import { inject } from 'inversify';\nimport { DocumentDesign } from '@webpieces/core-util';\nimport { Provider, bindFrameworkProvider, provideFrameworkSingleton } from '@webpieces/core-context';\nimport type { ApiPrototype } from '@webpieces/http-client-core';\nimport { buildClientProxy } from '@webpieces/http-client-core';\nimport type { ClientFilters } from '@webpieces/http-client-core';\nimport { ClientConfig } from './ClientConfig';\nimport { NODE_PROXY_CLIENT_PROVIDER, NodeProxyClient } from './NodeProxyClient';\n\n// Teach the container how to hand out fresh NodeProxyClients. NodeProxyClient is bound TRANSIENT\n// (@provideFrameworkTransient), so each provider.get() constructs a new one.\nbindFrameworkProvider(NODE_PROXY_CLIENT_PROVIDER, NodeProxyClient);\n\n/**\n * ClientHttpFactory - builds type-safe HTTP clients from API prototypes carrying\n * @ApiPath/@Endpoint decorators. The SERVER-side factory.\n *\n * This is the client-side equivalent of ApiRoutingFactory:\n * - Server routing: ApiRoutingFactory reads decorators -> routes HTTP requests to controllers\n * - Server client:  ClientHttpFactory reads decorators -> generates HTTP requests from method calls\n *\n * Inject it and ask for a typed client per contract:\n * ```typescript\n * // same project + region as this container; the URL is derived, you maintain nothing\n * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2'));\n *\n * // to reach somewhere derivation cannot describe (other region/project, non-Cloud-Run, localhost),\n * // register it once at startup — the client still carries only the svcName:\n * //   ClientRegistry.addUrlMapping('legacy', 'https://legacy.corp');\n * const legacy = factory.createRpcClient(LegacyApi, new ClientConfig('legacy'));\n *\n * const response = await server2.fetchValue(req);   // inside a RequestContext\n * ```\n *\n * A destination that is DATA rather than deployment — a URL a partner registered — is a FILTER, not\n * a different kind of client. Install `ContextBaseUrlFilter` on the one client that may be\n * re-pointed, and set the URL per call:\n * ```typescript\n * const partner = factory.createRpcClient(PartnerWebhookApi, new ClientConfig('partner-webhooks'), [\n *     new ClientFilterDefinition(1000, new ContextBaseUrlFilter()),\n * ]);\n * ```\n * The SSRF guard arms itself the moment that filter re-points a request, and the contract's\n * `@AuthWebhook(name)` selects the app's bound `WebhookSignerCallback` to sign the exact bytes —\n * neither is something the app registers, orders, or can displace.\n *\n * Every client it builds shares one {@link NodeProxyClient} *shape* but never one instance: the\n * injected `Provider<NodeProxyClient>` hands out a fresh one per contract, which `createRpcClient`\n * then `init`s. Their collaborators (RequestContextHeaders, Secrets) come from the container, so\n * the whole dependency graph is visible in this package's design.html.\n *\n * Unlike @webpieces/http-client-browser this package is Node-only, so the factory IS the inversify\n * entry point and the magic context is read straight from the RequestContext. A call made outside\n * `RequestContext.run(...)` throws rather than silently dropping the trace.\n */\n@DocumentDesign()\n@provideFrameworkSingleton()\nexport class ClientHttpFactory {\n    constructor(\n        @inject(NODE_PROXY_CLIENT_PROVIDER) private readonly proxyClientProvider: Provider<NodeProxyClient>,\n    ) {}\n\n    /**\n     * Create a type-safe RPC (HTTP) client for one API contract.\n     *\n     * @param apiPrototype - The API prototype class with @ApiPath/@Endpoint decorators\n     * @param config - This client's state: its svcName, which is what `ClientRegistry` resolves\n     * @param filters - This client's own OUTBOUND filters, each with the priority it runs at\n     *        (highest OUTERMOST). They wrap the send, so a filter may rewrite the URL, add or remove\n     *        headers, log, or replace `ClientRequest.body` — the exact bytes transmitted. What goes\n     *        here is APP behaviour: url rewriting, headers, logging, and `ContextBaseUrlFilter` when\n     *        this client's destination arrives per call.\n     *\n     *        OPTIONAL, and omitting it is not a statement about security: the framework's own SSRF\n     *        guard and credential minter are installed on every client regardless, BENEATH anything\n     *        passed here, so there is nothing an app can decline by writing nothing.\n     *\n     *        ONE SPELLING PER DECISION. It is a NON-EMPTY tuple, so `createRpcClient(Api, cfg, [])`\n     *        does not compile: \"this client has no app filters\" is said by omitting the argument, and\n     *        `[]` would be a second way to say the identical thing. That is the same device\n     *        {@link JwtRoles}'s `roles` uses, for the same reason — the bad case is deleted by the\n     *        TYPE rather than left available and discouraged in a docstring. Pinned in\n     *        {@link CreateRpcClientCompileAssertions}.\n     */\n    createRpcClient<T extends object>(\n        apiPrototype: ApiPrototype<T>,\n        config: ClientConfig,\n        filters?: ClientFilters,\n    ): T {\n        // Fresh instance per contract — NodeProxyClient is transient. init() binds it to this\n        // contract + target; the collaborators already came from the container.\n        const proxyClient = this.proxyClientProvider.get();\n        proxyClient.init(apiPrototype, config, filters === undefined ? [] : [...filters]);\n        return buildClientProxy(apiPrototype, proxyClient);\n    }\n}\n"]}

package/src/ContextBaseUrlFilter.d.ts

@@ -0,0 +1,80 @@
+import { Filter, Service } from '@webpieces/core-util';
+import { ClientRequest } from '@webpieces/http-client-core';
+import { SsrfPolicy } from './SsrfPolicy';
+/**
+ * Reads {@link WebpiecesCoreHeaders.OVERRIDE_BASE_URL} out of the ambient RequestContext and points
+ * THIS ONE CALL at it. Ships in the box, and is the whole of the runtime-base-URL feature:
+ *
+ * ```ts
+ * const partner = factory.createRpcClient(PartnerWebhookApi, new ClientConfig('partner-webhooks'), [
+ *     new ClientFilterDefinition(1000, new ContextBaseUrlFilter()),
+ * ]);
+ *
+ * for (const webhook of webhooks) {
+ *     await RequestContext.run(() => {
+ *         RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);
+ *         return partner.deliver(envelope);
+ *     });
+ * }
+ * ```
+ *
+ * ## INSTALLING IT IS THE OPT-IN
+ *
+ * There is no client-level setting saying "this one may be re-pointed", because installing this
+ * filter IS that statement, written at the one place a reader looks. A client with no
+ * `ContextBaseUrlFilter` ignores an ambient `OVERRIDE_BASE_URL` entirely — which is what stops a
+ * value set for a partner delivery from silently re-pointing every other client in the same
+ * request at the partner's server. `grep -rn ContextBaseUrlFilter` enumerates every client in a
+ * codebase that can be re-pointed at all, which is the question a security review actually asks.
+ *
+ * ## PER-ENDPOINT, if a contract mixes them
+ *
+ * `request.route` carries `methodName`, `path`, `httpMethod` and `authMeta`, so a subclass can
+ * re-point some endpoints of a contract and leave the rest on the configured host, with no API
+ * change:
+ *
+ * ```ts
+ * class DeliverOnlyBaseUrlFilter extends ContextBaseUrlFilter {
+ *     override async filter(request: ClientRequest, next: Service<ClientRequest, Response>) {
+ *         if (request.route.methodName !== 'deliver') return next.invoke(request);
+ *         return super.filter(request, next);
+ *     }
+ * }
+ * ```
+ *
+ * ## Scope, and why it cannot leak
+ *
+ * It mutates the per-call {@link ClientRequest} and nothing else. The client is untouched, so the
+ * next call through the same client starts from its configured host again; and the context entry is
+ * scoped to whatever `RequestContext.run(...)` the caller established, so a fan-out loop that sets
+ * a different URL per partner gets exactly the URL it set, per iteration.
+ *
+ * ## The SSRF guard is NOT registered here
+ *
+ * Re-pointing arms it by itself — `ClientRequest.pointAtBaseUrl` flips
+ * `destinationCameFromData`, and the framework's own guard sits beneath every app filter and reads
+ * that. So this filter cannot forget to bring the guard along, and an app cannot install this one
+ * without it. The only thing this class carries is WHICH policy the guard applies, and only
+ * because the single legitimate relaxation ({@link SsrfTestingPolicy}) belongs at the same
+ * construction site as the decision to be re-pointable at all.
+ */
+export declare class ContextBaseUrlFilter extends Filter<ClientRequest, Response> {
+    /**
+     * What the framework's SSRF guard holds this client's re-pointed URLs to.
+     *
+     * Defaulted to {@link SsrfPolicy} (the strict one), and that default is the SAFE branch, so the
+     * omitted argument can never be the permissive one — the widening has to be typed out, with
+     * a reason, as `new ContextBaseUrlFilter(new SsrfTestingPolicy('<why>'))`.
+     */
+    readonly ssrfPolicy: SsrfPolicy;
+    constructor(
+    /**
+     * What the framework's SSRF guard holds this client's re-pointed URLs to.
+     *
+     * Defaulted to {@link SsrfPolicy} (the strict one), and that default is the SAFE branch, so the
+     * omitted argument can never be the permissive one — the widening has to be typed out, with
+     * a reason, as `new ContextBaseUrlFilter(new SsrfTestingPolicy('<why>'))`.
+     */
+    ssrfPolicy?: SsrfPolicy);
+    filter(request: ClientRequest, nextFilter: Service<ClientRequest, Response>): Promise<Response>;
+}

package/src/ContextBaseUrlFilter.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextBaseUrlFilter = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const core_context_1 = require("@webpieces/core-context");
+const MissingRuntimeBaseUrlError_1 = require("./MissingRuntimeBaseUrlError");
+const SsrfPolicy_1 = require("./SsrfPolicy");
+/**
+ * Reads {@link WebpiecesCoreHeaders.OVERRIDE_BASE_URL} out of the ambient RequestContext and points
+ * THIS ONE CALL at it. Ships in the box, and is the whole of the runtime-base-URL feature:
+ *
+ * ```ts
+ * const partner = factory.createRpcClient(PartnerWebhookApi, new ClientConfig('partner-webhooks'), [
+ *     new ClientFilterDefinition(1000, new ContextBaseUrlFilter()),
+ * ]);
+ *
+ * for (const webhook of webhooks) {
+ *     await RequestContext.run(() => {
+ *         RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);
+ *         return partner.deliver(envelope);
+ *     });
+ * }
+ * ```
+ *
+ * ## INSTALLING IT IS THE OPT-IN
+ *
+ * There is no client-level setting saying "this one may be re-pointed", because installing this
+ * filter IS that statement, written at the one place a reader looks. A client with no
+ * `ContextBaseUrlFilter` ignores an ambient `OVERRIDE_BASE_URL` entirely — which is what stops a
+ * value set for a partner delivery from silently re-pointing every other client in the same
+ * request at the partner's server. `grep -rn ContextBaseUrlFilter` enumerates every client in a
+ * codebase that can be re-pointed at all, which is the question a security review actually asks.
+ *
+ * ## PER-ENDPOINT, if a contract mixes them
+ *
+ * `request.route` carries `methodName`, `path`, `httpMethod` and `authMeta`, so a subclass can
+ * re-point some endpoints of a contract and leave the rest on the configured host, with no API
+ * change:
+ *
+ * ```ts
+ * class DeliverOnlyBaseUrlFilter extends ContextBaseUrlFilter {
+ *     override async filter(request: ClientRequest, next: Service<ClientRequest, Response>) {
+ *         if (request.route.methodName !== 'deliver') return next.invoke(request);
+ *         return super.filter(request, next);
+ *     }
+ * }
+ * ```
+ *
+ * ## Scope, and why it cannot leak
+ *
+ * It mutates the per-call {@link ClientRequest} and nothing else. The client is untouched, so the
+ * next call through the same client starts from its configured host again; and the context entry is
+ * scoped to whatever `RequestContext.run(...)` the caller established, so a fan-out loop that sets
+ * a different URL per partner gets exactly the URL it set, per iteration.
+ *
+ * ## The SSRF guard is NOT registered here
+ *
+ * Re-pointing arms it by itself — `ClientRequest.pointAtBaseUrl` flips
+ * `destinationCameFromData`, and the framework's own guard sits beneath every app filter and reads
+ * that. So this filter cannot forget to bring the guard along, and an app cannot install this one
+ * without it. The only thing this class carries is WHICH policy the guard applies, and only
+ * because the single legitimate relaxation ({@link SsrfTestingPolicy}) belongs at the same
+ * construction site as the decision to be re-pointable at all.
+ */
+class ContextBaseUrlFilter extends core_util_1.Filter {
+    ssrfPolicy;
+    constructor(
+    /**
+     * What the framework's SSRF guard holds this client's re-pointed URLs to.
+     *
+     * Defaulted to {@link SsrfPolicy} (the strict one), and that default is the SAFE branch, so the
+     * omitted argument can never be the permissive one — the widening has to be typed out, with
+     * a reason, as `new ContextBaseUrlFilter(new SsrfTestingPolicy('<why>'))`.
+     */
+    ssrfPolicy = new SsrfPolicy_1.SsrfPolicy()) {
+        super();
+        this.ssrfPolicy = ssrfPolicy;
+    }
+    async filter(request, nextFilter) {
+        const override = core_context_1.RequestContext.getUntrusted(core_util_1.WebpiecesCoreHeaders.OVERRIDE_BASE_URL);
+        if (override === undefined || override === '') {
+            throw new MissingRuntimeBaseUrlError_1.MissingRuntimeBaseUrlError(`${request.contractName}.${request.route.methodName} runs behind a ContextBaseUrlFilter, so ` +
+                `its destination must be supplied per call, but no ` +
+                `WebpiecesCoreHeaders.OVERRIDE_BASE_URL was found in the RequestContext. Set it around ` +
+                `the call:\n` +
+                `    RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);\n` +
+                `Refusing rather than falling back to this client's configured service URL is ` +
+                `deliberate: a silent fallback would send a partner's payload to one of our own services.`, `${request.contractName}.${request.route.methodName}`);
+        }
+        request.pointAtBaseUrl(override);
+        return nextFilter.invoke(request);
+    }
+}
+exports.ContextBaseUrlFilter = ContextBaseUrlFilter;
+//# sourceMappingURL=ContextBaseUrlFilter.js.map