@webpieces/http-client-node 0.4.700 → 0.4.701

package/README.md

@@ -5,18 +5,10 @@ the Cloud Tasks twin — calling a method makes the HTTP request that contract d
 
 ```ts
 // inject the factory (a framework singleton), then one client per contract
-const server2 = factory.createRpcClient(
-    Server2Api,
-    new ClientConfig('server2', new DeployedServiceHost()),
-    [],                                             // this client's outbound filters
-);
+const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2'));
 const res = await server2.fetchValue(req);          // inside a RequestContext
 ```
 
-Every `ClientConfig` states WHERE its requests go, because there are two kinds of destination and
-they carry very different risk. `DeployedServiceHost` is the one above and is what almost every
-client wants. See "A destination supplied at RUNTIME" below for the other.
-
 - `svcName` becomes a URL through `ClientRegistry.resolve` — ONE chain, the same one the browser
   client and Cloud Tasks run:
   1. a registered mapping wins: `ClientRegistry.addMapping(svcName, port)` (localhost) or
@@ -41,19 +33,53 @@ 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. Name
-a runtime host policy and the base URL arrives per call:
+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
-const partner = factory.createRpcClient(
-    PartnerWebhookApi,
-    new ClientConfig('partner-webhooks', new RuntimeHostFromContext(new DnsAddressResolver())),
-    [new ClientFilterDefinition(500, new HmacSigningFilter(secret))],
-);
+/** @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(() => {
@@ -63,46 +89,51 @@ for (const webhook of webhooks) {
 }
 ```
 
+- **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.
-- **A `DeployedServiceHost` client IGNORES the key.** That is the point of making the policy a named
-  class: an ambient URL set for a partner delivery cannot re-point every other client in the same
-  request. `grep -rn RuntimeHostFromContext` lists every client that can be re-pointed at all.
-- **SSRF policy is ON.** https only; loopback / RFC1918 / link-local / cloud-metadata refused, by
-  name AND by every address the name resolves to; redirects are not followed by the transport but
-  re-judged hop by hop, so a partner URL that 302s at `169.254.169.254` is refused rather than
-  obeyed. The ONLY way to relax it is to say so out loud:
-  `new RuntimeHostFromContextAllowingInternalAddresses('local emulator on 127.0.0.1', resolver)`.
-- **`@AuthOidc` / `@AuthSharedSecret` endpoints are refused at bind time.** Both mint a credential
-  for a peer we chose; a destination that arrives per call has no honest audience, and minting one
-  would hand our credential to whoever registered the URL.
-- **The hop is VISIBLE.** `svcName` is still required under a runtime policy: it is the identity the
-  destination gets on the runtime architecture graph, drawn as an external node of kind `runtime`.
-
-## Outbound filters
-
-`createRpcClient`'s 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`:
+- **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
-class HmacSigningFilter extends Filter<ClientRequest, Response> {
-    constructor(private readonly secret: string) { super(); }
-
-    async filter(request: ClientRequest, next: Service<ClientRequest, Response>): Promise<Response> {
-        // request.body is the EXACT serialized bytes the transport will send — sign those.
-        const mac = createHmac('sha256', this.secret).update(request.body ?? '').digest('hex');
-        request.headers.set('x-signature', `sha256=${mac}`);
-        return next.invoke(request);
+@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}`]]);
     }
 }
-```
 
-Highest priority runs OUTERMOST, matching the server's `FilterMatcher`. The framework's own
-built-ins occupy 1000 (the runtime base-URL override) and 900 (the SSRF guard), so an app filter
-below them sees the destination already settled.
+// AppModule.ts
+options.bind(WEBHOOK_SIGNER_CALLBACK).to(PartnerHmacSigner);
+```
 
-Signing over `request.body` is the whole reason this seam exists: the bytes a filter signs are the
-bytes transmitted, byte for byte. Without it a sender has to hand-serialize and post the payload
-itself, because a raw HTTP library that re-serializes internally signs one sequence and sends
-another.
+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.700",
+  "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.700",
-    "@webpieces/core-util": "0.4.700",
-    "@webpieces/gcp-identity": "0.4.700",
-    "@webpieces/http-client-core": "0.4.700",
+    "@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

@@ -5,6 +5,12 @@
  *
  * 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 {
     /**
@@ -17,7 +23,11 @@ export declare abstract class AddressResolver {
      */
     abstract resolve(hostname: string): Promise<string[]>;
 }
-/** The real one: node's DNS resolver, asking for every address family. */
+/**
+ * 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

@@ -11,11 +11,21 @@ const core_context_1 = require("@webpieces/core-context");
  *
  * 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. */
+/**
+ * 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 });
@@ -24,6 +34,6 @@ let DnsAddressResolver = class DnsAddressResolver extends AddressResolver {
 };
 exports.DnsAddressResolver = DnsAddressResolver;
 exports.DnsAddressResolver = DnsAddressResolver = tslib_1.__decorate([
-    (0, core_context_1.provideFrameworkSingleton)()
+    (0, core_context_1.provideFrameworkSingletonDefaultForApi)(AddressResolver)
 ], DnsAddressResolver);
 //# sourceMappingURL=AddressResolver.js.map

package/src/AddressResolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"AddressResolver.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/AddressResolver.ts"],"names":[],"mappings":";;;;AACA,gDAA2C;AAC3C,0DAAoE;AAEpE;;;;;;;GAOG;AACH,MAAsB,eAAe;CAUpC;AAVD,0CAUC;AAED,0EAA0E;AAEnE,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,wCAAyB,GAAE;GACf,kBAAkB,CAK9B","sourcesContent":["import type { LookupAddress } from 'node:dns';\nimport { lookup } from 'node:dns/promises';\nimport { provideFrameworkSingleton } 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 */\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/** The real one: node's DNS resolver, asking for every address family. */\n@provideFrameworkSingleton()\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"]}
+{"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

@@ -1,4 +1,3 @@
-import { HostPolicy } from './HostPolicy';
 /**
  * Per-client STATE for a server-side HTTP client — nothing else. A plain class; it extends nothing
  * and is unrelated to the browser package's ClientConfig, because the two answer "what URL?"
@@ -6,51 +5,46 @@ import { HostPolicy } from './HostPolicy';
  *
  * Collaborators (RequestContextHeaders, Secrets) are NOT config: they are dependencies of
  * {@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 third
- * argument to `createRpcClient` rather than a field here.
+ * 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.
+     * The service name, and the ONE thing that decides where this client points.
      *
-     * Under {@link DeployedServiceHost} 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.
+     * 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.
      *
-     * Under a runtime host policy nothing is derived from it, but it is still required and still
-     * load-bearing: it is the IDENTITY this outbound hop gets on the runtime architecture graph
-     * ('partner-webhooks'), which is what stops a partner delivery being an invisible edge.
+     * 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;
-    /**
-     * WHERE this client's requests go: a service we deploy, or a host supplied per call at
-     * runtime. REQUIRED — see {@link HostPolicy} for why there is no default. The old
-     * one-argument `new ClientConfig('svc')` no longer compiles; write
-     * `new ClientConfig('svc', new DeployedServiceHost())` for the behaviour it used to have.
-     */
-    readonly hostPolicy: HostPolicy;
     constructor(
     /**
-     * The service name.
+     * The service name, and the ONE thing that decides where this client points.
      *
-     * Under {@link DeployedServiceHost} 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.
+     * 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.
      *
-     * Under a runtime host policy nothing is derived from it, but it is still required and still
-     * load-bearing: it is the IDENTITY this outbound hop gets on the runtime architecture graph
-     * ('partner-webhooks'), which is what stops a partner delivery being an invisible edge.
-     */
-    svcName: string, 
-    /**
-     * WHERE this client's requests go: a service we deploy, or a host supplied per call at
-     * runtime. REQUIRED — see {@link HostPolicy} for why there is no default. The old
-     * one-argument `new ClientConfig('svc')` no longer compiles; write
-     * `new ClientConfig('svc', new DeployedServiceHost())` for the behaviour it used to have.
+     * 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.
      */
-    hostPolicy: HostPolicy);
+    svcName: string);
 }

package/src/ClientConfig.js

@@ -8,36 +8,36 @@ exports.ClientConfig = void 0;
  *
  * Collaborators (RequestContextHeaders, Secrets) are NOT config: they are dependencies of
  * {@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 third
- * argument to `createRpcClient` rather than a field here.
+ * 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;
-    hostPolicy;
     constructor(
     /**
-     * The service name.
+     * The service name, and the ONE thing that decides where this client points.
      *
-     * Under {@link DeployedServiceHost} 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.
+     * 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.
      *
-     * Under a runtime host policy nothing is derived from it, but it is still required and still
-     * load-bearing: it is the IDENTITY this outbound hop gets on the runtime architecture graph
-     * ('partner-webhooks'), which is what stops a partner delivery being an invisible edge.
-     */
-    svcName, 
-    /**
-     * WHERE this client's requests go: a service we deploy, or a host supplied per call at
-     * runtime. REQUIRED — see {@link HostPolicy} for why there is no default. The old
-     * one-argument `new ClientConfig('svc')` no longer compiles; write
-     * `new ClientConfig('svc', new DeployedServiceHost())` for the behaviour it used to have.
+     * 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.
      */
-    hostPolicy) {
+    svcName) {
         this.svcName = svcName;
-        this.hostPolicy = hostPolicy;
     }
 }
 exports.ClientConfig = ClientConfig;

package/src/ClientConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientConfig.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-node/src/ClientConfig.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;GASG;AACH,MAAa,YAAY;IAeD;IAOA;IArBpB;IACI;;;;;;;;;;;;OAYG;IACa,OAAe;IAC/B;;;;;OAKG;IACa,UAAsB;QAPtB,YAAO,GAAP,OAAO,CAAQ;QAOf,eAAU,GAAV,UAAU,CAAY;IACvC,CAAC;CACP;AAxBD,oCAwBC","sourcesContent":["import { HostPolicy } from './HostPolicy';\n\n/**\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 third\n * argument to `createRpcClient` rather than a field here.\n */\nexport class ClientConfig {\n    constructor(\n        /**\n         * The service name.\n         *\n         * Under {@link DeployedServiceHost} the URL is DERIVED from it (on GCP: same project, same\n         * region — the Cloud Run service name, so you maintain no URL table), which works across\n         * demo/qa/prod. Anything the derivation cannot describe — a localhost port, another\n         * region/project, a non-Cloud-Run host — is a `ClientRegistry` mapping registered at\n         * startup, NOT a per-client URL.\n         *\n         * Under a runtime host policy nothing is derived from it, but it is still required and still\n         * load-bearing: it is the IDENTITY this outbound hop gets on the runtime architecture graph\n         * ('partner-webhooks'), which is what stops a partner delivery being an invisible edge.\n         */\n        public readonly svcName: string,\n        /**\n         * WHERE this client's requests go: a service we deploy, or a host supplied per call at\n         * runtime. REQUIRED — see {@link HostPolicy} for why there is no default. The old\n         * one-argument `new ClientConfig('svc')` no longer compiles; write\n         * `new ClientConfig('svc', new DeployedServiceHost())` for the behaviour it used to have.\n         */\n        public readonly hostPolicy: HostPolicy,\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,6 +1,6 @@
 import { Provider } from '@webpieces/core-context';
 import type { ApiPrototype } from '@webpieces/http-client-core';
-import { ClientFilterDefinition } from '@webpieces/http-client-core';
+import type { ClientFilters } from '@webpieces/http-client-core';
 import { ClientConfig } from './ClientConfig';
 import { NodeProxyClient } from './NodeProxyClient';
 /**
@@ -14,25 +14,27 @@ import { NodeProxyClient } from './NodeProxyClient';
  * Inject it and ask for a typed client per contract:
  * ```typescript
  * // same project + region as this container; the URL is derived, you maintain nothing
- * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2', new DeployedServiceHost()), []);
+ * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2'));
  *
  * // to reach somewhere derivation cannot describe (other region/project, non-Cloud-Run, localhost),
  * // register it once at startup — the client still carries only the svcName:
  * //   ClientRegistry.addUrlMapping('legacy', 'https://legacy.corp');
- * const legacy = factory.createRpcClient(LegacyApi, new ClientConfig('legacy', new DeployedServiceHost()), []);
+ * const legacy = factory.createRpcClient(LegacyApi, new ClientConfig('legacy'));
  *
  * const response = await server2.fetchValue(req);   // inside a RequestContext
  * ```
  *
- * A destination that is DATA rather than deployment — a URL a partner registered — names a runtime
- * host policy instead, and typically installs a signing filter over the exact bytes:
+ * 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 RuntimeHostFromContext(new DnsAddressResolver())),
- *     [new ClientFilterDefinition(500, new HmacSigningFilter(secret))],
- * );
+ * 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`
@@ -50,13 +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 and its host policy)
-     * @param filters - This client's OUTBOUND filters, each with the priority it runs at (highest
-     *        OUTERMOST). They wrap the send, so a filter sees the final URL, may add headers, and
-     *        may replace `ClientRequest.body` — the exact bytes transmitted, which is what makes
-     *        signing possible without hand-serializing. Pass `[]` for a client that needs none;
-     *        the argument is REQUIRED so "this client signs nothing" is written down rather than
-     *        inferred from an omitted argument.
+     * @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, filters: ClientFilterDefinition[]): T;
+    createRpcClient<T extends object>(apiPrototype: ApiPrototype<T>, config: ClientConfig, filters?: ClientFilters): T;
 }

package/src/ClientHttpFactory.js

@@ -21,25 +21,27 @@ const NodeProxyClient_1 = require("./NodeProxyClient");
  * Inject it and ask for a typed client per contract:
  * ```typescript
  * // same project + region as this container; the URL is derived, you maintain nothing
- * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2', new DeployedServiceHost()), []);
+ * const server2 = factory.createRpcClient(Server2Api, new ClientConfig('server2'));
  *
  * // to reach somewhere derivation cannot describe (other region/project, non-Cloud-Run, localhost),
  * // register it once at startup — the client still carries only the svcName:
  * //   ClientRegistry.addUrlMapping('legacy', 'https://legacy.corp');
- * const legacy = factory.createRpcClient(LegacyApi, new ClientConfig('legacy', new DeployedServiceHost()), []);
+ * const legacy = factory.createRpcClient(LegacyApi, new ClientConfig('legacy'));
  *
  * const response = await server2.fetchValue(req);   // inside a RequestContext
  * ```
  *
- * A destination that is DATA rather than deployment — a URL a partner registered — names a runtime
- * host policy instead, and typically installs a signing filter over the exact bytes:
+ * 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 RuntimeHostFromContext(new DnsAddressResolver())),
- *     [new ClientFilterDefinition(500, new HmacSigningFilter(secret))],
- * );
+ * 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`
@@ -59,19 +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 and its host policy)
-     * @param filters - This client's OUTBOUND filters, each with the priority it runs at (highest
-     *        OUTERMOST). They wrap the send, so a filter sees the final URL, may add headers, and
-     *        may replace `ClientRequest.body` — the exact bytes transmitted, which is what makes
-     *        signing possible without hand-serializing. Pass `[]` for a client that needs none;
-     *        the argument is REQUIRED so "this client signs nothing" is written down rather than
-     *        inferred from an omitted argument.
+     * @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, 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, filters);
+        proxyClient.init(apiPrototype, config, filters === undefined ? [] : [...filters]);
         return (0, http_client_core_1.buildClientProxy)(apiPrototype, proxyClient);
     }
 };