@webpieces/core-util 0.4.798 → 0.4.799

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.798",
+  "version": "0.4.799",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/ContextKey.d.ts

@@ -14,6 +14,13 @@
  *                 this HTTP header name (inbound request -> context, and context ->
  *                 outbound request). e.g. 'x-request-id'. When UNSET, the key is
  *                 context-only and never leaves the process (method-meta, recorder).
+ * - `responseHeader` OPTIONAL, and the exact MIRROR of `httpHeader`. When set, this key is written
+ *                 back onto every RESPONSE under this header name, and a webpieces client reads it
+ *                 off the response into the CALLER's context — so a value travels UP the call tree
+ *                 hop by hop. Independent of `httpHeader`: a key may ride requests, responses,
+ *                 both, or neither.
+ * - `responseMerge` HOW a response value combines with what the caller already holds — `collect`
+ *                 (the default), `first` or `last`. See {@link ResponseMerge}.
  * - `trust`       REQUIRED, and stated by WHICH FACTORY you call. See below.
  * - `maskInLogs`  When true, the value is masked (partially) in logs. This is about
  *                 LOG REDACTION and has NOTHING to do with `trust` — a userId is
@@ -120,6 +127,24 @@ export type AnyUntrustedContextKey = ContextKey<unknown, 'untrusted'>;
  * honest.
  */
 export type AnyContextKey = AnyTrustedContextKey | AnyUntrustedContextKey;
+/**
+ * HOW a RESPONSE value merges with whatever the caller's context already holds for the same key.
+ *
+ * Declared per KEY, because fan-out is the normal case and not the exception: one inbound request
+ * that calls five services produces FIVE values for one response key, and a silent last-write-wins
+ * keeps one of them and throws four away without saying so. Naming the policy on the key is what
+ * makes that choice visible at the definition rather than emergent at runtime.
+ *
+ * - `collect`  APPEND to a list (the value type is therefore `string[]`). The default, and the right
+ *              answer for every DIAGNOSTIC key — cache status, backend version, a downstream warning
+ *              — where "all five" is the interesting answer.
+ * - `first`    KEEP what is already there; the first value seen wins. This is the policy for a key
+ *              whose value belongs to THIS hop and must not be replaced by a callee's echo of it —
+ *              {@link WebpiecesCoreHeaders.REQUEST_ID} is exactly that.
+ * - `last`     OVERWRITE. The last response seen wins. Use it only where a single, latest value is
+ *              genuinely meant.
+ */
+export type ResponseMerge = 'collect' | 'first' | 'last';
 export declare class ContextKey<V, T extends Trust = Trust> {
     /**
      * Phantom marker carrying the value type {@link V}. It has no runtime existence (`declare`, never
@@ -141,6 +166,22 @@ export declare class ContextKey<V, T extends Trust = Trust> {
      * 'x-request-id'). Undefined = context-only, never transferred.
      */
     readonly httpHeader?: string;
+    /**
+     * HTTP header name this key is written back on the RESPONSE under (e.g. 'x-request-id').
+     * Undefined = this key never rides a response.
+     *
+     * It is the exact mirror of {@link httpHeader}, and the two are INDEPENDENT: a key may travel
+     * out on requests only, back on responses only, both, or neither. The server writes every key
+     * that sets it onto every response from one choke point; a webpieces client reads it back off
+     * the response into the CALLER's context, which is what lets a value climb the call tree hop by
+     * hop with nothing in between mentioning HTTP.
+     */
+    readonly responseHeader?: string;
+    /**
+     * How a response value merges with what the context already holds — see {@link ResponseMerge}.
+     * Only consulted when {@link responseHeader} is set; ignored otherwise.
+     */
+    readonly responseMerge: ResponseMerge;
     /** The runtime twin of the phantom {@link __trust}. See the class doc. */
     readonly trust: Trust;
     /**
@@ -169,7 +210,7 @@ export declare class ContextKey<V, T extends Trust = Trust> {
      *
      * @param provenance WHY it is trusted, in prose. Required — see {@link ContextKey.provenance}.
      */
-    static trusted<V>(name: string, provenance: string, httpHeader?: string, maskInLogs?: boolean, isLogged?: boolean): ContextKey<V, 'trusted'>;
+    static trusted<V>(name: string, provenance: string, httpHeader?: string, maskInLogs?: boolean, isLogged?: boolean, responseHeader?: string, responseMerge?: ResponseMerge): ContextKey<V, 'trusted'>;
     /**
      * A key whose value is merely ASSERTED by whoever sent it — a browser-minted actionId, a
      * client-supplied recording flag, an in-process log tag. Perfectly fine to use; just never
@@ -178,9 +219,23 @@ export declare class ContextKey<V, T extends Trust = Trust> {
      * This is the DEFAULT choice in the sense that most keys are this — but it is never the default
      * VALUE: you still type the word, so reading a key definition always tells you which it is.
      */
-    static untrusted<V>(name: string, httpHeader?: string, maskInLogs?: boolean, isLogged?: boolean): ContextKey<V, 'untrusted'>;
+    static untrusted<V>(name: string, httpHeader?: string, maskInLogs?: boolean, isLogged?: boolean, responseHeader?: string, responseMerge?: ResponseMerge): ContextKey<V, 'untrusted'>;
     /** True when this key is transferred over HTTP (has an httpHeader). */
     isTransferred(): boolean;
+    /** True when this key rides back on the RESPONSE (has a responseHeader). */
+    isResponseTransferred(): boolean;
+    /**
+     * The value to STORE for this key given what the context already holds and what one response
+     * just carried, per this key's {@link responseMerge}.
+     *
+     * It lives on the KEY rather than in the two client packages because the policy is a property of
+     * the declaration, and because node and browser must not be able to answer it differently.
+     *
+     * `collect` returns an ARRAY, which is why a collecting key's value type is `string[]`: a
+     * non-array `existing` (somebody put a scalar under a collecting key) is folded in as the first
+     * element rather than thrown away, so the fan-out answer is never silently truncated.
+     */
+    mergeResponseValue(existing: unknown, incoming: string): unknown;
     /**
      * True for a key built by {@link trusted}. Trust is BINARY, so this ONE predicate answers it in
      * both directions and there is deliberately no `isUntrusted()` twin. The RUNTIME check used by the

package/src/ContextKey.js

@@ -15,6 +15,13 @@
  *                 this HTTP header name (inbound request -> context, and context ->
  *                 outbound request). e.g. 'x-request-id'. When UNSET, the key is
  *                 context-only and never leaves the process (method-meta, recorder).
+ * - `responseHeader` OPTIONAL, and the exact MIRROR of `httpHeader`. When set, this key is written
+ *                 back onto every RESPONSE under this header name, and a webpieces client reads it
+ *                 off the response into the CALLER's context — so a value travels UP the call tree
+ *                 hop by hop. Independent of `httpHeader`: a key may ride requests, responses,
+ *                 both, or neither.
+ * - `responseMerge` HOW a response value combines with what the caller already holds — `collect`
+ *                 (the default), `first` or `last`. See {@link ResponseMerge}.
  * - `trust`       REQUIRED, and stated by WHICH FACTORY you call. See below.
  * - `maskInLogs`  When true, the value is masked (partially) in logs. This is about
  *                 LOG REDACTION and has NOTHING to do with `trust` — a userId is
@@ -98,6 +105,22 @@ class ContextKey {
      * 'x-request-id'). Undefined = context-only, never transferred.
      */
     httpHeader;
+    /**
+     * HTTP header name this key is written back on the RESPONSE under (e.g. 'x-request-id').
+     * Undefined = this key never rides a response.
+     *
+     * It is the exact mirror of {@link httpHeader}, and the two are INDEPENDENT: a key may travel
+     * out on requests only, back on responses only, both, or neither. The server writes every key
+     * that sets it onto every response from one choke point; a webpieces client reads it back off
+     * the response into the CALLER's context, which is what lets a value climb the call tree hop by
+     * hop with nothing in between mentioning HTTP.
+     */
+    responseHeader;
+    /**
+     * How a response value merges with what the context already holds — see {@link ResponseMerge}.
+     * Only consulted when {@link responseHeader} is set; ignored otherwise.
+     */
+    responseMerge;
     /** The runtime twin of the phantom {@link __trust}. See the class doc. */
     trust;
     /**
@@ -116,13 +139,15 @@ class ContextKey {
      * without stating its trust level: a defaulted trust argument would make the permissive branch
      * the shortest thing to type and impossible to grep.
      */
-    constructor(name, trust, provenance, httpHeader, maskInLogs, isLogged) {
+    constructor(name, trust, provenance, httpHeader, maskInLogs, isLogged, responseHeader, responseMerge) {
         this.name = name;
         this.trust = trust;
         this.provenance = provenance;
         this.httpHeader = httpHeader;
         this.maskInLogs = maskInLogs;
         this.isLogged = isLogged;
+        this.responseHeader = responseHeader;
+        this.responseMerge = responseMerge;
     }
     /**
      * A key whose value the framework PROVED — a verified JWT claim, or a fact an app derived from a
@@ -134,8 +159,8 @@ class ContextKey {
      * @param provenance WHY it is trusted, in prose. Required — see {@link ContextKey.provenance}.
      */
     // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor; the trust branch must be part of the call, not a defaulted argument
-    static trusted(name, provenance, httpHeader, maskInLogs = false, isLogged = true) {
-        return new ContextKey(name, 'trusted', provenance, httpHeader, maskInLogs, isLogged);
+    static trusted(name, provenance, httpHeader, maskInLogs = false, isLogged = true, responseHeader, responseMerge = 'collect') {
+        return new ContextKey(name, 'trusted', provenance, httpHeader, maskInLogs, isLogged, responseHeader, responseMerge);
     }
     /**
      * A key whose value is merely ASSERTED by whoever sent it — a browser-minted actionId, a
@@ -146,13 +171,43 @@ class ContextKey {
      * VALUE: you still type the word, so reading a key definition always tells you which it is.
      */
     // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor; see trusted()
-    static untrusted(name, httpHeader, maskInLogs = false, isLogged = true) {
-        return new ContextKey(name, 'untrusted', undefined, httpHeader, maskInLogs, isLogged);
+    static untrusted(name, httpHeader, maskInLogs = false, isLogged = true, responseHeader, responseMerge = 'collect') {
+        return new ContextKey(name, 'untrusted', undefined, httpHeader, maskInLogs, isLogged, responseHeader, responseMerge);
     }
     /** True when this key is transferred over HTTP (has an httpHeader). */
     isTransferred() {
         return this.httpHeader !== undefined;
     }
+    /** True when this key rides back on the RESPONSE (has a responseHeader). */
+    isResponseTransferred() {
+        return this.responseHeader !== undefined;
+    }
+    /**
+     * The value to STORE for this key given what the context already holds and what one response
+     * just carried, per this key's {@link responseMerge}.
+     *
+     * It lives on the KEY rather than in the two client packages because the policy is a property of
+     * the declaration, and because node and browser must not be able to answer it differently.
+     *
+     * `collect` returns an ARRAY, which is why a collecting key's value type is `string[]`: a
+     * non-array `existing` (somebody put a scalar under a collecting key) is folded in as the first
+     * element rather than thrown away, so the fan-out answer is never silently truncated.
+     */
+    // webpieces-disable no-any-unknown -- the context store is honestly type-erased; the key's own V types the public accessors
+    mergeResponseValue(existing, incoming) {
+        switch (this.responseMerge) {
+            case 'first':
+                return existing === undefined ? incoming : existing;
+            case 'last':
+                return incoming;
+            case 'collect':
+                if (Array.isArray(existing)) {
+                    // webpieces-disable no-any-unknown -- a collect key's accumulated list is honestly type-erased here, exactly like every other key-agnostic serialization read
+                    return [...existing, incoming];
+                }
+                return existing === undefined ? [incoming] : [existing, incoming];
+        }
+    }
     /**
      * True for a key built by {@link trusted}. Trust is BINARY, so this ONE predicate answers it in
      * both directions and there is deliberately no `isUntrusted()` twin. The RUNTIME check used by the

package/src/ContextKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextKey.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextKey.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;;;AAyCH,MAAa,UAAU;IAgBnB,qEAAqE;IAC5D,IAAI,CAAS;IAEtB;;;OAGG;IACM,UAAU,CAAU;IAE7B,0EAA0E;IACjE,KAAK,CAAQ;IAEtB;;;;;OAKG;IACM,UAAU,CAAU;IAE7B,4FAA4F;IACnF,UAAU,CAAU;IAE7B,6EAA6E;IACpE,QAAQ,CAAU;IAE3B;;;;OAIG;IACH,YACI,IAAY,EACZ,KAAY,EACZ,UAA8B,EAC9B,UAA8B,EAC9B,UAAmB,EACnB,QAAiB;QAEjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;IAED;;;;;;;;OAQG;IACH,6KAA6K;IAC7K,MAAM,CAAC,OAAO,CACV,IAAY,EACZ,UAAkB,EAClB,UAAmB,EACnB,UAAU,GAAG,KAAK,EAClB,QAAQ,GAAG,IAAI;QAEf,OAAO,IAAI,UAAU,CACjB,IAAI,EACJ,SAAS,EACT,UAAU,EACV,UAAU,EACV,UAAU,EACV,QAAQ,CACX,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACH,uHAAuH;IACvH,MAAM,CAAC,SAAS,CACZ,IAAY,EACZ,UAAmB,EACnB,UAAU,GAAG,KAAK,EAClB,QAAQ,GAAG,IAAI;QAEf,OAAO,IAAI,UAAU,CACjB,IAAI,EACJ,WAAW,EACX,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,CACX,CAAC;IACN,CAAC;IAED,uEAAuE;IACvE,aAAa;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS;QACL,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IACpC,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,KAAa;QACrB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACnB,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;QACzB,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACV,OAAO,+BAA+B,CAAC;QAC3C,CAAC;aAAM,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC;YACnB,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC;QACzC,CAAC;aAAM,CAAC;YACJ,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACpE,CAAC;IACL,CAAC;CACJ;AArKD,gCAqKC","sourcesContent":["/**\n * ContextKey - a single key that travels in the request's \"magic context\"\n * (RequestContext on the server, MutableContextStore in the browser).\n *\n * This ONE class replaces the old split of `Header` (interface) + `PlatformHeader`\n * (class) + `ContextKey` (class). Every context value — whether it rides over HTTP\n * (request-id, tenant, authorization) or stays in-process (method-meta, the\n * TestCaseRecorder) — is a `ContextKey`.\n *\n * The fields are named for what they DO (flipped from the old model):\n * - `name`        ALWAYS set. The context storage key, the log/MDC key, and the\n *                 recorder name. e.g. 'requestId', 'tenantId', 'authorization'.\n * - `httpHeader`  OPTIONAL. When set, this key is transferred over the wire under\n *                 this HTTP header name (inbound request -> context, and context ->\n *                 outbound request). e.g. 'x-request-id'. When UNSET, the key is\n *                 context-only and never leaves the process (method-meta, recorder).\n * - `trust`       REQUIRED, and stated by WHICH FACTORY you call. See below.\n * - `maskInLogs`  When true, the value is masked (partially) in logs. This is about\n *                 LOG REDACTION and has NOTHING to do with `trust` — a userId is\n *                 trusted AND fully logged; a bearer token is untrusted AND masked.\n *                 (Formerly `isSecured`, renamed because sitting next to `trust` the\n *                 old name read as \"this value is secure\", which it never meant.)\n * - `isLogged`    Defaults to true. When false, the value is NEVER logged (used for\n *                 object-valued/internal keys like the recorder or method-meta that\n *                 must not be serialized into log lines).\n *\n * ## TRUST — the whole point of this class\n *\n * A context value is either something the framework PROVED (`trusted`) or something a\n * caller merely ASSERTED (`untrusted`). That distinction is invisible in a `Map<string,\n * string>`, so code — human- or AI-written — routinely reads a spoofable header as if it\n * were an authenticated fact. `userId` is the canonical example: it is a verified JWT\n * claim on one route and an attacker-supplied `x-user-id` on the next, and nothing in the\n * old API told them apart.\n *\n * So trust is declared ON THE KEY, at the single place the key is defined, and it is\n * enforced at BOTH ends:\n *\n *   ContextKey.trusted<string>('userId', 'jwt claim `sub`, stamped by AuthFilter', 'x-user-id')\n *   ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid')\n *\n * `grep -rn \"ContextKey.trusted\"` therefore enumerates every high-assurance field in the\n * codebase, each with its `provenance` string on the same line saying WHY it is trusted.\n * That is the AI-facing payoff: the answer is one grep, not an audit.\n *\n * The constructor is PRIVATE — you cannot make a key without picking a branch, and there\n * is no default. A default would make the permissive branch the shortest thing to type,\n * which is exactly the \"widening that is an ABSENCE rather than a token\" that\n * `.claude/rules/no-backwards-compat.md`\n * rejects. `provenance` is a REQUIRED positional argument on the trusted factory only, so\n * \"trusted with no stated reason\" cannot be written down.\n *\n * ## What makes the `trusted` label HONEST at runtime\n *\n * The label would be a lie if anything could write a trusted key from an unverified\n * source. Three enforced facts prevent that:\n *\n * 1. WRITES are typed: only `RequestContext.putTrusted(key, value)` accepts a trusted key,\n *    and it is a distinct, greppable verb an app has to type on purpose.\n * 2. INBOUND wire values for trusted keys never enter the context directly.\n *    `RequestContextHeaders.fillFromRequest` stashes them as PENDING, and `AuthFilter`\n *    admits them only after it knows who the caller is (see {@link PendingWireTrust}).\n * 3. READS are typed: `getTrusted(key)` does not compile for an untrusted key, and\n *    `getUntrusted(key)` does not compile for a trusted one. Picking a verb is\n *    unavoidable, so a reader always knows which kind of value it is holding.\n *\n * Trusted keys DO keep their `httpHeader` — service-to-service propagation of a verified\n * userId is a first-class requirement, not a hole. It is safe because rule 2 gates it on\n * the endpoint's own auth mode: a route that verified WHO called it (`@WpAuthOidc`,\n * `@WpAuthSharedSecret`) accepts the caller's trusted headers; a route reachable by a\n * browser (`@WpAuthJwt`, public) does not.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n *\n * The type parameter `V` is the TYPE OF THE VALUE stored under this key — `string` for the wire/log\n * keys (requestId, tenantId, ...), `ApiCallInfo` for the structured api tag, `TestCaseRecorder` for\n * the recorder. It is REQUIRED (no default): every key must state what it holds. A heterogeneous\n * store CANNOT be a `Record<string, string>` — the recorder and the api payload are not strings — so\n * instead each KEY carries its own value type, and the typed accessors INFER it from the key. That\n * keeps the backing Map honestly type-erased while the public surface stays fully typed: a caller\n * never asserts a value type, the key already declares it. A genuinely mixed collection of keys is\n * spelled explicitly as `AnyContextKey[]`, so \"I mean a mixed bag\" is a visible, deliberate\n * statement, never a default.\n *\n * The type parameter `T` is the TRUST LEVEL, carried as a phantom type so the accessor verbs can\n * reject the wrong kind of key at COMPILE time rather than throwing at runtime (`.claude/rules/no-backwards-compat.md`\n * treats a\n * runtime throw standing in for an expressible type as a defect).\n */\n\n/** The two kinds of context value. See the {@link ContextKey} class doc. */\nexport type Trust = 'trusted' | 'untrusted';\n\n/**\n * A trusted key of any value type — what {@link ContextTuple} carries, and what the trusted write\n * verb accepts when the value type is not statically known.\n */\n// webpieces-disable no-any-unknown -- the ONE sanctioned `unknown`: a key whose value type is deliberately unconstrained (mixed-bag collections / key-agnostic code). Every other site names one of these aliases instead of repeating it.\nexport type AnyTrustedContextKey = ContextKey<unknown, 'trusted'>;\n\n/**\n * An untrusted key of any value type — what the {@link ApiCallContext} seam stamps, so that seam\n * cannot be used as a side door to forge a trusted value.\n */\n// webpieces-disable no-any-unknown -- same sanctioned mixed-bag alias, narrowed to the untrusted branch\nexport type AnyUntrustedContextKey = ContextKey<unknown, 'untrusted'>;\n\n/**\n * A ContextKey whose value type is intentionally UNCONSTRAINED — a \"key of any value type\". Use this\n * (never a bare `ContextKey`, which no longer compiles) for genuinely mixed-bag collections and\n * key-agnostic code: `ALL_HEADERS: AnyContextKey[]`, the {@link HeaderRegistry}'s key arrays, a\n * reader that takes whatever key it is handed. Naming the mixed case makes \"I mean any key\" a visible,\n * deliberate statement.\n *\n * It is a UNION of the two branches, not `ContextKey<unknown, Trust>`, and that is load-bearing rather\n * than cosmetic. Trust is BINARY, so `if (key.isTrusted())` should type BOTH of its branches — and it\n * does only against a union: TypeScript narrows the negative of a `this is X` predicate by dropping the\n * union constituents assignable to `X`, so the `else` here lands on {@link AnyUntrustedContextKey} and\n * goes straight to `putUntrusted` with no cast. Written as one type with a mixed `Trust` parameter\n * there would be nothing to drop, the `else` would stay mixed, and the class would need a second\n * `isUntrusted()` predicate to type the branch its own negative already decided — one runtime question\n * with two spellings, which is the shim shape `.claude/rules/no-backwards-compat.md` rejects.\n *\n * Mixed in TRUST as well as in value type, so it is READ-ONLY territory: `getAny(key)` takes one, but\n * no WRITE verb does. A write must name the trust level, which is what keeps the `trusted` label\n * honest.\n */\nexport type AnyContextKey = AnyTrustedContextKey | AnyUntrustedContextKey;\n\nexport class ContextKey<V, T extends Trust = Trust> {\n    /**\n     * Phantom marker carrying the value type {@link V}. It has no runtime existence (`declare`, never\n     * assigned) — it exists ONLY so the read verbs return `V` and the write verbs check `value`\n     * against `V`, both inferred straight from the key. Optional, so `ContextKey<A>` stays assignable\n     * to `AnyContextKey` (i.e. `ContextKey<unknown>`) — arrays of mixed keys keep working.\n     */\n    declare readonly __valueType?: V;\n\n    /**\n     * Phantom marker carrying the trust level {@link T} — the reason `getTrusted(SOME_UNTRUSTED_KEY)`\n     * is a COMPILE error and not a runtime throw. Like `__valueType` it never exists at runtime; the\n     * runtime answer is the {@link trust} field below, which the fill/reconcile path reads.\n     */\n    declare readonly __trust?: T;\n\n    /** Context storage key + log/MDC key + recorder name. Always set. */\n    readonly name: string;\n\n    /**\n     * HTTP header name when this key is transferred over the wire (e.g.\n     * 'x-request-id'). Undefined = context-only, never transferred.\n     */\n    readonly httpHeader?: string;\n\n    /** The runtime twin of the phantom {@link __trust}. See the class doc. */\n    readonly trust: Trust;\n\n    /**\n     * WHY this key is trusted, in prose — 'jwt claim `sub`, stamped by AuthFilter', or\n     * 'whatsapp webhook phone number -> user lookup'. Required on a trusted key, absent on an\n     * untrusted one. It exists so that grepping the trusted keys also tells you what proves each\n     * one, without opening another file.\n     */\n    readonly provenance?: string;\n\n    /** Mask this value (partially) in logs. Log redaction only — unrelated to {@link trust}. */\n    readonly maskInLogs: boolean;\n\n    /** Whether this key is logged at all. Default true; false = never logged. */\n    readonly isLogged: boolean;\n\n    /**\n     * PRIVATE — use {@link trusted} or {@link untrusted}. There is deliberately no way to build a key\n     * without stating its trust level: a defaulted trust argument would make the permissive branch\n     * the shortest thing to type and impossible to grep.\n     */\n    private constructor(\n        name: string,\n        trust: Trust,\n        provenance: string | undefined,\n        httpHeader: string | undefined,\n        maskInLogs: boolean,\n        isLogged: boolean,\n    ) {\n        this.name = name;\n        this.trust = trust;\n        this.provenance = provenance;\n        this.httpHeader = httpHeader;\n        this.maskInLogs = maskInLogs;\n        this.isLogged = isLogged;\n    }\n\n    /**\n     * A key whose value the framework PROVED — a verified JWT claim, or a fact an app derived from a\n     * verified credential (a Twilio/WhatsApp webhook's signed phone number looked up to a userId).\n     *\n     * Only `RequestContext.putTrusted` can write one, only `RequestContext.getTrusted` can read one,\n     * and an inbound wire value for one is held PENDING until `AuthFilter` knows who the caller is.\n     *\n     * @param provenance WHY it is trusted, in prose. Required — see {@link ContextKey.provenance}.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor; the trust branch must be part of the call, not a defaulted argument\n    static trusted<V>(\n        name: string,\n        provenance: string,\n        httpHeader?: string,\n        maskInLogs = false,\n        isLogged = true,\n    ): ContextKey<V, 'trusted'> {\n        return new ContextKey<V, 'trusted'>(\n            name,\n            'trusted',\n            provenance,\n            httpHeader,\n            maskInLogs,\n            isLogged,\n        );\n    }\n\n    /**\n     * A key whose value is merely ASSERTED by whoever sent it — a browser-minted actionId, a\n     * client-supplied recording flag, an in-process log tag. Perfectly fine to use; just never\n     * an input to an authorization decision.\n     *\n     * This is the DEFAULT choice in the sense that most keys are this — but it is never the default\n     * VALUE: you still type the word, so reading a key definition always tells you which it is.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor; see trusted()\n    static untrusted<V>(\n        name: string,\n        httpHeader?: string,\n        maskInLogs = false,\n        isLogged = true,\n    ): ContextKey<V, 'untrusted'> {\n        return new ContextKey<V, 'untrusted'>(\n            name,\n            'untrusted',\n            undefined,\n            httpHeader,\n            maskInLogs,\n            isLogged,\n        );\n    }\n\n    /** True when this key is transferred over HTTP (has an httpHeader). */\n    isTransferred(): boolean {\n        return this.httpHeader !== undefined;\n    }\n\n    /**\n     * True for a key built by {@link trusted}. Trust is BINARY, so this ONE predicate answers it in\n     * both directions and there is deliberately no `isUntrusted()` twin. The RUNTIME check used by the\n     * inbound fill and the AuthFilter reconciliation; ordinary application code should never need it,\n     * because the typed verbs already made the decision at compile time.\n     *\n     * It is a TYPE PREDICATE, so BOTH branches are typed, with NO cast on either side: the `if` holds a\n     * `ContextKey<V, 'trusted'>` for `putTrusted` / `PendingWireTrust.stash`, and the `else` holds a\n     * `ContextKey<V, 'untrusted'>` for `putUntrusted`. The `else` types only because\n     * {@link AnyContextKey} is a UNION of the two branches — see that alias for why the negative of a\n     * predicate needs something to drop. Before this, every such site wrote `key as\n     * AnyTrustedContextKey`; a cast is exactly the thing an agent copies to the one place it is not\n     * warranted, so the runtime check produces the type it proves instead.\n     *\n     * That is what makes a loop over a mixed `AnyContextKey[]` — the {@link HeaderRegistry} arrays, a\n     * browser-log payload re-stated into a detached scope — safe BY CONSTRUCTION: the loop can only\n     * write a key whose trust it has just tested, and a trusted key cannot reach `putUntrusted` at all,\n     * so a loop fed by a source that proves nothing cannot fabricate a proven value, and nobody has to\n     * remember to filter. That is a limit on the SOURCE, not on the key: a trusted key is written all\n     * the time via `putTrusted`, by an authenticator or by app code that proved the value out of band.\n     */\n    isTrusted(): this is ContextKey<V, 'trusted'> {\n        return this.trust === 'trusted';\n    }\n\n    /**\n     * The value as it should appear in a log line: returned as-is for a normal\n     * key, partially masked when this key sets `maskInLogs`. Masking is length-based:\n     * - Length > 15: first 3 + \"...\" + last 3\n     * - Length 8-15: first 2 + \"...\"\n     * - Length < 8: \"<secure key too short to log>\"\n     */\n    maskForLogs(value: string): string {\n        if (!this.maskInLogs) {\n            return value;\n        }\n        const len = value.length;\n        if (len < 8) {\n            return '<secure key too short to log>';\n        } else if (len <= 15) {\n            return `${value.substring(0, 2)}...`;\n        } else {\n            return `${value.substring(0, 3)}...${value.substring(len - 3)}`;\n        }\n    }\n}\n"]}
+{"version":3,"file":"ContextKey.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextKey.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ContextKey - a single key that travels in the request's \"magic context\"\n * (RequestContext on the server, MutableContextStore in the browser).\n *\n * This ONE class replaces the old split of `Header` (interface) + `PlatformHeader`\n * (class) + `ContextKey` (class). Every context value — whether it rides over HTTP\n * (request-id, tenant, authorization) or stays in-process (method-meta, the\n * TestCaseRecorder) — is a `ContextKey`.\n *\n * The fields are named for what they DO (flipped from the old model):\n * - `name`        ALWAYS set. The context storage key, the log/MDC key, and the\n *                 recorder name. e.g. 'requestId', 'tenantId', 'authorization'.\n * - `httpHeader`  OPTIONAL. When set, this key is transferred over the wire under\n *                 this HTTP header name (inbound request -> context, and context ->\n *                 outbound request). e.g. 'x-request-id'. When UNSET, the key is\n *                 context-only and never leaves the process (method-meta, recorder).\n * - `responseHeader` OPTIONAL, and the exact MIRROR of `httpHeader`. When set, this key is written\n *                 back onto every RESPONSE under this header name, and a webpieces client reads it\n *                 off the response into the CALLER's context — so a value travels UP the call tree\n *                 hop by hop. Independent of `httpHeader`: a key may ride requests, responses,\n *                 both, or neither.\n * - `responseMerge` HOW a response value combines with what the caller already holds — `collect`\n *                 (the default), `first` or `last`. See {@link ResponseMerge}.\n * - `trust`       REQUIRED, and stated by WHICH FACTORY you call. See below.\n * - `maskInLogs`  When true, the value is masked (partially) in logs. This is about\n *                 LOG REDACTION and has NOTHING to do with `trust` — a userId is\n *                 trusted AND fully logged; a bearer token is untrusted AND masked.\n *                 (Formerly `isSecured`, renamed because sitting next to `trust` the\n *                 old name read as \"this value is secure\", which it never meant.)\n * - `isLogged`    Defaults to true. When false, the value is NEVER logged (used for\n *                 object-valued/internal keys like the recorder or method-meta that\n *                 must not be serialized into log lines).\n *\n * ## TRUST — the whole point of this class\n *\n * A context value is either something the framework PROVED (`trusted`) or something a\n * caller merely ASSERTED (`untrusted`). That distinction is invisible in a `Map<string,\n * string>`, so code — human- or AI-written — routinely reads a spoofable header as if it\n * were an authenticated fact. `userId` is the canonical example: it is a verified JWT\n * claim on one route and an attacker-supplied `x-user-id` on the next, and nothing in the\n * old API told them apart.\n *\n * So trust is declared ON THE KEY, at the single place the key is defined, and it is\n * enforced at BOTH ends:\n *\n *   ContextKey.trusted<string>('userId', 'jwt claim `sub`, stamped by AuthFilter', 'x-user-id')\n *   ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid')\n *\n * `grep -rn \"ContextKey.trusted\"` therefore enumerates every high-assurance field in the\n * codebase, each with its `provenance` string on the same line saying WHY it is trusted.\n * That is the AI-facing payoff: the answer is one grep, not an audit.\n *\n * The constructor is PRIVATE — you cannot make a key without picking a branch, and there\n * is no default. A default would make the permissive branch the shortest thing to type,\n * which is exactly the \"widening that is an ABSENCE rather than a token\" that\n * `.claude/rules/no-backwards-compat.md`\n * rejects. `provenance` is a REQUIRED positional argument on the trusted factory only, so\n * \"trusted with no stated reason\" cannot be written down.\n *\n * ## What makes the `trusted` label HONEST at runtime\n *\n * The label would be a lie if anything could write a trusted key from an unverified\n * source. Three enforced facts prevent that:\n *\n * 1. WRITES are typed: only `RequestContext.putTrusted(key, value)` accepts a trusted key,\n *    and it is a distinct, greppable verb an app has to type on purpose.\n * 2. INBOUND wire values for trusted keys never enter the context directly.\n *    `RequestContextHeaders.fillFromRequest` stashes them as PENDING, and `AuthFilter`\n *    admits them only after it knows who the caller is (see {@link PendingWireTrust}).\n * 3. READS are typed: `getTrusted(key)` does not compile for an untrusted key, and\n *    `getUntrusted(key)` does not compile for a trusted one. Picking a verb is\n *    unavoidable, so a reader always knows which kind of value it is holding.\n *\n * Trusted keys DO keep their `httpHeader` — service-to-service propagation of a verified\n * userId is a first-class requirement, not a hole. It is safe because rule 2 gates it on\n * the endpoint's own auth mode: a route that verified WHO called it (`@WpAuthOidc`,\n * `@WpAuthSharedSecret`) accepts the caller's trusted headers; a route reachable by a\n * browser (`@WpAuthJwt`, public) does not.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n *\n * The type parameter `V` is the TYPE OF THE VALUE stored under this key — `string` for the wire/log\n * keys (requestId, tenantId, ...), `ApiCallInfo` for the structured api tag, `TestCaseRecorder` for\n * the recorder. It is REQUIRED (no default): every key must state what it holds. A heterogeneous\n * store CANNOT be a `Record<string, string>` — the recorder and the api payload are not strings — so\n * instead each KEY carries its own value type, and the typed accessors INFER it from the key. That\n * keeps the backing Map honestly type-erased while the public surface stays fully typed: a caller\n * never asserts a value type, the key already declares it. A genuinely mixed collection of keys is\n * spelled explicitly as `AnyContextKey[]`, so \"I mean a mixed bag\" is a visible, deliberate\n * statement, never a default.\n *\n * The type parameter `T` is the TRUST LEVEL, carried as a phantom type so the accessor verbs can\n * reject the wrong kind of key at COMPILE time rather than throwing at runtime (`.claude/rules/no-backwards-compat.md`\n * treats a\n * runtime throw standing in for an expressible type as a defect).\n */\n\n/** The two kinds of context value. See the {@link ContextKey} class doc. */\nexport type Trust = 'trusted' | 'untrusted';\n\n/**\n * A trusted key of any value type — what {@link ContextTuple} carries, and what the trusted write\n * verb accepts when the value type is not statically known.\n */\n// webpieces-disable no-any-unknown -- the ONE sanctioned `unknown`: a key whose value type is deliberately unconstrained (mixed-bag collections / key-agnostic code). Every other site names one of these aliases instead of repeating it.\nexport type AnyTrustedContextKey = ContextKey<unknown, 'trusted'>;\n\n/**\n * An untrusted key of any value type — what the {@link ApiCallContext} seam stamps, so that seam\n * cannot be used as a side door to forge a trusted value.\n */\n// webpieces-disable no-any-unknown -- same sanctioned mixed-bag alias, narrowed to the untrusted branch\nexport type AnyUntrustedContextKey = ContextKey<unknown, 'untrusted'>;\n\n/**\n * A ContextKey whose value type is intentionally UNCONSTRAINED — a \"key of any value type\". Use this\n * (never a bare `ContextKey`, which no longer compiles) for genuinely mixed-bag collections and\n * key-agnostic code: `ALL_HEADERS: AnyContextKey[]`, the {@link HeaderRegistry}'s key arrays, a\n * reader that takes whatever key it is handed. Naming the mixed case makes \"I mean any key\" a visible,\n * deliberate statement.\n *\n * It is a UNION of the two branches, not `ContextKey<unknown, Trust>`, and that is load-bearing rather\n * than cosmetic. Trust is BINARY, so `if (key.isTrusted())` should type BOTH of its branches — and it\n * does only against a union: TypeScript narrows the negative of a `this is X` predicate by dropping the\n * union constituents assignable to `X`, so the `else` here lands on {@link AnyUntrustedContextKey} and\n * goes straight to `putUntrusted` with no cast. Written as one type with a mixed `Trust` parameter\n * there would be nothing to drop, the `else` would stay mixed, and the class would need a second\n * `isUntrusted()` predicate to type the branch its own negative already decided — one runtime question\n * with two spellings, which is the shim shape `.claude/rules/no-backwards-compat.md` rejects.\n *\n * Mixed in TRUST as well as in value type, so it is READ-ONLY territory: `getAny(key)` takes one, but\n * no WRITE verb does. A write must name the trust level, which is what keeps the `trusted` label\n * honest.\n */\nexport type AnyContextKey = AnyTrustedContextKey | AnyUntrustedContextKey;\n\n/**\n * HOW a RESPONSE value merges with whatever the caller's context already holds for the same key.\n *\n * Declared per KEY, because fan-out is the normal case and not the exception: one inbound request\n * that calls five services produces FIVE values for one response key, and a silent last-write-wins\n * keeps one of them and throws four away without saying so. Naming the policy on the key is what\n * makes that choice visible at the definition rather than emergent at runtime.\n *\n * - `collect`  APPEND to a list (the value type is therefore `string[]`). The default, and the right\n *              answer for every DIAGNOSTIC key — cache status, backend version, a downstream warning\n *              — where \"all five\" is the interesting answer.\n * - `first`    KEEP what is already there; the first value seen wins. This is the policy for a key\n *              whose value belongs to THIS hop and must not be replaced by a callee's echo of it —\n *              {@link WebpiecesCoreHeaders.REQUEST_ID} is exactly that.\n * - `last`     OVERWRITE. The last response seen wins. Use it only where a single, latest value is\n *              genuinely meant.\n */\nexport type ResponseMerge = 'collect' | 'first' | 'last';\n\nexport class ContextKey<V, T extends Trust = Trust> {\n    /**\n     * Phantom marker carrying the value type {@link V}. It has no runtime existence (`declare`, never\n     * assigned) — it exists ONLY so the read verbs return `V` and the write verbs check `value`\n     * against `V`, both inferred straight from the key. Optional, so `ContextKey<A>` stays assignable\n     * to `AnyContextKey` (i.e. `ContextKey<unknown>`) — arrays of mixed keys keep working.\n     */\n    declare readonly __valueType?: V;\n\n    /**\n     * Phantom marker carrying the trust level {@link T} — the reason `getTrusted(SOME_UNTRUSTED_KEY)`\n     * is a COMPILE error and not a runtime throw. Like `__valueType` it never exists at runtime; the\n     * runtime answer is the {@link trust} field below, which the fill/reconcile path reads.\n     */\n    declare readonly __trust?: T;\n\n    /** Context storage key + log/MDC key + recorder name. Always set. */\n    readonly name: string;\n\n    /**\n     * HTTP header name when this key is transferred over the wire (e.g.\n     * 'x-request-id'). Undefined = context-only, never transferred.\n     */\n    readonly httpHeader?: string;\n\n    /**\n     * HTTP header name this key is written back on the RESPONSE under (e.g. 'x-request-id').\n     * Undefined = this key never rides a response.\n     *\n     * It is the exact mirror of {@link httpHeader}, and the two are INDEPENDENT: a key may travel\n     * out on requests only, back on responses only, both, or neither. The server writes every key\n     * that sets it onto every response from one choke point; a webpieces client reads it back off\n     * the response into the CALLER's context, which is what lets a value climb the call tree hop by\n     * hop with nothing in between mentioning HTTP.\n     */\n    readonly responseHeader?: string;\n\n    /**\n     * How a response value merges with what the context already holds — see {@link ResponseMerge}.\n     * Only consulted when {@link responseHeader} is set; ignored otherwise.\n     */\n    readonly responseMerge: ResponseMerge;\n\n    /** The runtime twin of the phantom {@link __trust}. See the class doc. */\n    readonly trust: Trust;\n\n    /**\n     * WHY this key is trusted, in prose — 'jwt claim `sub`, stamped by AuthFilter', or\n     * 'whatsapp webhook phone number -> user lookup'. Required on a trusted key, absent on an\n     * untrusted one. It exists so that grepping the trusted keys also tells you what proves each\n     * one, without opening another file.\n     */\n    readonly provenance?: string;\n\n    /** Mask this value (partially) in logs. Log redaction only — unrelated to {@link trust}. */\n    readonly maskInLogs: boolean;\n\n    /** Whether this key is logged at all. Default true; false = never logged. */\n    readonly isLogged: boolean;\n\n    /**\n     * PRIVATE — use {@link trusted} or {@link untrusted}. There is deliberately no way to build a key\n     * without stating its trust level: a defaulted trust argument would make the permissive branch\n     * the shortest thing to type and impossible to grep.\n     */\n    private constructor(\n        name: string,\n        trust: Trust,\n        provenance: string | undefined,\n        httpHeader: string | undefined,\n        maskInLogs: boolean,\n        isLogged: boolean,\n        responseHeader: string | undefined,\n        responseMerge: ResponseMerge,\n    ) {\n        this.name = name;\n        this.trust = trust;\n        this.provenance = provenance;\n        this.httpHeader = httpHeader;\n        this.maskInLogs = maskInLogs;\n        this.isLogged = isLogged;\n        this.responseHeader = responseHeader;\n        this.responseMerge = responseMerge;\n    }\n\n    /**\n     * A key whose value the framework PROVED — a verified JWT claim, or a fact an app derived from a\n     * verified credential (a Twilio/WhatsApp webhook's signed phone number looked up to a userId).\n     *\n     * Only `RequestContext.putTrusted` can write one, only `RequestContext.getTrusted` can read one,\n     * and an inbound wire value for one is held PENDING until `AuthFilter` knows who the caller is.\n     *\n     * @param provenance WHY it is trusted, in prose. Required — see {@link ContextKey.provenance}.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor; the trust branch must be part of the call, not a defaulted argument\n    static trusted<V>(\n        name: string,\n        provenance: string,\n        httpHeader?: string,\n        maskInLogs = false,\n        isLogged = true,\n        responseHeader?: string,\n        responseMerge: ResponseMerge = 'collect',\n    ): ContextKey<V, 'trusted'> {\n        return new ContextKey<V, 'trusted'>(\n            name,\n            'trusted',\n            provenance,\n            httpHeader,\n            maskInLogs,\n            isLogged,\n            responseHeader,\n            responseMerge,\n        );\n    }\n\n    /**\n     * A key whose value is merely ASSERTED by whoever sent it — a browser-minted actionId, a\n     * client-supplied recording flag, an in-process log tag. Perfectly fine to use; just never\n     * an input to an authorization decision.\n     *\n     * This is the DEFAULT choice in the sense that most keys are this — but it is never the default\n     * VALUE: you still type the word, so reading a key definition always tells you which it is.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor; see trusted()\n    static untrusted<V>(\n        name: string,\n        httpHeader?: string,\n        maskInLogs = false,\n        isLogged = true,\n        responseHeader?: string,\n        responseMerge: ResponseMerge = 'collect',\n    ): ContextKey<V, 'untrusted'> {\n        return new ContextKey<V, 'untrusted'>(\n            name,\n            'untrusted',\n            undefined,\n            httpHeader,\n            maskInLogs,\n            isLogged,\n            responseHeader,\n            responseMerge,\n        );\n    }\n\n    /** True when this key is transferred over HTTP (has an httpHeader). */\n    isTransferred(): boolean {\n        return this.httpHeader !== undefined;\n    }\n\n    /** True when this key rides back on the RESPONSE (has a responseHeader). */\n    isResponseTransferred(): boolean {\n        return this.responseHeader !== undefined;\n    }\n\n    /**\n     * The value to STORE for this key given what the context already holds and what one response\n     * just carried, per this key's {@link responseMerge}.\n     *\n     * It lives on the KEY rather than in the two client packages because the policy is a property of\n     * the declaration, and because node and browser must not be able to answer it differently.\n     *\n     * `collect` returns an ARRAY, which is why a collecting key's value type is `string[]`: a\n     * non-array `existing` (somebody put a scalar under a collecting key) is folded in as the first\n     * element rather than thrown away, so the fan-out answer is never silently truncated.\n     */\n    // webpieces-disable no-any-unknown -- the context store is honestly type-erased; the key's own V types the public accessors\n    mergeResponseValue(existing: unknown, incoming: string): unknown {\n        switch (this.responseMerge) {\n            case 'first':\n                return existing === undefined ? incoming : existing;\n            case 'last':\n                return incoming;\n            case 'collect':\n                if (Array.isArray(existing)) {\n                    // webpieces-disable no-any-unknown -- a collect key's accumulated list is honestly type-erased here, exactly like every other key-agnostic serialization read\n                    return [...(existing as unknown[]), incoming];\n                }\n                return existing === undefined ? [incoming] : [existing, incoming];\n        }\n    }\n\n    /**\n     * True for a key built by {@link trusted}. Trust is BINARY, so this ONE predicate answers it in\n     * both directions and there is deliberately no `isUntrusted()` twin. The RUNTIME check used by the\n     * inbound fill and the AuthFilter reconciliation; ordinary application code should never need it,\n     * because the typed verbs already made the decision at compile time.\n     *\n     * It is a TYPE PREDICATE, so BOTH branches are typed, with NO cast on either side: the `if` holds a\n     * `ContextKey<V, 'trusted'>` for `putTrusted` / `PendingWireTrust.stash`, and the `else` holds a\n     * `ContextKey<V, 'untrusted'>` for `putUntrusted`. The `else` types only because\n     * {@link AnyContextKey} is a UNION of the two branches — see that alias for why the negative of a\n     * predicate needs something to drop. Before this, every such site wrote `key as\n     * AnyTrustedContextKey`; a cast is exactly the thing an agent copies to the one place it is not\n     * warranted, so the runtime check produces the type it proves instead.\n     *\n     * That is what makes a loop over a mixed `AnyContextKey[]` — the {@link HeaderRegistry} arrays, a\n     * browser-log payload re-stated into a detached scope — safe BY CONSTRUCTION: the loop can only\n     * write a key whose trust it has just tested, and a trusted key cannot reach `putUntrusted` at all,\n     * so a loop fed by a source that proves nothing cannot fabricate a proven value, and nobody has to\n     * remember to filter. That is a limit on the SOURCE, not on the key: a trusted key is written all\n     * the time via `putTrusted`, by an authenticator or by app code that proved the value out of band.\n     */\n    isTrusted(): this is ContextKey<V, 'trusted'> {\n        return this.trust === 'trusted';\n    }\n\n    /**\n     * The value as it should appear in a log line: returned as-is for a normal\n     * key, partially masked when this key sets `maskInLogs`. Masking is length-based:\n     * - Length > 15: first 3 + \"...\" + last 3\n     * - Length 8-15: first 2 + \"...\"\n     * - Length < 8: \"<secure key too short to log>\"\n     */\n    maskForLogs(value: string): string {\n        if (!this.maskInLogs) {\n            return value;\n        }\n        const len = value.length;\n        if (len < 8) {\n            return '<secure key too short to log>';\n        } else if (len <= 15) {\n            return `${value.substring(0, 2)}...`;\n        } else {\n            return `${value.substring(0, 3)}...${value.substring(len - 3)}`;\n        }\n    }\n}\n"]}

package/src/http/ContextMgr.d.ts

@@ -1,4 +1,4 @@
-import { ContextReader } from './ContextReader';
+import { ContextStore } from './ContextWriter';
 import { DestinationTrust } from './DestinationTrust';
 /**
  * ContextMgr - propagates the magic context onto outbound BROWSER requests.
@@ -24,11 +24,11 @@ import { DestinationTrust } from './DestinationTrust';
  * ```
  */
 export declare class ContextMgr {
-    /** The app-held store that provides context-key values. */
-    readonly contextReader: ContextReader;
+    /** The app-held store context-key values are read from AND written back into. */
+    readonly contextStore: ContextStore;
     constructor(
-    /** The app-held store that provides context-key values. */
-    contextReader: ContextReader);
+    /** The app-held store context-key values are read from AND written back into. */
+    contextStore: ContextStore);
     /**
      * Build the headers to send on an outbound request: every transferred key (httpHeader set)
      * with a non-empty value THAT THIS DESTINATION MAY RECEIVE, emitted under its `httpHeader`
@@ -46,11 +46,28 @@ export declare class ContextMgr {
      * The rule is applied here anyway rather than argued away, because the OTHER guarantee people
      * reach for — "`MutableContextStore.set` only accepts an untrusted key, so a browser store
      * cannot HOLD a trusted value" — is true of that store and NOT of the seam: {@link ContextMgr}
-     * takes any app-supplied {@link ContextReader}, whose `read` is handed an `AnyContextKey`. One
+     * takes any app-supplied {@link ContextStore}, whose `read` is handed an `AnyContextKey`. One
      * enforced rule in both builders beats a browser-only exemption resting on an implementation
      * detail of one implementation.
      *
      * Values are RAW (unmasked) — this map goes on the wire, not in logs.
      */
     buildOutboundHeaders(destination: DestinationTrust): Map<string, string>;
+    /**
+     * RESPONSE -> the store: every key that declares a `responseHeader` and appears on a response
+     * this browser just received, merged into the app-held store per the key's own
+     * {@link ContextKey.responseMerge}.
+     *
+     * The browser twin of `RequestContextHeaders.acceptResponseHeaders`, and the reason a value set
+     * by a server reaches the page without the page naming a header.
+     *
+     * TRUSTED keys are DROPPED here, unconditionally and without consulting `destination`, and the
+     * `if` is what makes that a compile-time fact rather than a convention: {@link ContextWriter.set}
+     * takes an {@link AnyUntrustedContextKey}, so a browser store CANNOT hold a proven value. That is
+     * the same rule as the outbound direction reaches by a different route — every browser
+     * destination is `@WpAuthJwt` or `@WpAuthPublic`, so `destination.allows` would refuse them
+     * anyway — and `destination` is still threaded and still applied, so a future browser destination
+     * that DID authenticate its caller does not silently start believing response headers.
+     */
+    acceptResponseHeaders(headers: Headers, destination: DestinationTrust): void;
 }

package/src/http/ContextMgr.js

@@ -28,11 +28,11 @@ const WebpiecesCoreHeaders_1 = require("./WebpiecesCoreHeaders");
  * ```
  */
 class ContextMgr {
-    contextReader;
+    contextStore;
     constructor(
-    /** The app-held store that provides context-key values. */
-    contextReader) {
-        this.contextReader = contextReader;
+    /** The app-held store context-key values are read from AND written back into. */
+    contextStore) {
+        this.contextStore = contextStore;
     }
     /**
      * Build the headers to send on an outbound request: every transferred key (httpHeader set)
@@ -51,7 +51,7 @@ class ContextMgr {
      * The rule is applied here anyway rather than argued away, because the OTHER guarantee people
      * reach for — "`MutableContextStore.set` only accepts an untrusted key, so a browser store
      * cannot HOLD a trusted value" — is true of that store and NOT of the seam: {@link ContextMgr}
-     * takes any app-supplied {@link ContextReader}, whose `read` is handed an `AnyContextKey`. One
+     * takes any app-supplied {@link ContextStore}, whose `read` is handed an `AnyContextKey`. One
      * enforced rule in both builders beats a browser-only exemption resting on an implementation
      * detail of one implementation.
      *
@@ -63,7 +63,7 @@ class ContextMgr {
             if (!destination.allows(key)) {
                 continue;
             }
-            const value = this.contextReader.read(key);
+            const value = this.contextStore.read(key);
             if (value !== undefined && value !== null && value !== '') {
                 outbound.set(key.httpHeader, value);
             }
@@ -81,6 +81,35 @@ class ContextMgr {
         }
         return outbound;
     }
+    /**
+     * RESPONSE -> the store: every key that declares a `responseHeader` and appears on a response
+     * this browser just received, merged into the app-held store per the key's own
+     * {@link ContextKey.responseMerge}.
+     *
+     * The browser twin of `RequestContextHeaders.acceptResponseHeaders`, and the reason a value set
+     * by a server reaches the page without the page naming a header.
+     *
+     * TRUSTED keys are DROPPED here, unconditionally and without consulting `destination`, and the
+     * `if` is what makes that a compile-time fact rather than a convention: {@link ContextWriter.set}
+     * takes an {@link AnyUntrustedContextKey}, so a browser store CANNOT hold a proven value. That is
+     * the same rule as the outbound direction reaches by a different route — every browser
+     * destination is `@WpAuthJwt` or `@WpAuthPublic`, so `destination.allows` would refuse them
+     * anyway — and `destination` is still threaded and still applied, so a future browser destination
+     * that DID authenticate its caller does not silently start believing response headers.
+     */
+    acceptResponseHeaders(headers, destination) {
+        for (const key of HeaderRegistry_1.HeaderRegistry.get().getResponseTxfrKeys()) {
+            const value = headers.get(key.responseHeader);
+            if (value === null || value === '') {
+                continue;
+            }
+            if (!destination.allows(key) || key.isTrusted()) {
+                // DROPPED: a browser proves nothing, so it may never hold a trusted value.
+                continue;
+            }
+            this.contextStore.set(key, key.mergeResponseValue(this.contextStore.readValue?.(key), value));
+        }
+    }
 }
 exports.ContextMgr = ContextMgr;
 //# sourceMappingURL=ContextMgr.js.map

package/src/http/ContextMgr.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextMgr.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextMgr.ts"],"names":[],"mappings":";;;AAGA,qDAAkD;AAClD,+CAA4C;AAC5C,iEAA8D;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,UAAU;IAGC;IAFpB;IACI,2DAA2D;IAC3C,aAA4B;QAA5B,kBAAa,GAAb,aAAa,CAAe;IAC7C,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,oBAAoB,CAAC,WAA6B;QAC9C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE3C,KAAK,MAAM,GAAG,IAAI,+BAAc,CAAC,GAAG,EAAE,CAAC,kBAAkB,EAAE,EAAE,CAAC;YAC1D,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,SAAS;YACb,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBACxD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,UAAW,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACL,CAAC;QAED,2FAA2F;QAC3F,+FAA+F;QAC/F,gGAAgG;QAChG,MAAM,SAAS,GAAG,yBAAW,CAAC,UAAU,EAAE,CAAC;QAC3C,MAAM,mBAAmB,GAAG,2CAAoB,CAAC,cAAc,CAAC,UAAW,CAAC;QAC5E,IAAI,SAAS,EAAE,CAAC;YACZ,QAAQ,CAAC,GAAG,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACJ,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;CACJ;AAvDD,gCAuDC","sourcesContent":["import { ContextKey } from '../ContextKey';\nimport { ContextReader } from './ContextReader';\nimport { DestinationTrust } from './DestinationTrust';\nimport { HeaderRegistry } from './HeaderRegistry';\nimport { ServiceInfo } from './ServiceInfo';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\n\n/**\n * ContextMgr - propagates the magic context onto outbound BROWSER requests.\n *\n * BROWSER-ONLY. Only @webpieces/http-client-browser may name this class. The server reads\n * `RequestContext` directly through `RequestContextHeaders` (in @webpieces/core-context) — a\n * `ContextReader` indirection buys a server nothing, because there is exactly one right answer there.\n *\n * Browsers have no AsyncLocalStorage, so the app holds a `MutableContextStore` and sets values as\n * they become known (login token, tenant). Every transferred key (httpHeader set) in the GLOBAL\n * {@link HeaderRegistry} is read from it and added to outbound requests. The registry is a process\n * global configured once at startup (like LogManager) and is browser-safe: it is the key SCHEMA,\n * not the value store.\n *\n * Example usage:\n * ```typescript\n * // startup, before bootstrap:\n * HeaderRegistry.configure(CompanyHeaders.ALL_HEADERS, true);\n *\n * const store = new MutableContextStore();\n * const factory = new ClientHttpBrowserFactory(store);\n * const client = factory.createRpcClient(SaveApi, new ClientConfig('http://api.example.com'));\n * ```\n */\nexport class ContextMgr {\n    constructor(\n        /** The app-held store that provides context-key values. */\n        public readonly contextReader: ContextReader,\n    ) {}\n\n    /**\n     * Build the headers to send on an outbound request: every transferred key (httpHeader set)\n     * with a non-empty value THAT THIS DESTINATION MAY RECEIVE, emitted under its `httpHeader`\n     * wire name.\n     *\n     * NO request-id chaining. A browser ORIGINATES a trace — it has no inbound request to point\n     * back at. If the app puts an `x-request-id` on the store it goes out as-is, and the server's\n     * inbound transfer adopts it as hop 1's own id. Chaining is a server concern; see\n     * RequestContextHeaders.\n     *\n     * `destination` gates TRUSTED keys exactly as it does on the server side (see\n     * {@link DestinationTrust}). In practice a browser never reaches the permissive branch — twice\n     * over: `BrowserProxyClient.assertEndpointSupported` refuses to bind an `@WpAuthOidc` /\n     * `@WpAuthSharedSecret` contract at all, so every browser destination is `@WpAuthJwt` or `@WpAuthPublic`.\n     * The rule is applied here anyway rather than argued away, because the OTHER guarantee people\n     * reach for — \"`MutableContextStore.set` only accepts an untrusted key, so a browser store\n     * cannot HOLD a trusted value\" — is true of that store and NOT of the seam: {@link ContextMgr}\n     * takes any app-supplied {@link ContextReader}, whose `read` is handed an `AnyContextKey`. One\n     * enforced rule in both builders beats a browser-only exemption resting on an implementation\n     * detail of one implementation.\n     *\n     * Values are RAW (unmasked) — this map goes on the wire, not in logs.\n     */\n    buildOutboundHeaders(destination: DestinationTrust): Map<string, string> {\n        const outbound = new Map<string, string>();\n\n        for (const key of HeaderRegistry.get().getTransferredKeys()) {\n            if (!destination.allows(key)) {\n                continue;\n            }\n            const value = this.contextReader.read(key);\n            if (value !== undefined && value !== null && value !== '') {\n                outbound.set(key.httpHeader!, value);\n            }\n        }\n\n        // CLIENT_VERSION: a browser ORIGINATES a call, so it sends its OWN app build version (from\n        // ServiceInfo) and the server logs which client build called it — same rule as the server-side\n        // RequestContextHeaders. Our version wins; absent if this app was never identified via setInfo.\n        const myVersion = ServiceInfo.getVersion();\n        const clientVersionHeader = WebpiecesCoreHeaders.CLIENT_VERSION.httpHeader!;\n        if (myVersion) {\n            outbound.set(clientVersionHeader, myVersion);\n        } else {\n            outbound.delete(clientVersionHeader);\n        }\n\n        return outbound;\n    }\n}\n"]}
+{"version":3,"file":"ContextMgr.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextMgr.ts"],"names":[],"mappings":";;;AAGA,qDAAkD;AAClD,+CAA4C;AAC5C,iEAA8D;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,UAAU;IAGC;IAFpB;IACI,iFAAiF;IACjE,YAA0B;QAA1B,iBAAY,GAAZ,YAAY,CAAc;IAC3C,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,oBAAoB,CAAC,WAA6B;QAC9C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE3C,KAAK,MAAM,GAAG,IAAI,+BAAc,CAAC,GAAG,EAAE,CAAC,kBAAkB,EAAE,EAAE,CAAC;YAC1D,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,SAAS;YACb,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBACxD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,UAAW,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACL,CAAC;QAED,2FAA2F;QAC3F,+FAA+F;QAC/F,gGAAgG;QAChG,MAAM,SAAS,GAAG,yBAAW,CAAC,UAAU,EAAE,CAAC;QAC3C,MAAM,mBAAmB,GAAG,2CAAoB,CAAC,cAAc,CAAC,UAAW,CAAC;QAC5E,IAAI,SAAS,EAAE,CAAC;YACZ,QAAQ,CAAC,GAAG,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACJ,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,OAAgB,EAAE,WAA6B;QACjE,KAAK,MAAM,GAAG,IAAI,+BAAc,CAAC,GAAG,EAAE,CAAC,mBAAmB,EAAE,EAAE,CAAC;YAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,cAAe,CAAC,CAAC;YAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBACjC,SAAS;YACb,CAAC;YACD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;gBAC9C,2EAA2E;gBAC3E,SAAS;YACb,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,kBAAkB,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QAClG,CAAC;IACL,CAAC;CACJ;AArFD,gCAqFC","sourcesContent":["import { ContextKey } from '../ContextKey';\nimport { ContextStore } from './ContextWriter';\nimport { DestinationTrust } from './DestinationTrust';\nimport { HeaderRegistry } from './HeaderRegistry';\nimport { ServiceInfo } from './ServiceInfo';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\n\n/**\n * ContextMgr - propagates the magic context onto outbound BROWSER requests.\n *\n * BROWSER-ONLY. Only @webpieces/http-client-browser may name this class. The server reads\n * `RequestContext` directly through `RequestContextHeaders` (in @webpieces/core-context) — a\n * `ContextReader` indirection buys a server nothing, because there is exactly one right answer there.\n *\n * Browsers have no AsyncLocalStorage, so the app holds a `MutableContextStore` and sets values as\n * they become known (login token, tenant). Every transferred key (httpHeader set) in the GLOBAL\n * {@link HeaderRegistry} is read from it and added to outbound requests. The registry is a process\n * global configured once at startup (like LogManager) and is browser-safe: it is the key SCHEMA,\n * not the value store.\n *\n * Example usage:\n * ```typescript\n * // startup, before bootstrap:\n * HeaderRegistry.configure(CompanyHeaders.ALL_HEADERS, true);\n *\n * const store = new MutableContextStore();\n * const factory = new ClientHttpBrowserFactory(store);\n * const client = factory.createRpcClient(SaveApi, new ClientConfig('http://api.example.com'));\n * ```\n */\nexport class ContextMgr {\n    constructor(\n        /** The app-held store context-key values are read from AND written back into. */\n        public readonly contextStore: ContextStore,\n    ) {}\n\n    /**\n     * Build the headers to send on an outbound request: every transferred key (httpHeader set)\n     * with a non-empty value THAT THIS DESTINATION MAY RECEIVE, emitted under its `httpHeader`\n     * wire name.\n     *\n     * NO request-id chaining. A browser ORIGINATES a trace — it has no inbound request to point\n     * back at. If the app puts an `x-request-id` on the store it goes out as-is, and the server's\n     * inbound transfer adopts it as hop 1's own id. Chaining is a server concern; see\n     * RequestContextHeaders.\n     *\n     * `destination` gates TRUSTED keys exactly as it does on the server side (see\n     * {@link DestinationTrust}). In practice a browser never reaches the permissive branch — twice\n     * over: `BrowserProxyClient.assertEndpointSupported` refuses to bind an `@WpAuthOidc` /\n     * `@WpAuthSharedSecret` contract at all, so every browser destination is `@WpAuthJwt` or `@WpAuthPublic`.\n     * The rule is applied here anyway rather than argued away, because the OTHER guarantee people\n     * reach for — \"`MutableContextStore.set` only accepts an untrusted key, so a browser store\n     * cannot HOLD a trusted value\" — is true of that store and NOT of the seam: {@link ContextMgr}\n     * takes any app-supplied {@link ContextStore}, whose `read` is handed an `AnyContextKey`. One\n     * enforced rule in both builders beats a browser-only exemption resting on an implementation\n     * detail of one implementation.\n     *\n     * Values are RAW (unmasked) — this map goes on the wire, not in logs.\n     */\n    buildOutboundHeaders(destination: DestinationTrust): Map<string, string> {\n        const outbound = new Map<string, string>();\n\n        for (const key of HeaderRegistry.get().getTransferredKeys()) {\n            if (!destination.allows(key)) {\n                continue;\n            }\n            const value = this.contextStore.read(key);\n            if (value !== undefined && value !== null && value !== '') {\n                outbound.set(key.httpHeader!, value);\n            }\n        }\n\n        // CLIENT_VERSION: a browser ORIGINATES a call, so it sends its OWN app build version (from\n        // ServiceInfo) and the server logs which client build called it — same rule as the server-side\n        // RequestContextHeaders. Our version wins; absent if this app was never identified via setInfo.\n        const myVersion = ServiceInfo.getVersion();\n        const clientVersionHeader = WebpiecesCoreHeaders.CLIENT_VERSION.httpHeader!;\n        if (myVersion) {\n            outbound.set(clientVersionHeader, myVersion);\n        } else {\n            outbound.delete(clientVersionHeader);\n        }\n\n        return outbound;\n    }\n\n    /**\n     * RESPONSE -> the store: every key that declares a `responseHeader` and appears on a response\n     * this browser just received, merged into the app-held store per the key's own\n     * {@link ContextKey.responseMerge}.\n     *\n     * The browser twin of `RequestContextHeaders.acceptResponseHeaders`, and the reason a value set\n     * by a server reaches the page without the page naming a header.\n     *\n     * TRUSTED keys are DROPPED here, unconditionally and without consulting `destination`, and the\n     * `if` is what makes that a compile-time fact rather than a convention: {@link ContextWriter.set}\n     * takes an {@link AnyUntrustedContextKey}, so a browser store CANNOT hold a proven value. That is\n     * the same rule as the outbound direction reaches by a different route — every browser\n     * destination is `@WpAuthJwt` or `@WpAuthPublic`, so `destination.allows` would refuse them\n     * anyway — and `destination` is still threaded and still applied, so a future browser destination\n     * that DID authenticate its caller does not silently start believing response headers.\n     */\n    acceptResponseHeaders(headers: Headers, destination: DestinationTrust): void {\n        for (const key of HeaderRegistry.get().getResponseTxfrKeys()) {\n            const value = headers.get(key.responseHeader!);\n            if (value === null || value === '') {\n                continue;\n            }\n            if (!destination.allows(key) || key.isTrusted()) {\n                // DROPPED: a browser proves nothing, so it may never hold a trusted value.\n                continue;\n            }\n            this.contextStore.set(key, key.mergeResponseValue(this.contextStore.readValue?.(key), value));\n        }\n    }\n}\n"]}

package/src/http/ContextWriter.d.ts

@@ -0,0 +1,29 @@
+import { AnyUntrustedContextKey } from '../ContextKey';
+import { ContextReader } from './ContextReader';
+/**
+ * ContextWriter - writes context-key values INTO an app-held store.
+ *
+ * BROWSER-ONLY, and the exact mirror of {@link ContextReader}. It exists because the context is no
+ * longer a one-way street: a webpieces client reads a callee's RESPONSE headers back into the
+ * caller's context (see `ContextMgr.acceptResponseHeaders`), and in a browser "the caller's context"
+ * IS the app-held store. A reader-only seam could propagate a value DOWN and never back UP.
+ *
+ * UNTRUSTED keys only, by type — the same rule {@link MutableContextStore.set} already enforced, now
+ * stated at the seam rather than at one implementation of it. A browser cannot PROVE anything, so a
+ * store that accepted a trusted key would be a forgery side door.
+ *
+ * `value` is `unknown` rather than `string` because a `collect` key holds a LIST (see
+ * {@link ContextKey.mergeResponseValue}); {@link ContextReader.read} keeps its string return and
+ * simply does not see those, which is correct — a list has no single outbound header value.
+ *
+ * This is a business-logic interface (per CLAUDE.md: behavior = interface).
+ */
+export interface ContextWriter {
+    set(key: AnyUntrustedContextKey, value: unknown): void;
+}
+/**
+ * The app-held browser context store, read AND write — what {@link ContextMgr} needs, and what
+ * {@link MutableContextStore} is. Named as one type so a browser app implements one thing rather
+ * than correlating two.
+ */
+export type ContextStore = ContextReader & ContextWriter;

package/src/http/ContextWriter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ContextWriter.js.map

package/src/http/ContextWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextWriter.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextWriter.ts"],"names":[],"mappings":"","sourcesContent":["import { AnyUntrustedContextKey, ContextKey } from '../ContextKey';\nimport { ContextReader } from './ContextReader';\n\n/**\n * ContextWriter - writes context-key values INTO an app-held store.\n *\n * BROWSER-ONLY, and the exact mirror of {@link ContextReader}. It exists because the context is no\n * longer a one-way street: a webpieces client reads a callee's RESPONSE headers back into the\n * caller's context (see `ContextMgr.acceptResponseHeaders`), and in a browser \"the caller's context\"\n * IS the app-held store. A reader-only seam could propagate a value DOWN and never back UP.\n *\n * UNTRUSTED keys only, by type — the same rule {@link MutableContextStore.set} already enforced, now\n * stated at the seam rather than at one implementation of it. A browser cannot PROVE anything, so a\n * store that accepted a trusted key would be a forgery side door.\n *\n * `value` is `unknown` rather than `string` because a `collect` key holds a LIST (see\n * {@link ContextKey.mergeResponseValue}); {@link ContextReader.read} keeps its string return and\n * simply does not see those, which is correct — a list has no single outbound header value.\n *\n * This is a business-logic interface (per CLAUDE.md: behavior = interface).\n */\nexport interface ContextWriter {\n    // webpieces-disable no-any-unknown -- context values are heterogeneous: a scalar key holds a string, a `collect` key holds a list\n    set(key: AnyUntrustedContextKey, value: unknown): void;\n}\n\n/**\n * The app-held browser context store, read AND write — what {@link ContextMgr} needs, and what\n * {@link MutableContextStore} is. Named as one type so a browser app implements one thing rather\n * than correlating two.\n */\nexport type ContextStore = ContextReader & ContextWriter;\n"]}

package/src/http/DestinationTrust.d.ts

@@ -52,9 +52,22 @@ export declare class DestinationTrust {
      */
     static forAuthMode(mode: AuthMode | undefined): DestinationTrust;
     /**
-     * May this key go on the wire to this destination? Untrusted keys always may — nobody was ever
-     * going to make a security decision on them. A trusted key may only when the destination will
-     * authenticate US, because that is the only case its `AuthFilter` will admit it.
+     * May this key cross the boundary between us and this destination? Untrusted keys always may —
+     * nobody was ever going to make a security decision on them. A trusted key may only when we and
+     * the destination authenticate each other.
+     *
+     * ONE method answers BOTH directions, deliberately, because it is one question:
+     *
+     * - OUTBOUND (`buildOutboundHeaders`): may we SEND a trusted key there? Only when the destination
+     *   will authenticate US, because that is the only case its `AuthFilter` will admit it.
+     * - RESPONSE (`acceptResponseHeaders`): may we BELIEVE a trusted key that came BACK? Only from a
+     *   destination this client authenticated to — an `@WpAuthOidc` / `@WpAuthSharedSecret` peer is a
+     *   service in our own trust domain, while a `@WpAuthPublic` / `@WpAuthJwt` / partner endpoint is
+     *   somebody else's process whose response headers are an assertion, not a proof.
+     *
+     * A second, identically-bodied `believesResponsesFrom(key)` would be two spellings of one
+     * decision — the shim shape `.claude/rules/no-backwards-compat.md` rejects — so the direction
+     * lives in the CALLER's name and the rule lives here, once.
      */
     allows(key: AnyContextKey): boolean;
 }

package/src/http/DestinationTrust.js

@@ -85,9 +85,22 @@ class DestinationTrust {
         }
     }
     /**
-     * May this key go on the wire to this destination? Untrusted keys always may — nobody was ever
-     * going to make a security decision on them. A trusted key may only when the destination will
-     * authenticate US, because that is the only case its `AuthFilter` will admit it.
+     * May this key cross the boundary between us and this destination? Untrusted keys always may —
+     * nobody was ever going to make a security decision on them. A trusted key may only when we and
+     * the destination authenticate each other.
+     *
+     * ONE method answers BOTH directions, deliberately, because it is one question:
+     *
+     * - OUTBOUND (`buildOutboundHeaders`): may we SEND a trusted key there? Only when the destination
+     *   will authenticate US, because that is the only case its `AuthFilter` will admit it.
+     * - RESPONSE (`acceptResponseHeaders`): may we BELIEVE a trusted key that came BACK? Only from a
+     *   destination this client authenticated to — an `@WpAuthOidc` / `@WpAuthSharedSecret` peer is a
+     *   service in our own trust domain, while a `@WpAuthPublic` / `@WpAuthJwt` / partner endpoint is
+     *   somebody else's process whose response headers are an assertion, not a proof.
+     *
+     * A second, identically-bodied `believesResponsesFrom(key)` would be two spellings of one
+     * decision — the shim shape `.claude/rules/no-backwards-compat.md` rejects — so the direction
+     * lives in the CALLER's name and the rule lives here, once.
      */
     allows(key) {
         return this.verifiesCaller || !key.isTrusted();

package/src/http/DestinationTrust.js.map

@@ -1 +1 @@
-{"version":3,"file":"DestinationTrust.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/DestinationTrust.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,gBAAgB;IAeY;IAdrC;;;;OAIG;IACK,MAAM,CAAU,eAAe,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAErE;;;;OAIG;IACK,MAAM,CAAU,oBAAoB,GAAG,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAE3E,YAAqC,cAAuB;QAAvB,mBAAc,GAAd,cAAc,CAAS;IAAG,CAAC;IAEhE;;;;OAIG;IACH,qSAAqS;IACrS,MAAM,CAAC,WAAW,CAAC,IAA0B;QACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACjD,CAAC;QACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,MAAM,CAAC;YACZ,KAAK,eAAe;gBAChB,OAAO,gBAAgB,CAAC,eAAe,CAAC;YAC5C,KAAK,KAAK,CAAC;YACX,KAAK,QAAQ,CAAC;YACd,iFAAiF;YACjF,oFAAoF;YACpF,mFAAmF;YACnF,yFAAyF;YACzF,mDAAmD;YACnD,KAAK,SAAS,CAAC;YACf,uFAAuF;YACvF,uFAAuF;YACvF,uFAAuF;YACvF,4FAA4F;YAC5F,iCAAiC;YACjC,KAAK,QAAQ,CAAC;YACd,gFAAgF;YAChF,uFAAuF;YACvF,wFAAwF;YACxF,iFAAiF;YACjF,KAAK,YAAY;gBACb,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACrD,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,GAAkB;QACrB,OAAO,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;IACnD,CAAC;;AA7DL,4CA8DC","sourcesContent":["import { AnyContextKey } from '../ContextKey';\nimport { AuthMode } from './auth-mode';\n\n/**\n * DestinationTrust - the OUTBOUND half of the trust model: may a TRUSTED context key\n * ({@link ContextKey.trusted}) ride to the endpoint we are about to call?\n *\n * ## Why the client has to answer this at all\n *\n * The server already decided (see `PendingWireTrust`): an inbound `x-user-id` is admitted only on a\n * route that verified WHO called it — `@WpAuthOidc` / `@WpAuthSharedSecret`. On a `@WpAuthJwt` or `@WpAuthPublic`\n * route the same header must match what the authenticator independently derived, or the request is\n * REJECTED with a 401.\n *\n * That rule is correct, and it means a client that ships `x-user-id` to a `@WpAuthPublic` endpoint is\n * building a request the callee is obliged to reject. Before this class the outbound builders\n * forwarded EVERY transferred key with no idea what the destination was, so an internal service\n * calling another service's public or JWT endpoint 401'd itself. The fix belongs on the producing\n * side: don't send what cannot possibly be believed.\n *\n * ## Why it is a class with a private constructor and no boolean parameter\n *\n * `buildOutboundHeaders(sendTrusted = true)` would have been three characters of work and exactly the\n * \"widening that is an ABSENCE rather than a token\" `.claude/rules/no-backwards-compat.md` rejects — the\n * permissive answer would be\n * what you get by not typing anything. There is no way to build a DestinationTrust except from the\n * destination endpoint's own {@link AuthMode}, so the caller cannot assert a posture the route does\n * not actually have, and `grep -rn DestinationTrust.forAuthMode` lists every place the question is\n * asked. The two instances are PRIVATE for the same reason: exposing them would be a second spelling\n * that skips the derivation.\n *\n * Per CLAUDE.md: data-only structure, so a class rather than an interface or a bare boolean.\n */\nexport class DestinationTrust {\n    /**\n     * The destination authenticates its CALLER (@WpAuthOidc / @WpAuthSharedSecret), so it is entitled to\n     * believe context WE vouch for — this is the service-to-service identity propagation that trusted\n     * keys keep an `httpHeader` for.\n     */\n    private static readonly VERIFIES_CALLER = new DestinationTrust(true);\n\n    /**\n     * The destination cannot tell us from a browser with curl (@WpAuthJwt / @WpAuthPublic / @WpAuthWebhook /\n     * @WpAuthApiKey / @WpAuthLocalOnly / an endpoint with no declared mode), so trusted keys are omitted.\n     * Untrusted keys still travel.\n     */\n    private static readonly CANNOT_VERIFY_CALLER = new DestinationTrust(false);\n\n    private constructor(private readonly verifiesCaller: boolean) {}\n\n    /**\n     * The ONLY way to obtain one: state the destination endpoint's auth mode. `undefined` (an\n     * endpoint that declared no mode) is treated as un-verifying, i.e. the SAFE answer — an absent\n     * declaration must never be the widest one.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor, exactly as ContextKey.trusted/untrusted do: the destination's auth mode must be part of the CALL, and a DI-injected instance method would let a caller hold one without ever naming a route\n    static forAuthMode(mode: AuthMode | undefined): DestinationTrust {\n        if (mode === undefined) {\n            return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n        switch (mode.kind) {\n            case 'oidc':\n            case 'shared-secret':\n                return DestinationTrust.VERIFIES_CALLER;\n            case 'jwt':\n            case 'public':\n            // @WpAuthWebhook authenticates an OUTSIDE VENDOR, which is not the same thing as\n            // authenticating a peer in this repo. The vendor knows nothing of webpieces context\n            // headers and would never send one, so there is no identity to propagate in either\n            // direction — and a webpieces client cannot call such an endpoint anyway (it cannot mint\n            // the vendor's signature). Trusted keys stay home.\n            case 'webhook':\n            // @WpAuthApiKey authenticates a CUSTOMER, not a peer service. The holder of the key is\n            // another company's codebase, so nothing it forwards may be believed, and no webpieces\n            // client can call it anyway (the framework extracts no api-key header — the app's hook\n            // owns which headers carry the credential; the contract's `credentials` list only DESCRIBES\n            // them). Trusted keys stay home.\n            case 'apikey':\n            // @WpAuthLocalOnly authenticates NOBODY — it gates on the environment, not on a\n            // credential — so a browser with curl on the same laptop is indistinguishable from us.\n            // Same bucket as public/jwt. (This switch has NO `default` on purpose: adding a kind to\n            // AuthMode is a compile error here rather than a silent permissive fallthrough.)\n            case 'local-only':\n                return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n    }\n\n    /**\n     * May this key go on the wire to this destination? Untrusted keys always may — nobody was ever\n     * going to make a security decision on them. A trusted key may only when the destination will\n     * authenticate US, because that is the only case its `AuthFilter` will admit it.\n     */\n    allows(key: AnyContextKey): boolean {\n        return this.verifiesCaller || !key.isTrusted();\n    }\n}\n"]}
+{"version":3,"file":"DestinationTrust.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/DestinationTrust.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAa,gBAAgB;IAeY;IAdrC;;;;OAIG;IACK,MAAM,CAAU,eAAe,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAErE;;;;OAIG;IACK,MAAM,CAAU,oBAAoB,GAAG,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAE3E,YAAqC,cAAuB;QAAvB,mBAAc,GAAd,cAAc,CAAS;IAAG,CAAC;IAEhE;;;;OAIG;IACH,qSAAqS;IACrS,MAAM,CAAC,WAAW,CAAC,IAA0B;QACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACjD,CAAC;QACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,MAAM,CAAC;YACZ,KAAK,eAAe;gBAChB,OAAO,gBAAgB,CAAC,eAAe,CAAC;YAC5C,KAAK,KAAK,CAAC;YACX,KAAK,QAAQ,CAAC;YACd,iFAAiF;YACjF,oFAAoF;YACpF,mFAAmF;YACnF,yFAAyF;YACzF,mDAAmD;YACnD,KAAK,SAAS,CAAC;YACf,uFAAuF;YACvF,uFAAuF;YACvF,uFAAuF;YACvF,4FAA4F;YAC5F,iCAAiC;YACjC,KAAK,QAAQ,CAAC;YACd,gFAAgF;YAChF,uFAAuF;YACvF,wFAAwF;YACxF,iFAAiF;YACjF,KAAK,YAAY;gBACb,OAAO,gBAAgB,CAAC,oBAAoB,CAAC;QACrD,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,GAAkB;QACrB,OAAO,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;IACnD,CAAC;;AA1EL,4CA2EC","sourcesContent":["import { AnyContextKey } from '../ContextKey';\nimport { AuthMode } from './auth-mode';\n\n/**\n * DestinationTrust - the OUTBOUND half of the trust model: may a TRUSTED context key\n * ({@link ContextKey.trusted}) ride to the endpoint we are about to call?\n *\n * ## Why the client has to answer this at all\n *\n * The server already decided (see `PendingWireTrust`): an inbound `x-user-id` is admitted only on a\n * route that verified WHO called it — `@WpAuthOidc` / `@WpAuthSharedSecret`. On a `@WpAuthJwt` or `@WpAuthPublic`\n * route the same header must match what the authenticator independently derived, or the request is\n * REJECTED with a 401.\n *\n * That rule is correct, and it means a client that ships `x-user-id` to a `@WpAuthPublic` endpoint is\n * building a request the callee is obliged to reject. Before this class the outbound builders\n * forwarded EVERY transferred key with no idea what the destination was, so an internal service\n * calling another service's public or JWT endpoint 401'd itself. The fix belongs on the producing\n * side: don't send what cannot possibly be believed.\n *\n * ## Why it is a class with a private constructor and no boolean parameter\n *\n * `buildOutboundHeaders(sendTrusted = true)` would have been three characters of work and exactly the\n * \"widening that is an ABSENCE rather than a token\" `.claude/rules/no-backwards-compat.md` rejects — the\n * permissive answer would be\n * what you get by not typing anything. There is no way to build a DestinationTrust except from the\n * destination endpoint's own {@link AuthMode}, so the caller cannot assert a posture the route does\n * not actually have, and `grep -rn DestinationTrust.forAuthMode` lists every place the question is\n * asked. The two instances are PRIVATE for the same reason: exposing them would be a second spelling\n * that skips the derivation.\n *\n * Per CLAUDE.md: data-only structure, so a class rather than an interface or a bare boolean.\n */\nexport class DestinationTrust {\n    /**\n     * The destination authenticates its CALLER (@WpAuthOidc / @WpAuthSharedSecret), so it is entitled to\n     * believe context WE vouch for — this is the service-to-service identity propagation that trusted\n     * keys keep an `httpHeader` for.\n     */\n    private static readonly VERIFIES_CALLER = new DestinationTrust(true);\n\n    /**\n     * The destination cannot tell us from a browser with curl (@WpAuthJwt / @WpAuthPublic / @WpAuthWebhook /\n     * @WpAuthApiKey / @WpAuthLocalOnly / an endpoint with no declared mode), so trusted keys are omitted.\n     * Untrusted keys still travel.\n     */\n    private static readonly CANNOT_VERIFY_CALLER = new DestinationTrust(false);\n\n    private constructor(private readonly verifiesCaller: boolean) {}\n\n    /**\n     * The ONLY way to obtain one: state the destination endpoint's auth mode. `undefined` (an\n     * endpoint that declared no mode) is treated as un-verifying, i.e. the SAFE answer — an absent\n     * declaration must never be the widest one.\n     */\n    // webpieces-disable no-function-outside-class -- static factory replacing the (now private) constructor, exactly as ContextKey.trusted/untrusted do: the destination's auth mode must be part of the CALL, and a DI-injected instance method would let a caller hold one without ever naming a route\n    static forAuthMode(mode: AuthMode | undefined): DestinationTrust {\n        if (mode === undefined) {\n            return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n        switch (mode.kind) {\n            case 'oidc':\n            case 'shared-secret':\n                return DestinationTrust.VERIFIES_CALLER;\n            case 'jwt':\n            case 'public':\n            // @WpAuthWebhook authenticates an OUTSIDE VENDOR, which is not the same thing as\n            // authenticating a peer in this repo. The vendor knows nothing of webpieces context\n            // headers and would never send one, so there is no identity to propagate in either\n            // direction — and a webpieces client cannot call such an endpoint anyway (it cannot mint\n            // the vendor's signature). Trusted keys stay home.\n            case 'webhook':\n            // @WpAuthApiKey authenticates a CUSTOMER, not a peer service. The holder of the key is\n            // another company's codebase, so nothing it forwards may be believed, and no webpieces\n            // client can call it anyway (the framework extracts no api-key header — the app's hook\n            // owns which headers carry the credential; the contract's `credentials` list only DESCRIBES\n            // them). Trusted keys stay home.\n            case 'apikey':\n            // @WpAuthLocalOnly authenticates NOBODY — it gates on the environment, not on a\n            // credential — so a browser with curl on the same laptop is indistinguishable from us.\n            // Same bucket as public/jwt. (This switch has NO `default` on purpose: adding a kind to\n            // AuthMode is a compile error here rather than a silent permissive fallthrough.)\n            case 'local-only':\n                return DestinationTrust.CANNOT_VERIFY_CALLER;\n        }\n    }\n\n    /**\n     * May this key cross the boundary between us and this destination? Untrusted keys always may —\n     * nobody was ever going to make a security decision on them. A trusted key may only when we and\n     * the destination authenticate each other.\n     *\n     * ONE method answers BOTH directions, deliberately, because it is one question:\n     *\n     * - OUTBOUND (`buildOutboundHeaders`): may we SEND a trusted key there? Only when the destination\n     *   will authenticate US, because that is the only case its `AuthFilter` will admit it.\n     * - RESPONSE (`acceptResponseHeaders`): may we BELIEVE a trusted key that came BACK? Only from a\n     *   destination this client authenticated to — an `@WpAuthOidc` / `@WpAuthSharedSecret` peer is a\n     *   service in our own trust domain, while a `@WpAuthPublic` / `@WpAuthJwt` / partner endpoint is\n     *   somebody else's process whose response headers are an assertion, not a proof.\n     *\n     * A second, identically-bodied `believesResponsesFrom(key)` would be two spellings of one\n     * decision — the shim shape `.claude/rules/no-backwards-compat.md` rejects — so the direction\n     * lives in the CALLER's name and the rule lives here, once.\n     */\n    allows(key: AnyContextKey): boolean {\n        return this.verifiesCaller || !key.isTrusted();\n    }\n}\n"]}

package/src/http/HeaderRegistry.d.ts

@@ -19,8 +19,9 @@ import { AnyContextKey } from '../ContextKey';
  *
  * Duplicate validation (port of Java checkForDuplicates) runs at configure() time,
  * so conflicting definitions fail fast at startup:
- * - Two keys with the same `name` must agree on httpHeader/trust/maskInLogs/isLogged.
+ * - Two keys with the same `name` must agree on httpHeader/responseHeader/trust/maskInLogs/isLogged.
  * - Two keys with the same `httpHeader` must agree on `name`.
+ * - Two keys with the same `responseHeader` must agree on `name`.
  * - Exact duplicates collapse to one entry.
  */
 export declare class HeaderRegistry {
@@ -29,9 +30,11 @@ export declare class HeaderRegistry {
     private static instance;
     private readonly keys;
     private readonly transferredKeys;
+    private readonly responseTxfrKeys;
     private readonly securedNames;
     private readonly loggedKeys;
     private readonly byHttpHeader;
+    private readonly byResponseHeader;
     private constructor();
     /**
      * Install the process-wide registry. Call once at startup, BEFORE
@@ -49,6 +52,16 @@ export declare class HeaderRegistry {
      * outbound request): those with an httpHeader set.
      */
     getTransferredKeys(): AnyContextKey[];
+    /**
+     * Keys that ride back on the RESPONSE (context -> outbound response on a server, response ->
+     * caller's context in a client): those with a `responseHeader` set. The exact mirror of
+     * {@link getTransferredKeys}, precomputed in the constructor for the same reason — the server
+     * writes them on EVERY response, so this is a hot path.
+     *
+     * This list is the whole reason there is no hard-coded response header anywhere in webpieces:
+     * a key joins it by DECLARING a `responseHeader`, with no framework edit.
+     */
+    getResponseTxfrKeys(): AnyContextKey[];
     /** Names (log keys) whose values must be masked in logs. maskInLogs=true. */
     getMaskedNames(): string[];
     /**
@@ -72,12 +85,18 @@ export declare class HeaderRegistry {
     /** Look up a key by its HTTP header name (case-insensitive). O(1) via the precomputed map. */
     findByHttpHeader(httpHeader: string): AnyContextKey | undefined;
     /**
-     * Collapse exact duplicates, throw on conflicting definitions sharing a `name`
-     * or an `httpHeader`.
+     * Look up a key by its RESPONSE header name (case-insensitive). O(1) via the precomputed map.
+     * This is what a client calls for each header of a response it just received, to decide whether
+     * that header carries a context value at all.
+     */
+    findByResponseHeader(responseHeader: string): AnyContextKey | undefined;
+    /**
+     * Collapse exact duplicates, throw on conflicting definitions sharing a `name`,
+     * an `httpHeader` or a `responseHeader`.
      */
     private checkForDuplicates;
     /**
-     * Two keys sharing a `name` must agree on httpHeader/trust/maskInLogs/isLogged,
+     * Two keys sharing a `name` must agree on httpHeader/responseHeader/responseMerge/trust/maskInLogs/isLogged,
      * otherwise the platform would behave differently depending on which module's
      * definition happened to load first.
      */

package/src/http/HeaderRegistry.js

@@ -22,8 +22,9 @@ const WebpiecesCoreHeaders_1 = require("./WebpiecesCoreHeaders");
  *
  * Duplicate validation (port of Java checkForDuplicates) runs at configure() time,
  * so conflicting definitions fail fast at startup:
- * - Two keys with the same `name` must agree on httpHeader/trust/maskInLogs/isLogged.
+ * - Two keys with the same `name` must agree on httpHeader/responseHeader/trust/maskInLogs/isLogged.
  * - Two keys with the same `httpHeader` must agree on `name`.
+ * - Two keys with the same `responseHeader` must agree on `name`.
  * - Exact duplicates collapse to one entry.
  */
 class HeaderRegistry {
@@ -37,9 +38,11 @@ class HeaderRegistry {
     // instead of re-filtering the full key list on each call. These are reachable
     // only through HeaderRegistry.get(), which throws until configure() has run.
     transferredKeys;
+    responseTxfrKeys;
     securedNames;
     loggedKeys;
     byHttpHeader;
+    byResponseHeader;
     constructor(keys) {
         this.keys = this.checkForDuplicates(keys);
         this.transferredKeys = this.keys.filter((k) => k.httpHeader !== undefined);
@@ -48,6 +51,11 @@ class HeaderRegistry {
             .map((k) => k.name);
         this.loggedKeys = this.keys.filter((k) => k.isLogged);
         this.byHttpHeader = new Map(this.transferredKeys.map((k) => [k.httpHeader.toLowerCase(), k]));
+        this.responseTxfrKeys = this.keys.filter((k) => k.responseHeader !== undefined);
+        this.byResponseHeader = new Map(this.responseTxfrKeys.map((k) => [
+            k.responseHeader.toLowerCase(),
+            k,
+        ]));
     }
     /**
      * Install the process-wide registry. Call once at startup, BEFORE
@@ -84,6 +92,18 @@ class HeaderRegistry {
     getTransferredKeys() {
         return this.transferredKeys;
     }
+    /**
+     * Keys that ride back on the RESPONSE (context -> outbound response on a server, response ->
+     * caller's context in a client): those with a `responseHeader` set. The exact mirror of
+     * {@link getTransferredKeys}, precomputed in the constructor for the same reason — the server
+     * writes them on EVERY response, so this is a hot path.
+     *
+     * This list is the whole reason there is no hard-coded response header anywhere in webpieces:
+     * a key joins it by DECLARING a `responseHeader`, with no framework edit.
+     */
+    getResponseTxfrKeys() {
+        return this.responseTxfrKeys;
+    }
     /** Names (log keys) whose values must be masked in logs. maskInLogs=true. */
     getMaskedNames() {
         return this.securedNames;
@@ -116,12 +136,21 @@ class HeaderRegistry {
         return this.byHttpHeader.get(httpHeader.toLowerCase());
     }
     /**
-     * Collapse exact duplicates, throw on conflicting definitions sharing a `name`
-     * or an `httpHeader`.
+     * Look up a key by its RESPONSE header name (case-insensitive). O(1) via the precomputed map.
+     * This is what a client calls for each header of a response it just received, to decide whether
+     * that header carries a context value at all.
+     */
+    findByResponseHeader(responseHeader) {
+        return this.byResponseHeader.get(responseHeader.toLowerCase());
+    }
+    /**
+     * Collapse exact duplicates, throw on conflicting definitions sharing a `name`,
+     * an `httpHeader` or a `responseHeader`.
      */
     checkForDuplicates(allKeys) {
         const byName = new Map();
         const byHttpHeader = new Map();
+        const byResponseHeader = new Map();
         for (const key of allKeys) {
             const nameKey = key.name.toLowerCase();
             const existing = byName.get(nameKey);
@@ -140,11 +169,21 @@ class HeaderRegistry {
                 }
                 byHttpHeader.set(headerKey, key);
             }
+            if (key.responseHeader !== undefined) {
+                const responseKey = key.responseHeader.toLowerCase();
+                const clash = byResponseHeader.get(responseKey);
+                if (clash) {
+                    throw new Error(`Duplicate ContextKey responseHeader '${key.responseHeader}': ` +
+                        `defined by key '${clash.name}' AND key '${key.name}'. ` +
+                        `Each HTTP response header must map to exactly one context key.`);
+                }
+                byResponseHeader.set(responseKey, key);
+            }
         }
         return Array.from(byName.values());
     }
     /**
-     * Two keys sharing a `name` must agree on httpHeader/trust/maskInLogs/isLogged,
+     * Two keys sharing a `name` must agree on httpHeader/responseHeader/responseMerge/trust/maskInLogs/isLogged,
      * otherwise the platform would behave differently depending on which module's
      * definition happened to load first.
      */
@@ -153,6 +192,12 @@ class HeaderRegistry {
         if (existing.httpHeader !== duplicate.httpHeader) {
             conflicts.push(`httpHeader ('${existing.httpHeader}' vs '${duplicate.httpHeader}')`);
         }
+        if (existing.responseHeader !== duplicate.responseHeader) {
+            conflicts.push(`responseHeader ('${existing.responseHeader}' vs '${duplicate.responseHeader}')`);
+        }
+        if (existing.responseMerge !== duplicate.responseMerge) {
+            conflicts.push(`responseMerge ('${existing.responseMerge}' vs '${duplicate.responseMerge}')`);
+        }
         if (existing.trust !== duplicate.trust) {
             // The most dangerous disagreement of the three: one module says this key is a proven
             // fact and another says it is caller-asserted. Whichever loaded first would silently

package/src/http/HeaderRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"HeaderRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HeaderRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContextKey, AnyContextKey } from '../ContextKey';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\n\n/**\n * HeaderRegistry - the single, GLOBAL source of truth for every ContextKey the\n * platform knows about. Port of Java webpieces' HeaderTranslation.\n *\n * Configured exactly like {@link LogManager} — once, at process startup — and then\n * globally accessible. There is NO DI wiring: filters/clients call\n * `HeaderRegistry.get()` instead of injecting it.\n *\n * ```ts\n * // startup (server AND browser), BEFORE LogManager.setFactory(...):\n * HeaderRegistry.configure(CompanyHeaders.ALL_HEADERS, true);\n * ```\n *\n * - `svrHeaders`      the context keys this process registers — by convention the whole\n *                     company-wide set (all keys across all servers), e.g. CompanyHeaders.\n * - `platformHeaders` when true, also include {@link HeaderRegistry.DEFAULT_HEADERS}\n *                     (the webpieces common keys: request-id, correlation-id, ...).\n *\n * Duplicate validation (port of Java checkForDuplicates) runs at configure() time,\n * so conflicting definitions fail fast at startup:\n * - Two keys with the same `name` must agree on httpHeader/trust/maskInLogs/isLogged.\n * - Two keys with the same `httpHeader` must agree on `name`.\n * - Exact duplicates collapse to one entry.\n */\nexport class HeaderRegistry {\n    /** The webpieces-supplied common keys; included when platformHeaders=true. */\n    static readonly DEFAULT_HEADERS: AnyContextKey[] = WebpiecesCoreHeaders.ALL_HEADERS;\n\n    private static instance: HeaderRegistry | undefined;\n\n    private readonly keys: AnyContextKey[];\n\n    // Derived collections precomputed ONCE, here in the constructor (i.e. at\n    // configure() time). The hot path — every log line calls getLoggedKeys(), every\n    // outbound request calls getTransferredKeys() — then returns the cached array\n    // instead of re-filtering the full key list on each call. These are reachable\n    // only through HeaderRegistry.get(), which throws until configure() has run.\n    private readonly transferredKeys: AnyContextKey[];\n    private readonly securedNames: string[];\n    private readonly loggedKeys: AnyContextKey[];\n    private readonly byHttpHeader: Map<string, AnyContextKey>;\n\n    private constructor(keys: AnyContextKey[]) {\n        this.keys = this.checkForDuplicates(keys);\n        this.transferredKeys = this.keys.filter((k: AnyContextKey) => k.httpHeader !== undefined);\n        this.securedNames = this.keys\n            .filter((k: AnyContextKey) => k.maskInLogs)\n            .map((k: AnyContextKey) => k.name);\n        this.loggedKeys = this.keys.filter((k: AnyContextKey) => k.isLogged);\n        this.byHttpHeader = new Map(\n            this.transferredKeys.map((k: AnyContextKey): [string, AnyContextKey] => [k.httpHeader!.toLowerCase(), k]),\n        );\n    }\n\n    /**\n     * Install the process-wide registry. Call once at startup, BEFORE\n     * LogManager.setFactory(...) (logging masks/keys off this registry).\n     */\n    // webpieces-disable no-function-outside-class -- HeaderRegistry is a deliberately static global singleton (like LogManager); configured once at startup, never DI-injected\n    static configure(svrHeaders: AnyContextKey[], platformHeaders: boolean): void {\n        const all: AnyContextKey[] = [\n            ...(platformHeaders ? HeaderRegistry.DEFAULT_HEADERS : []),\n            ...svrHeaders,\n        ];\n        HeaderRegistry.instance = new HeaderRegistry(all);\n    }\n\n    /** The configured registry. Throws if configure() has not been called. */\n    static get(): HeaderRegistry {\n        if (!HeaderRegistry.instance) {\n            throw new Error(\n                'HeaderRegistry.configure(...) has not been called. Configure the registry ' +\n                'at startup (before LogManager.setFactory) so filters/logging know the context keys.',\n            );\n        }\n        return HeaderRegistry.instance;\n    }\n\n    /** True once configure() has run. Used by LogManager.setFactory to fail fast. */\n    static isConfigured(): boolean {\n        return HeaderRegistry.instance !== undefined;\n    }\n\n    /** All registered keys (deduplicated). */\n    getKeys(): AnyContextKey[] {\n        return this.keys;\n    }\n\n    /**\n     * Keys that transfer over the wire (inbound request -> context, and context ->\n     * outbound request): those with an httpHeader set.\n     */\n    getTransferredKeys(): AnyContextKey[] {\n        return this.transferredKeys;\n    }\n\n    /** Names (log keys) whose values must be masked in logs. maskInLogs=true. */\n    getMaskedNames(): string[] {\n        return this.securedNames;\n    }\n\n    /**\n     * Keys that appear in logs. isLogged=true. The node logging backends read THESE and build the log\n     * field map directly from the active context — see `RequestContext.buildLogFields()` /\n     * `buildStructuredLogFields()`. (The registry used to own those two builders behind a read\n     * callback, but only the server ever called them, so the seam was inlined away.)\n     */\n    getLoggedKeys(): AnyContextKey[] {\n        return this.loggedKeys;\n    }\n\n    /**\n     * Look up a key by its CONTEXT name — the guard behind `RequestContext.get/put(name: string)`.\n     * Those raw string accessors would otherwise be a side door around the typed trust verbs\n     * (`RequestContext.get('userId')` reads a trusted value without ever saying `getTrusted`, and\n     * `put('userId', ...)` forges one without saying `putTrusted`), so they reject any name that\n     * belongs to a registered key and point the caller at the verb to use instead.\n     *\n     * Linear over the key list, which is fine: this runs only on the raw string path, and the\n     * reserved framework keys that legitimately use it ('__webpieces_*__') are a handful.\n     */\n    findByName(name: string): AnyContextKey | undefined {\n        const lower = name.toLowerCase();\n        return this.keys.find((k: AnyContextKey) => k.name.toLowerCase() === lower);\n    }\n\n    /** Look up a key by its HTTP header name (case-insensitive). O(1) via the precomputed map. */\n    findByHttpHeader(httpHeader: string): AnyContextKey | undefined {\n        return this.byHttpHeader.get(httpHeader.toLowerCase());\n    }\n\n    /**\n     * Collapse exact duplicates, throw on conflicting definitions sharing a `name`\n     * or an `httpHeader`.\n     */\n    private checkForDuplicates(allKeys: AnyContextKey[]): AnyContextKey[] {\n        const byName = new Map<string, AnyContextKey>();\n        const byHttpHeader = new Map<string, AnyContextKey>();\n\n        for (const key of allKeys) {\n            const nameKey = key.name.toLowerCase();\n            const existing = byName.get(nameKey);\n            if (existing) {\n                this.assertSameDefinition(existing, key);\n                continue; // exact duplicate - collapse\n            }\n            byName.set(nameKey, key);\n\n            if (key.httpHeader !== undefined) {\n                const headerKey = key.httpHeader.toLowerCase();\n                const clash = byHttpHeader.get(headerKey);\n                if (clash) {\n                    throw new Error(\n                        `Duplicate ContextKey httpHeader '${key.httpHeader}': ` +\n                        `defined by key '${clash.name}' AND key '${key.name}'. ` +\n                        `Each HTTP header must map to exactly one context key.`,\n                    );\n                }\n                byHttpHeader.set(headerKey, key);\n            }\n        }\n\n        return Array.from(byName.values());\n    }\n\n    /**\n     * Two keys sharing a `name` must agree on httpHeader/trust/maskInLogs/isLogged,\n     * otherwise the platform would behave differently depending on which module's\n     * definition happened to load first.\n     */\n    private assertSameDefinition(existing: AnyContextKey, duplicate: AnyContextKey): void {\n        const conflicts: string[] = [];\n        if (existing.httpHeader !== duplicate.httpHeader) {\n            conflicts.push(`httpHeader ('${existing.httpHeader}' vs '${duplicate.httpHeader}')`);\n        }\n        if (existing.trust !== duplicate.trust) {\n            // The most dangerous disagreement of the three: one module says this key is a proven\n            // fact and another says it is caller-asserted. Whichever loaded first would silently\n            // decide whether every reader of that key is doing an authorization check on a\n            // spoofable value, so it fails the whole startup instead.\n            conflicts.push(`trust ('${existing.trust}' vs '${duplicate.trust}')`);\n        }\n        if (existing.maskInLogs !== duplicate.maskInLogs) {\n            conflicts.push(`maskInLogs (${existing.maskInLogs} vs ${duplicate.maskInLogs})`);\n        }\n        if (existing.isLogged !== duplicate.isLogged) {\n            conflicts.push(`isLogged (${existing.isLogged} vs ${duplicate.isLogged})`);\n        }\n        if (conflicts.length > 0) {\n            throw new Error(\n                `Conflicting ContextKey definitions for '${existing.name}': ` +\n                `two modules registered it with different ${conflicts.join(', ')}. ` +\n                `Keys sharing a name must agree on all flags.`,\n            );\n        }\n    }\n}\n"]}
+{"version":3,"file":"HeaderRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HeaderRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContextKey, AnyContextKey } from '../ContextKey';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\n\n/**\n * HeaderRegistry - the single, GLOBAL source of truth for every ContextKey the\n * platform knows about. Port of Java webpieces' HeaderTranslation.\n *\n * Configured exactly like {@link LogManager} — once, at process startup — and then\n * globally accessible. There is NO DI wiring: filters/clients call\n * `HeaderRegistry.get()` instead of injecting it.\n *\n * ```ts\n * // startup (server AND browser), BEFORE LogManager.setFactory(...):\n * HeaderRegistry.configure(CompanyHeaders.ALL_HEADERS, true);\n * ```\n *\n * - `svrHeaders`      the context keys this process registers — by convention the whole\n *                     company-wide set (all keys across all servers), e.g. CompanyHeaders.\n * - `platformHeaders` when true, also include {@link HeaderRegistry.DEFAULT_HEADERS}\n *                     (the webpieces common keys: request-id, correlation-id, ...).\n *\n * Duplicate validation (port of Java checkForDuplicates) runs at configure() time,\n * so conflicting definitions fail fast at startup:\n * - Two keys with the same `name` must agree on httpHeader/responseHeader/trust/maskInLogs/isLogged.\n * - Two keys with the same `httpHeader` must agree on `name`.\n * - Two keys with the same `responseHeader` must agree on `name`.\n * - Exact duplicates collapse to one entry.\n */\nexport class HeaderRegistry {\n    /** The webpieces-supplied common keys; included when platformHeaders=true. */\n    static readonly DEFAULT_HEADERS: AnyContextKey[] = WebpiecesCoreHeaders.ALL_HEADERS;\n\n    private static instance: HeaderRegistry | undefined;\n\n    private readonly keys: AnyContextKey[];\n\n    // Derived collections precomputed ONCE, here in the constructor (i.e. at\n    // configure() time). The hot path — every log line calls getLoggedKeys(), every\n    // outbound request calls getTransferredKeys() — then returns the cached array\n    // instead of re-filtering the full key list on each call. These are reachable\n    // only through HeaderRegistry.get(), which throws until configure() has run.\n    private readonly transferredKeys: AnyContextKey[];\n    private readonly responseTxfrKeys: AnyContextKey[];\n    private readonly securedNames: string[];\n    private readonly loggedKeys: AnyContextKey[];\n    private readonly byHttpHeader: Map<string, AnyContextKey>;\n    private readonly byResponseHeader: Map<string, AnyContextKey>;\n\n    private constructor(keys: AnyContextKey[]) {\n        this.keys = this.checkForDuplicates(keys);\n        this.transferredKeys = this.keys.filter((k: AnyContextKey) => k.httpHeader !== undefined);\n        this.securedNames = this.keys\n            .filter((k: AnyContextKey) => k.maskInLogs)\n            .map((k: AnyContextKey) => k.name);\n        this.loggedKeys = this.keys.filter((k: AnyContextKey) => k.isLogged);\n        this.byHttpHeader = new Map(\n            this.transferredKeys.map((k: AnyContextKey): [string, AnyContextKey] => [k.httpHeader!.toLowerCase(), k]),\n        );\n        this.responseTxfrKeys = this.keys.filter((k: AnyContextKey) => k.responseHeader !== undefined);\n        this.byResponseHeader = new Map(\n            this.responseTxfrKeys.map((k: AnyContextKey): [string, AnyContextKey] => [\n                k.responseHeader!.toLowerCase(),\n                k,\n            ]),\n        );\n    }\n\n    /**\n     * Install the process-wide registry. Call once at startup, BEFORE\n     * LogManager.setFactory(...) (logging masks/keys off this registry).\n     */\n    // webpieces-disable no-function-outside-class -- HeaderRegistry is a deliberately static global singleton (like LogManager); configured once at startup, never DI-injected\n    static configure(svrHeaders: AnyContextKey[], platformHeaders: boolean): void {\n        const all: AnyContextKey[] = [\n            ...(platformHeaders ? HeaderRegistry.DEFAULT_HEADERS : []),\n            ...svrHeaders,\n        ];\n        HeaderRegistry.instance = new HeaderRegistry(all);\n    }\n\n    /** The configured registry. Throws if configure() has not been called. */\n    static get(): HeaderRegistry {\n        if (!HeaderRegistry.instance) {\n            throw new Error(\n                'HeaderRegistry.configure(...) has not been called. Configure the registry ' +\n                'at startup (before LogManager.setFactory) so filters/logging know the context keys.',\n            );\n        }\n        return HeaderRegistry.instance;\n    }\n\n    /** True once configure() has run. Used by LogManager.setFactory to fail fast. */\n    static isConfigured(): boolean {\n        return HeaderRegistry.instance !== undefined;\n    }\n\n    /** All registered keys (deduplicated). */\n    getKeys(): AnyContextKey[] {\n        return this.keys;\n    }\n\n    /**\n     * Keys that transfer over the wire (inbound request -> context, and context ->\n     * outbound request): those with an httpHeader set.\n     */\n    getTransferredKeys(): AnyContextKey[] {\n        return this.transferredKeys;\n    }\n\n    /**\n     * Keys that ride back on the RESPONSE (context -> outbound response on a server, response ->\n     * caller's context in a client): those with a `responseHeader` set. The exact mirror of\n     * {@link getTransferredKeys}, precomputed in the constructor for the same reason — the server\n     * writes them on EVERY response, so this is a hot path.\n     *\n     * This list is the whole reason there is no hard-coded response header anywhere in webpieces:\n     * a key joins it by DECLARING a `responseHeader`, with no framework edit.\n     */\n    getResponseTxfrKeys(): AnyContextKey[] {\n        return this.responseTxfrKeys;\n    }\n\n    /** Names (log keys) whose values must be masked in logs. maskInLogs=true. */\n    getMaskedNames(): string[] {\n        return this.securedNames;\n    }\n\n    /**\n     * Keys that appear in logs. isLogged=true. The node logging backends read THESE and build the log\n     * field map directly from the active context — see `RequestContext.buildLogFields()` /\n     * `buildStructuredLogFields()`. (The registry used to own those two builders behind a read\n     * callback, but only the server ever called them, so the seam was inlined away.)\n     */\n    getLoggedKeys(): AnyContextKey[] {\n        return this.loggedKeys;\n    }\n\n    /**\n     * Look up a key by its CONTEXT name — the guard behind `RequestContext.get/put(name: string)`.\n     * Those raw string accessors would otherwise be a side door around the typed trust verbs\n     * (`RequestContext.get('userId')` reads a trusted value without ever saying `getTrusted`, and\n     * `put('userId', ...)` forges one without saying `putTrusted`), so they reject any name that\n     * belongs to a registered key and point the caller at the verb to use instead.\n     *\n     * Linear over the key list, which is fine: this runs only on the raw string path, and the\n     * reserved framework keys that legitimately use it ('__webpieces_*__') are a handful.\n     */\n    findByName(name: string): AnyContextKey | undefined {\n        const lower = name.toLowerCase();\n        return this.keys.find((k: AnyContextKey) => k.name.toLowerCase() === lower);\n    }\n\n    /** Look up a key by its HTTP header name (case-insensitive). O(1) via the precomputed map. */\n    findByHttpHeader(httpHeader: string): AnyContextKey | undefined {\n        return this.byHttpHeader.get(httpHeader.toLowerCase());\n    }\n\n    /**\n     * Look up a key by its RESPONSE header name (case-insensitive). O(1) via the precomputed map.\n     * This is what a client calls for each header of a response it just received, to decide whether\n     * that header carries a context value at all.\n     */\n    findByResponseHeader(responseHeader: string): AnyContextKey | undefined {\n        return this.byResponseHeader.get(responseHeader.toLowerCase());\n    }\n\n    /**\n     * Collapse exact duplicates, throw on conflicting definitions sharing a `name`,\n     * an `httpHeader` or a `responseHeader`.\n     */\n    private checkForDuplicates(allKeys: AnyContextKey[]): AnyContextKey[] {\n        const byName = new Map<string, AnyContextKey>();\n        const byHttpHeader = new Map<string, AnyContextKey>();\n        const byResponseHeader = new Map<string, AnyContextKey>();\n\n        for (const key of allKeys) {\n            const nameKey = key.name.toLowerCase();\n            const existing = byName.get(nameKey);\n            if (existing) {\n                this.assertSameDefinition(existing, key);\n                continue; // exact duplicate - collapse\n            }\n            byName.set(nameKey, key);\n\n            if (key.httpHeader !== undefined) {\n                const headerKey = key.httpHeader.toLowerCase();\n                const clash = byHttpHeader.get(headerKey);\n                if (clash) {\n                    throw new Error(\n                        `Duplicate ContextKey httpHeader '${key.httpHeader}': ` +\n                        `defined by key '${clash.name}' AND key '${key.name}'. ` +\n                        `Each HTTP header must map to exactly one context key.`,\n                    );\n                }\n                byHttpHeader.set(headerKey, key);\n            }\n\n            if (key.responseHeader !== undefined) {\n                const responseKey = key.responseHeader.toLowerCase();\n                const clash = byResponseHeader.get(responseKey);\n                if (clash) {\n                    throw new Error(\n                        `Duplicate ContextKey responseHeader '${key.responseHeader}': ` +\n                        `defined by key '${clash.name}' AND key '${key.name}'. ` +\n                        `Each HTTP response header must map to exactly one context key.`,\n                    );\n                }\n                byResponseHeader.set(responseKey, key);\n            }\n        }\n\n        return Array.from(byName.values());\n    }\n\n    /**\n     * Two keys sharing a `name` must agree on httpHeader/responseHeader/responseMerge/trust/maskInLogs/isLogged,\n     * otherwise the platform would behave differently depending on which module's\n     * definition happened to load first.\n     */\n    private assertSameDefinition(existing: AnyContextKey, duplicate: AnyContextKey): void {\n        const conflicts: string[] = [];\n        if (existing.httpHeader !== duplicate.httpHeader) {\n            conflicts.push(`httpHeader ('${existing.httpHeader}' vs '${duplicate.httpHeader}')`);\n        }\n        if (existing.responseHeader !== duplicate.responseHeader) {\n            conflicts.push(\n                `responseHeader ('${existing.responseHeader}' vs '${duplicate.responseHeader}')`,\n            );\n        }\n        if (existing.responseMerge !== duplicate.responseMerge) {\n            conflicts.push(\n                `responseMerge ('${existing.responseMerge}' vs '${duplicate.responseMerge}')`,\n            );\n        }\n        if (existing.trust !== duplicate.trust) {\n            // The most dangerous disagreement of the three: one module says this key is a proven\n            // fact and another says it is caller-asserted. Whichever loaded first would silently\n            // decide whether every reader of that key is doing an authorization check on a\n            // spoofable value, so it fails the whole startup instead.\n            conflicts.push(`trust ('${existing.trust}' vs '${duplicate.trust}')`);\n        }\n        if (existing.maskInLogs !== duplicate.maskInLogs) {\n            conflicts.push(`maskInLogs (${existing.maskInLogs} vs ${duplicate.maskInLogs})`);\n        }\n        if (existing.isLogged !== duplicate.isLogged) {\n            conflicts.push(`isLogged (${existing.isLogged} vs ${duplicate.isLogged})`);\n        }\n        if (conflicts.length > 0) {\n            throw new Error(\n                `Conflicting ContextKey definitions for '${existing.name}': ` +\n                `two modules registered it with different ${conflicts.join(', ')}. ` +\n                `Keys sharing a name must agree on all flags.`,\n            );\n        }\n    }\n}\n"]}

package/src/http/WebpiecesCoreHeaders.d.ts

@@ -21,6 +21,18 @@ export declare class WebpiecesCoreHeaders {
     /**
      * The id that correlates every hop of one request, and every log line of every hop.
      * Generated by the first service to see a request without one; propagated unchanged after that.
+     *
+     * - `httpHeader` `x-request-id` → travels DOWN the call tree on every outbound request.
+     * - `responseHeader` `x-request-id` → and back UP on every response, which is the header a
+     *   support desk quotes. This used to be a hard-coded `res.setHeader` in `ExpressWrapper`
+     *   (`stampTransactionId`), reachable by no other key. It is an ordinary registry entry now: the
+     *   server's ONE response choke point writes every key in
+     *   {@link HeaderRegistry.getResponseTxfrKeys}, so a second key joins with no framework edit.
+     * - `responseMerge` `first` → and NOT `collect`. A callee echoes OUR id back at us, so the
+     *   caller's context must KEEP what it already has. `collect` would turn `requestId` into a
+     *   growing array on every client call and break every log line of the request; `last` would
+     *   rewrite it with an echo. `first` makes reading it back a provable no-op for the normal case
+     *   and still adopts an id when a caller somehow had none.
      */
     static readonly REQUEST_ID: ContextKey<string, "untrusted">;
     /**

package/src/http/WebpiecesCoreHeaders.js

@@ -22,8 +22,24 @@ class WebpiecesCoreHeaders {
     /**
      * The id that correlates every hop of one request, and every log line of every hop.
      * Generated by the first service to see a request without one; propagated unchanged after that.
+     *
+     * - `httpHeader` `x-request-id` → travels DOWN the call tree on every outbound request.
+     * - `responseHeader` `x-request-id` → and back UP on every response, which is the header a
+     *   support desk quotes. This used to be a hard-coded `res.setHeader` in `ExpressWrapper`
+     *   (`stampTransactionId`), reachable by no other key. It is an ordinary registry entry now: the
+     *   server's ONE response choke point writes every key in
+     *   {@link HeaderRegistry.getResponseTxfrKeys}, so a second key joins with no framework edit.
+     * - `responseMerge` `first` → and NOT `collect`. A callee echoes OUR id back at us, so the
+     *   caller's context must KEEP what it already has. `collect` would turn `requestId` into a
+     *   growing array on every client call and break every log line of the request; `last` would
+     *   rewrite it with an echo. `first` makes reading it back a provable no-op for the normal case
+     *   and still adopts an id when a caller somehow had none.
      */
-    static REQUEST_ID = ContextKey_1.ContextKey.untrusted('requestId', 'x-request-id');
+    static REQUEST_ID = ContextKey_1.ContextKey.untrusted('requestId', 'x-request-id', 
+    /*maskInLogs*/ false, 
+    /*isLogged*/ true, 
+    /*responseHeader*/ 'x-request-id', 
+    /*responseMerge*/ 'first');
     /**
      * WHICH SERVICE MINTED {@link REQUEST_ID} — the name from {@link ServiceInfo}, stamped by
      * `RequestContextHeaders.fillFromRequest` ONLY on the branch that generates a new id (i.e. when

package/src/http/WebpiecesCoreHeaders.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesCoreHeaders.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesCoreHeaders.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContextKey, AnyContextKey } from '../ContextKey';\nimport { ApiCallInfo } from './ApiCallInfo';\nimport { Surface } from './Surface';\n\n/**\n * Core framework context keys — the minimum the WebPieces framework needs to correlate one\n * request across every service it touches, and across every log line each of them writes.\n *\n * ONE id, propagated unchanged. The first service to see a request without an `x-request-id`\n * generates one (RequestContextHeaders.fillFromRequest); every hop copies it onward verbatim. Grep that id and you\n * have the whole call tree. There is no per-hop id and no parent pointer: a chain of ids you must\n * stitch back together buys nothing a single shared id does not already give you.\n *\n * Lives in core-util (browser-safe) so both the http clients and http-server can reference it.\n *\n * Exposed as {@link HeaderRegistry.DEFAULT_HEADERS} — a service opts into these by\n * passing `platformHeaders=true` to `HeaderRegistry.configure(...)`.\n *\n * Each key's `name` is the logical/log name; `httpHeader` is the wire name.\n */\nexport class WebpiecesCoreHeaders {\n    /**\n     * The id that correlates every hop of one request, and every log line of every hop.\n     * Generated by the first service to see a request without one; propagated unchanged after that.\n     */\n    static readonly REQUEST_ID = ContextKey.untrusted<string>('requestId', 'x-request-id');\n\n    /**\n     * WHICH SERVICE MINTED {@link REQUEST_ID} — the name from {@link ServiceInfo}, stamped by\n     * `RequestContextHeaders.fillFromRequest` ONLY on the branch that generates a new id (i.e. when\n     * the inbound request carried no `x-request-id`). It answers the question the id alone cannot:\n     * \"this trace starts here — is that right?\" An id appearing with no source means it came from\n     * outside; an id sourced by a service that should never be an entry point is a routing bug.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is the WHOLE POINT. If it\n     *   travelled, hop 2 would inherit it, hop 3 would inherit it, and \"who started this trace\"\n     *   would be indistinguishable from \"who passed it along\" — the origin, the one fact this key\n     *   carries, would be lost. It is absent on every hop that did NOT mint the id, which is exactly\n     *   the signal: present == I am the origin.\n     * - `isLogged` TRUE → emitted as a plain string at `jsonPayload.requestIdSource`.\n     */\n    static readonly REQUEST_ID_SOURCE = ContextKey.untrusted<string>(\n        'requestIdSource',\n        /*httpHeader*/ undefined,\n    );\n\n    /**\n     * The CALLER's build version — so a downstream server's logs record which build of the client\n     * called it (surfaces as `jsonPayload.clientVersion`). Distinct from the log line's own `version`\n     * (this service's build): `version` answers \"which build wrote this line?\", `clientVersion`\n     * answers \"which build asked us to?\".\n     *\n     * - `httpHeader` SET → transferred over the wire, BUT unlike a normal transferred key it is NOT\n     *   copied from the context onward. Each hop OVERWRITES it with its OWN `ServiceInfo.getVersion()`\n     *   as it becomes the client to the next hop (see `buildOutboundHeaders`), so on any given server\n     *   `clientVersion` is always the IMMEDIATE caller's version, never a stale grand-caller's.\n     * - `isLogged` TRUE → the inbound value lands in the context and flows through the normal log\n     *   field map; no backend change needed.\n     */\n    static readonly CLIENT_VERSION = ContextKey.untrusted<string>(\n        'clientVersion',\n        'x-webpieces-client-version',\n    );\n\n    /**\n     * A frontend/app-minted correlation id that groups every request triggered by ONE user ACTION.\n     *\n     * An \"action\" is a single thing the user did in the GUI — a CLICK on a button/link, or TYPING in a\n     * field — or a background poller tick: anything that may fan out into MULTIPLE remote calls. That one\n     * action fires 1..N browser HTTP calls, each of which gets its own framework-minted {@link REQUEST_ID}\n     * (one per HTTP call, shared within that call's server→server subtree). `actionId` sits ABOVE\n     * `requestId` and is what stitches those N requests back to the single action that caused them:\n     *\n     *     actionId  (app-minted, ONE per user action, rides EVERY call of that action)\n     *        └── 1..N requestId  (framework-minted, ONE per HTTP call)\n     *\n     * Grep one `actionId` in the logs → every `requestId` it spawned, and every log line of the whole\n     * action. Minted and refreshed by the app (a UI concern), carried under `x-webpieces-actionid`.\n     *\n     * Browser/app-minted ONLY: unlike {@link REQUEST_ID}, the framework transfers and logs it but must\n     * NOT auto-mint one server-side. Absent `actionId` ⇒ a non-action flow (system / cron / task), which\n     * is the correct signal.\n     *\n     * - `httpHeader` SET → transferred: copied off the inbound request into context and re-emitted on\n     *   outbound hops, so the id follows the action across services.\n     * - `isLogged` TRUE → emitted as a plain string on every log line of the request.\n     */\n    static readonly ACTION_ID = ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid');\n\n    /**\n     * WHO the request is acting as, and WHAT they may do. All three are TRUSTED keys: they are the\n     * inputs to authorization decisions, so a reader must be able to tell \"the framework proved\n     * this\" from \"the caller typed this\" — see the trust section of the {@link ContextKey} doc.\n     *\n     * They keep their `httpHeader`, because propagating a verified identity to the next internal\n     * service is the point. What makes that safe is not the header being absent, it is WHO is\n     * allowed to have set it: an inbound value is held PENDING by\n     * `RequestContextHeaders.fillFromRequest` and admitted by `AuthFilter` only on a route that\n     * verified its CALLER (`@WpAuthOidc` / `@WpAuthSharedSecret`). On a browser-reachable route\n     * (`@WpAuthJwt` / public) the value must match what the authenticator itself derived, or the\n     * request is rejected.\n     *\n     * `provenance` says \"an app-bound JwtHook\" rather than naming one hook, because the framework\n     * default ({@link DefaultJwtHook}) stamps NO context entries at all — an app supplies a hook that\n     * returns {@link ContextTuple}s for the keys it can vouch for. Any of these three that an app's\n     * hook does NOT stamp will be rejected when a caller supplies it, which is the correct and loud\n     * outcome: nothing is vouching for it.\n     */\n    static readonly ORG_ID = ContextKey.trusted<string>(\n        'orgId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-org-id',\n    );\n\n    static readonly USER_ID = ContextKey.trusted<string>(\n        'userId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-user-id',\n    );\n\n    static readonly USER_ROLES = ContextKey.trusted<string>(\n        'roles',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-webpieces-roles',\n    );\n\n    /**\n     * WHICH KIND OF CALLER is driving this request — `gui`, `llm` or `public-api`. See\n     * {@link Surface} for the table and for why it is a property of the CALLER and not of the server.\n     *\n     * TRUSTED, and that is load-bearing twice over. It is what makes an app safe to branch on it in\n     * its OWN authorization logic (\"this endpoint is not exposed to partners\"), and it is what makes\n     * the value in {@link SurfaceEndUserStatus} believable: webpieces sets it itself, from the auth\n     * mode that matched, never from caller input. A caller that simply SENDS `x-wp-surface` at an\n     * endpoint whose auth did not establish one is rejected by `AuthFilter.reconcileWireTrust`, like\n     * every other unvouched trusted header.\n     *\n     * It keeps its `httpHeader` because PROPAGATION is the point: the surface belongs to the ORIGINAL\n     * caller, so `GUI -> api1 -> api2` must leave api2 seeing `gui`. An internal `@WpAuthOidc` hop\n     * verifies its caller, so the propagated value is admitted verbatim — and the auth filter only\n     * ever SETS a surface when none arrived, so an inherited one is never overwritten.\n     */\n    static readonly SURFACE = ContextKey.trusted<Surface>(\n        'surface',\n        'set by the webpieces AuthFilter from the auth mode that matched the incoming request, or inherited from the edge hop that did',\n        'x-wp-surface',\n    );\n\n    /**\n     * Turns on test-case recording for this request (Java: x-webpieces-recording).\n     * Transferred so recording follows the request across service hops.\n     */\n    static readonly RECORDING = ContextKey.untrusted<string>('recording', 'x-webpieces-recording');\n\n    /**\n     * The structured API-call tag ({@link ApiCallInfo}) stamped by {@link LogApiCallImpl} around every\n     * outbound (client) / inbound (server) call. It rides the magic context so EVERY log line emitted\n     * during the call inherits a filterable `api` object, surfacing in GCP as nested\n     * `jsonPayload.api.{side,type,result,path,method}`.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire. Per-hop only: each server/client hop\n     *   stamps its own tag, so a downstream server records `side:'server'`, never the caller's `side:'client'`.\n     * - `isLogged` TRUE → emitted by the logging backends. It carries an OBJECT value, so the backends\n     *   read it via {@link HeaderRegistry.buildStructuredLogFields} (object-aware); the flat\n     *   `buildLogFields()` string map deliberately skips it (typeof-string guard).\n     */\n    static readonly API_CALL_INFO = ContextKey.untrusted<ApiCallInfo>(\n        'api',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The inbound request's HTTP method and path, stamped ONCE from the {@link HttpRequest} by\n     * `RequestContextHeaders.fillFromRequest` (the atomic inbound choke point every transport funnels\n     * through). They surface as top-level `jsonPayload.httpMethod` / `jsonPayload.requestPath` so every\n     * log line of the request carries them — they used to ride inside {@link ApiCallInfo} (`api.path` /\n     * `api.method`) but that coupled a per-CALL logger to the per-REQUEST transport shape.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire: a downstream hop stamps its OWN inbound\n     *   method/path, never the caller's. Outbound client calls never set these (no inbound path).\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly HTTP_METHOD = ContextKey.untrusted<string>(\n        'httpMethod',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly REQUEST_PATH = ContextKey.untrusted<string>(\n        'requestPath',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The routed endpoint's IMPLEMENTATION identity: the concrete controller class name\n     * ({@link RouteMetadata.controllerClassName}, e.g. `LoginController`) and the handler method NAME\n     * ({@link RouteMetadata.methodName}, e.g. `login`), stamped once per request by {@link LogApiFilter}\n     * after route matching so every subsequent log line of the request carries them.\n     *\n     * These say WHICH CODE ran, which is what you actually grep for — far more useful than the raw\n     * `requestPath`. They are the top-level, filterable twin of what previously only lived nested in\n     * {@link ApiCallInfo} (`api.method.controllerName` / `api.method.methodName`). The local console\n     * formatters render them together as a compact `[Controller.method]` bracket; GCP keeps them as two\n     * separate `jsonPayload.controller` / `jsonPayload.method` fields.\n     *\n     * NOTE: `method` here is the CODE method name (e.g. `login`), NOT the HTTP verb — that is\n     * {@link HTTP_METHOD} (`httpMethod`).\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred: each hop stamps its OWN routed controller/method.\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly CONTROLLER = ContextKey.untrusted<string>(\n        'controller',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly METHOD = ContextKey.untrusted<string>(\n        'method',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The base URL ONE outbound call should go to, overriding whatever the client's `ClientConfig`\n     * bound at construction — the answer to \"POST our published contract to a URL the PARTNER\n     * registered at runtime\" (an `OrganizationWebhook.url` column, an OAuth callback, a per-tenant\n     * or self-hosted host). The destination is DATA, not deployment, so it cannot be a svcName and\n     * there is nothing to register in {@link ClientRegistry}.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * The contract's path IS appended to it (base + `@ApiPath` + `@Endpoint`). When the stored value\n     * is a complete url — the usual partner-webhook row — use {@link OVERRIDE_FULL_URL} instead.\n     *\n     * ONLY a client carrying a `ContextBaseUrlFilter` reads it. Every other client IGNORES this key\n     * entirely, which is what stops an ambient value re-pointing every other client in the same\n     * fan-out loop at a partner's server. Installing that ONE filter IS the opt-in, so\n     * `grep -rn ContextBaseUrlFilter` enumerates every client that can be re-pointed at all.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is load-bearing. This value\n     *   names where THIS hop goes. If it travelled, the callee would inherit it and re-point ITS\n     *   own outbound calls at the same host — one partner-supplied URL turning into an SSRF pivot\n     *   across the whole call tree. It is per-hop, always.\n     * - `isLogged` TRUE → the destination of a partner delivery is exactly what you want in the log\n     *   line when one fails.\n     *\n     * UNTRUSTED, necessarily: it comes from a database column a partner edited. That is precisely\n     * why re-pointing a request ARMS the framework's SSRF guard, automatically, rather than trusting\n     * it — the guard sits beneath every app filter and reads the fact that the request was moved.\n     */\n    static readonly OVERRIDE_BASE_URL = ContextKey.untrusted<string>(\n        'overrideBaseUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The COMPLETE url — host, path AND query — ONE outbound call should be sent to, verbatim. The\n     * sibling of {@link OVERRIDE_BASE_URL} for the other shape of runtime destination: a partner\n     * that does not implement our contract at their own host, but hands us one opaque url to POST\n     * to (`https://hooks.partner.example/in/abc?token=xyz`, straight out of a webhook row). With a\n     * base-URL override the contract's path would be appended to it and the url would be wrong; with\n     * this one the contract's path is NOT appended and nothing is inserted.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_FULL_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * ONLY a client carrying a `ContextFullUrlFilter` reads it, for exactly the reasons given on\n     * {@link OVERRIDE_BASE_URL}: installing that filter IS the opt-in, and every other client ignores\n     * the key. Not transferred over the wire (per-hop, or it becomes an SSRF pivot across the call\n     * tree), logged (it is what you want in a failed-delivery log line), and UNTRUSTED (a partner\n     * edited it) — which is why re-pointing at it arms the framework's SSRF guard automatically.\n     */\n    static readonly OVERRIDE_FULL_URL = ContextKey.untrusted<string>(\n        'overrideFullUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * NO CREDENTIAL KEYS LIVE HERE.\n     *\n     * `authorization` and `x-webpieces-shared-secret` used to be ContextKeys. That made them\n     * TRANSFERRED keys, so the inbound transfer copied them off the request into the\n     * RequestContext, and every outbound RPC call and enqueued Cloud Task then carried the\n     * caller's credential onward — to services that had no business seeing it.\n     *\n     * A credential belongs to ONE request hop. It is read straight off the {@link HttpRequest}\n     * by the framework AuthFilter, and written straight onto the outbound request by the client\n     * that mints it (NodeProxyClient, GcpTaskInvoker, InMemoryTaskInvoker). It never enters the\n     * magic context, so nothing can propagate it by accident.\n     *\n     * An app that genuinely wants a credential to travel can still register its own ContextKey for\n     * it — but that is now an explicit, visible decision rather than the default.\n     */\n\n    /**\n     * All core context keys (the platform DEFAULT_HEADERS set). A `static readonly` CONSTANT, not a\n     * method: it is compile-time data — a list of the key definitions above — read once at the startup\n     * composition root (`HeaderRegistry.configure` / `HeaderRegistry.DEFAULT_HEADERS`). A method here\n     * would be un-injectable behavior the DI design graph can't reach; a constant is honest data.\n     */\n    static readonly ALL_HEADERS: AnyContextKey[] = [\n        WebpiecesCoreHeaders.REQUEST_ID,\n        WebpiecesCoreHeaders.REQUEST_ID_SOURCE,\n        WebpiecesCoreHeaders.CLIENT_VERSION,\n        WebpiecesCoreHeaders.ACTION_ID,\n        WebpiecesCoreHeaders.USER_ID,\n        WebpiecesCoreHeaders.ORG_ID,\n        WebpiecesCoreHeaders.USER_ROLES,\n        WebpiecesCoreHeaders.SURFACE,\n        WebpiecesCoreHeaders.RECORDING,\n        WebpiecesCoreHeaders.API_CALL_INFO,\n        WebpiecesCoreHeaders.HTTP_METHOD,\n        WebpiecesCoreHeaders.REQUEST_PATH,\n        WebpiecesCoreHeaders.CONTROLLER,\n        WebpiecesCoreHeaders.METHOD,\n        WebpiecesCoreHeaders.OVERRIDE_BASE_URL,\n        WebpiecesCoreHeaders.OVERRIDE_FULL_URL,\n    ];\n}\n"]}
+{"version":3,"file":"WebpiecesCoreHeaders.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesCoreHeaders.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContextKey, AnyContextKey } from '../ContextKey';\nimport { ApiCallInfo } from './ApiCallInfo';\nimport { Surface } from './Surface';\n\n/**\n * Core framework context keys — the minimum the WebPieces framework needs to correlate one\n * request across every service it touches, and across every log line each of them writes.\n *\n * ONE id, propagated unchanged. The first service to see a request without an `x-request-id`\n * generates one (RequestContextHeaders.fillFromRequest); every hop copies it onward verbatim. Grep that id and you\n * have the whole call tree. There is no per-hop id and no parent pointer: a chain of ids you must\n * stitch back together buys nothing a single shared id does not already give you.\n *\n * Lives in core-util (browser-safe) so both the http clients and http-server can reference it.\n *\n * Exposed as {@link HeaderRegistry.DEFAULT_HEADERS} — a service opts into these by\n * passing `platformHeaders=true` to `HeaderRegistry.configure(...)`.\n *\n * Each key's `name` is the logical/log name; `httpHeader` is the wire name.\n */\nexport class WebpiecesCoreHeaders {\n    /**\n     * The id that correlates every hop of one request, and every log line of every hop.\n     * Generated by the first service to see a request without one; propagated unchanged after that.\n     *\n     * - `httpHeader` `x-request-id` → travels DOWN the call tree on every outbound request.\n     * - `responseHeader` `x-request-id` → and back UP on every response, which is the header a\n     *   support desk quotes. This used to be a hard-coded `res.setHeader` in `ExpressWrapper`\n     *   (`stampTransactionId`), reachable by no other key. It is an ordinary registry entry now: the\n     *   server's ONE response choke point writes every key in\n     *   {@link HeaderRegistry.getResponseTxfrKeys}, so a second key joins with no framework edit.\n     * - `responseMerge` `first` → and NOT `collect`. A callee echoes OUR id back at us, so the\n     *   caller's context must KEEP what it already has. `collect` would turn `requestId` into a\n     *   growing array on every client call and break every log line of the request; `last` would\n     *   rewrite it with an echo. `first` makes reading it back a provable no-op for the normal case\n     *   and still adopts an id when a caller somehow had none.\n     */\n    static readonly REQUEST_ID = ContextKey.untrusted<string>(\n        'requestId',\n        'x-request-id',\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n        /*responseHeader*/ 'x-request-id',\n        /*responseMerge*/ 'first',\n    );\n\n    /**\n     * WHICH SERVICE MINTED {@link REQUEST_ID} — the name from {@link ServiceInfo}, stamped by\n     * `RequestContextHeaders.fillFromRequest` ONLY on the branch that generates a new id (i.e. when\n     * the inbound request carried no `x-request-id`). It answers the question the id alone cannot:\n     * \"this trace starts here — is that right?\" An id appearing with no source means it came from\n     * outside; an id sourced by a service that should never be an entry point is a routing bug.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is the WHOLE POINT. If it\n     *   travelled, hop 2 would inherit it, hop 3 would inherit it, and \"who started this trace\"\n     *   would be indistinguishable from \"who passed it along\" — the origin, the one fact this key\n     *   carries, would be lost. It is absent on every hop that did NOT mint the id, which is exactly\n     *   the signal: present == I am the origin.\n     * - `isLogged` TRUE → emitted as a plain string at `jsonPayload.requestIdSource`.\n     */\n    static readonly REQUEST_ID_SOURCE = ContextKey.untrusted<string>(\n        'requestIdSource',\n        /*httpHeader*/ undefined,\n    );\n\n    /**\n     * The CALLER's build version — so a downstream server's logs record which build of the client\n     * called it (surfaces as `jsonPayload.clientVersion`). Distinct from the log line's own `version`\n     * (this service's build): `version` answers \"which build wrote this line?\", `clientVersion`\n     * answers \"which build asked us to?\".\n     *\n     * - `httpHeader` SET → transferred over the wire, BUT unlike a normal transferred key it is NOT\n     *   copied from the context onward. Each hop OVERWRITES it with its OWN `ServiceInfo.getVersion()`\n     *   as it becomes the client to the next hop (see `buildOutboundHeaders`), so on any given server\n     *   `clientVersion` is always the IMMEDIATE caller's version, never a stale grand-caller's.\n     * - `isLogged` TRUE → the inbound value lands in the context and flows through the normal log\n     *   field map; no backend change needed.\n     */\n    static readonly CLIENT_VERSION = ContextKey.untrusted<string>(\n        'clientVersion',\n        'x-webpieces-client-version',\n    );\n\n    /**\n     * A frontend/app-minted correlation id that groups every request triggered by ONE user ACTION.\n     *\n     * An \"action\" is a single thing the user did in the GUI — a CLICK on a button/link, or TYPING in a\n     * field — or a background poller tick: anything that may fan out into MULTIPLE remote calls. That one\n     * action fires 1..N browser HTTP calls, each of which gets its own framework-minted {@link REQUEST_ID}\n     * (one per HTTP call, shared within that call's server→server subtree). `actionId` sits ABOVE\n     * `requestId` and is what stitches those N requests back to the single action that caused them:\n     *\n     *     actionId  (app-minted, ONE per user action, rides EVERY call of that action)\n     *        └── 1..N requestId  (framework-minted, ONE per HTTP call)\n     *\n     * Grep one `actionId` in the logs → every `requestId` it spawned, and every log line of the whole\n     * action. Minted and refreshed by the app (a UI concern), carried under `x-webpieces-actionid`.\n     *\n     * Browser/app-minted ONLY: unlike {@link REQUEST_ID}, the framework transfers and logs it but must\n     * NOT auto-mint one server-side. Absent `actionId` ⇒ a non-action flow (system / cron / task), which\n     * is the correct signal.\n     *\n     * - `httpHeader` SET → transferred: copied off the inbound request into context and re-emitted on\n     *   outbound hops, so the id follows the action across services.\n     * - `isLogged` TRUE → emitted as a plain string on every log line of the request.\n     */\n    static readonly ACTION_ID = ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid');\n\n    /**\n     * WHO the request is acting as, and WHAT they may do. All three are TRUSTED keys: they are the\n     * inputs to authorization decisions, so a reader must be able to tell \"the framework proved\n     * this\" from \"the caller typed this\" — see the trust section of the {@link ContextKey} doc.\n     *\n     * They keep their `httpHeader`, because propagating a verified identity to the next internal\n     * service is the point. What makes that safe is not the header being absent, it is WHO is\n     * allowed to have set it: an inbound value is held PENDING by\n     * `RequestContextHeaders.fillFromRequest` and admitted by `AuthFilter` only on a route that\n     * verified its CALLER (`@WpAuthOidc` / `@WpAuthSharedSecret`). On a browser-reachable route\n     * (`@WpAuthJwt` / public) the value must match what the authenticator itself derived, or the\n     * request is rejected.\n     *\n     * `provenance` says \"an app-bound JwtHook\" rather than naming one hook, because the framework\n     * default ({@link DefaultJwtHook}) stamps NO context entries at all — an app supplies a hook that\n     * returns {@link ContextTuple}s for the keys it can vouch for. Any of these three that an app's\n     * hook does NOT stamp will be rejected when a caller supplies it, which is the correct and loud\n     * outcome: nothing is vouching for it.\n     */\n    static readonly ORG_ID = ContextKey.trusted<string>(\n        'orgId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-org-id',\n    );\n\n    static readonly USER_ID = ContextKey.trusted<string>(\n        'userId',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-user-id',\n    );\n\n    static readonly USER_ROLES = ContextKey.trusted<string>(\n        'roles',\n        'derived from a verified credential by an app-bound JwtHook (a ContextTuple in AuthenticatedCaller)',\n        'x-webpieces-roles',\n    );\n\n    /**\n     * WHICH KIND OF CALLER is driving this request — `gui`, `llm` or `public-api`. See\n     * {@link Surface} for the table and for why it is a property of the CALLER and not of the server.\n     *\n     * TRUSTED, and that is load-bearing twice over. It is what makes an app safe to branch on it in\n     * its OWN authorization logic (\"this endpoint is not exposed to partners\"), and it is what makes\n     * the value in {@link SurfaceEndUserStatus} believable: webpieces sets it itself, from the auth\n     * mode that matched, never from caller input. A caller that simply SENDS `x-wp-surface` at an\n     * endpoint whose auth did not establish one is rejected by `AuthFilter.reconcileWireTrust`, like\n     * every other unvouched trusted header.\n     *\n     * It keeps its `httpHeader` because PROPAGATION is the point: the surface belongs to the ORIGINAL\n     * caller, so `GUI -> api1 -> api2` must leave api2 seeing `gui`. An internal `@WpAuthOidc` hop\n     * verifies its caller, so the propagated value is admitted verbatim — and the auth filter only\n     * ever SETS a surface when none arrived, so an inherited one is never overwritten.\n     */\n    static readonly SURFACE = ContextKey.trusted<Surface>(\n        'surface',\n        'set by the webpieces AuthFilter from the auth mode that matched the incoming request, or inherited from the edge hop that did',\n        'x-wp-surface',\n    );\n\n    /**\n     * Turns on test-case recording for this request (Java: x-webpieces-recording).\n     * Transferred so recording follows the request across service hops.\n     */\n    static readonly RECORDING = ContextKey.untrusted<string>('recording', 'x-webpieces-recording');\n\n    /**\n     * The structured API-call tag ({@link ApiCallInfo}) stamped by {@link LogApiCallImpl} around every\n     * outbound (client) / inbound (server) call. It rides the magic context so EVERY log line emitted\n     * during the call inherits a filterable `api` object, surfacing in GCP as nested\n     * `jsonPayload.api.{side,type,result,path,method}`.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire. Per-hop only: each server/client hop\n     *   stamps its own tag, so a downstream server records `side:'server'`, never the caller's `side:'client'`.\n     * - `isLogged` TRUE → emitted by the logging backends. It carries an OBJECT value, so the backends\n     *   read it via {@link HeaderRegistry.buildStructuredLogFields} (object-aware); the flat\n     *   `buildLogFields()` string map deliberately skips it (typeof-string guard).\n     */\n    static readonly API_CALL_INFO = ContextKey.untrusted<ApiCallInfo>(\n        'api',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The inbound request's HTTP method and path, stamped ONCE from the {@link HttpRequest} by\n     * `RequestContextHeaders.fillFromRequest` (the atomic inbound choke point every transport funnels\n     * through). They surface as top-level `jsonPayload.httpMethod` / `jsonPayload.requestPath` so every\n     * log line of the request carries them — they used to ride inside {@link ApiCallInfo} (`api.path` /\n     * `api.method`) but that coupled a per-CALL logger to the per-REQUEST transport shape.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire: a downstream hop stamps its OWN inbound\n     *   method/path, never the caller's. Outbound client calls never set these (no inbound path).\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly HTTP_METHOD = ContextKey.untrusted<string>(\n        'httpMethod',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly REQUEST_PATH = ContextKey.untrusted<string>(\n        'requestPath',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The routed endpoint's IMPLEMENTATION identity: the concrete controller class name\n     * ({@link RouteMetadata.controllerClassName}, e.g. `LoginController`) and the handler method NAME\n     * ({@link RouteMetadata.methodName}, e.g. `login`), stamped once per request by {@link LogApiFilter}\n     * after route matching so every subsequent log line of the request carries them.\n     *\n     * These say WHICH CODE ran, which is what you actually grep for — far more useful than the raw\n     * `requestPath`. They are the top-level, filterable twin of what previously only lived nested in\n     * {@link ApiCallInfo} (`api.method.controllerName` / `api.method.methodName`). The local console\n     * formatters render them together as a compact `[Controller.method]` bracket; GCP keeps them as two\n     * separate `jsonPayload.controller` / `jsonPayload.method` fields.\n     *\n     * NOTE: `method` here is the CODE method name (e.g. `login`), NOT the HTTP verb — that is\n     * {@link HTTP_METHOD} (`httpMethod`).\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred: each hop stamps its OWN routed controller/method.\n     * - `isLogged` TRUE → emitted by the logging backends as plain strings.\n     */\n    static readonly CONTROLLER = ContextKey.untrusted<string>(\n        'controller',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    static readonly METHOD = ContextKey.untrusted<string>(\n        'method',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The base URL ONE outbound call should go to, overriding whatever the client's `ClientConfig`\n     * bound at construction — the answer to \"POST our published contract to a URL the PARTNER\n     * registered at runtime\" (an `OrganizationWebhook.url` column, an OAuth callback, a per-tenant\n     * or self-hosted host). The destination is DATA, not deployment, so it cannot be a svcName and\n     * there is nothing to register in {@link ClientRegistry}.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_BASE_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * The contract's path IS appended to it (base + `@ApiPath` + `@Endpoint`). When the stored value\n     * is a complete url — the usual partner-webhook row — use {@link OVERRIDE_FULL_URL} instead.\n     *\n     * ONLY a client carrying a `ContextBaseUrlFilter` reads it. Every other client IGNORES this key\n     * entirely, which is what stops an ambient value re-pointing every other client in the same\n     * fan-out loop at a partner's server. Installing that ONE filter IS the opt-in, so\n     * `grep -rn ContextBaseUrlFilter` enumerates every client that can be re-pointed at all.\n     *\n     * - `httpHeader` UNDEFINED → NOT transferred over the wire, and that is load-bearing. This value\n     *   names where THIS hop goes. If it travelled, the callee would inherit it and re-point ITS\n     *   own outbound calls at the same host — one partner-supplied URL turning into an SSRF pivot\n     *   across the whole call tree. It is per-hop, always.\n     * - `isLogged` TRUE → the destination of a partner delivery is exactly what you want in the log\n     *   line when one fails.\n     *\n     * UNTRUSTED, necessarily: it comes from a database column a partner edited. That is precisely\n     * why re-pointing a request ARMS the framework's SSRF guard, automatically, rather than trusting\n     * it — the guard sits beneath every app filter and reads the fact that the request was moved.\n     */\n    static readonly OVERRIDE_BASE_URL = ContextKey.untrusted<string>(\n        'overrideBaseUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * The COMPLETE url — host, path AND query — ONE outbound call should be sent to, verbatim. The\n     * sibling of {@link OVERRIDE_BASE_URL} for the other shape of runtime destination: a partner\n     * that does not implement our contract at their own host, but hands us one opaque url to POST\n     * to (`https://hooks.partner.example/in/abc?token=xyz`, straight out of a webhook row). With a\n     * base-URL override the contract's path would be appended to it and the url would be wrong; with\n     * this one the contract's path is NOT appended and nothing is inserted.\n     *\n     * ```ts\n     * RequestContext.run(() => {\n     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.OVERRIDE_FULL_URL, webhook.url);\n     *     return partnerWebhookClient.deliver(envelope);\n     * });\n     * ```\n     *\n     * ONLY a client carrying a `ContextFullUrlFilter` reads it, for exactly the reasons given on\n     * {@link OVERRIDE_BASE_URL}: installing that filter IS the opt-in, and every other client ignores\n     * the key. Not transferred over the wire (per-hop, or it becomes an SSRF pivot across the call\n     * tree), logged (it is what you want in a failed-delivery log line), and UNTRUSTED (a partner\n     * edited it) — which is why re-pointing at it arms the framework's SSRF guard automatically.\n     */\n    static readonly OVERRIDE_FULL_URL = ContextKey.untrusted<string>(\n        'overrideFullUrl',\n        /*httpHeader*/ undefined,\n        /*maskInLogs*/ false,\n        /*isLogged*/ true,\n    );\n\n    /**\n     * NO CREDENTIAL KEYS LIVE HERE.\n     *\n     * `authorization` and `x-webpieces-shared-secret` used to be ContextKeys. That made them\n     * TRANSFERRED keys, so the inbound transfer copied them off the request into the\n     * RequestContext, and every outbound RPC call and enqueued Cloud Task then carried the\n     * caller's credential onward — to services that had no business seeing it.\n     *\n     * A credential belongs to ONE request hop. It is read straight off the {@link HttpRequest}\n     * by the framework AuthFilter, and written straight onto the outbound request by the client\n     * that mints it (NodeProxyClient, GcpTaskInvoker, InMemoryTaskInvoker). It never enters the\n     * magic context, so nothing can propagate it by accident.\n     *\n     * An app that genuinely wants a credential to travel can still register its own ContextKey for\n     * it — but that is now an explicit, visible decision rather than the default.\n     */\n\n    /**\n     * All core context keys (the platform DEFAULT_HEADERS set). A `static readonly` CONSTANT, not a\n     * method: it is compile-time data — a list of the key definitions above — read once at the startup\n     * composition root (`HeaderRegistry.configure` / `HeaderRegistry.DEFAULT_HEADERS`). A method here\n     * would be un-injectable behavior the DI design graph can't reach; a constant is honest data.\n     */\n    static readonly ALL_HEADERS: AnyContextKey[] = [\n        WebpiecesCoreHeaders.REQUEST_ID,\n        WebpiecesCoreHeaders.REQUEST_ID_SOURCE,\n        WebpiecesCoreHeaders.CLIENT_VERSION,\n        WebpiecesCoreHeaders.ACTION_ID,\n        WebpiecesCoreHeaders.USER_ID,\n        WebpiecesCoreHeaders.ORG_ID,\n        WebpiecesCoreHeaders.USER_ROLES,\n        WebpiecesCoreHeaders.SURFACE,\n        WebpiecesCoreHeaders.RECORDING,\n        WebpiecesCoreHeaders.API_CALL_INFO,\n        WebpiecesCoreHeaders.HTTP_METHOD,\n        WebpiecesCoreHeaders.REQUEST_PATH,\n        WebpiecesCoreHeaders.CONTROLLER,\n        WebpiecesCoreHeaders.METHOD,\n        WebpiecesCoreHeaders.OVERRIDE_BASE_URL,\n        WebpiecesCoreHeaders.OVERRIDE_FULL_URL,\n    ];\n}\n"]}

package/src/index.d.ts

@@ -69,6 +69,7 @@ export { WebpiecesDefaultFailureClassifier, WEBPIECES_DEFAULT_FAILURE_CLASSIFIER
 export { templateDeriver } from './http/templateDeriver';
 export { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';
 export { ContextReader } from './http/ContextReader';
+export { ContextWriter, ContextStore } from './http/ContextWriter';
 export { DestinationTrust } from './http/DestinationTrust';
 export { ContextMgr } from './http/ContextMgr';
 export { LogApiCallImpl } from './http/LogApiCall';

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport type {\n    AnyContextKey,\n    AnyTrustedContextKey,\n    AnyUntrustedContextKey,\n    Trust,\n} from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\nexport {\n    LogChunker,\n    LogChunkerImpl,\n    LogChunkInfo,\n    MAX_GCP_LOG_BYTES,\n    GCP_LOG_BUDGET_BYTES,\n} from './logging/LogChunker';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the API error taxonomy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    WpAuthPublic,\n    WpAuthJwt,\n    rolesRequired,\n    MISSING_AUTH_DECORATOR_FIX,\n    WpAuthOidc,\n    WpAuthSharedSecret,\n    WpAuthWebhook,\n    WpAuthApiKey,\n    WpAuthLocalOnly,\n    MaskLog,\n    getApiPath,\n    getEndpoints,\n    getEndpointHttpMethod,\n    getEndpointOptions,\n    getEndpointOperation,\n    getEndpointKind,\n    getEndpointKinds,\n    getMaskSpec,\n    isFormPost,\n    isRawBody,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    assertEveryExternalEndpointDeclaresCaller,\n    assertEveryWebhookEndpointRetainsRawBody,\n    validateNoConflictingDecorators,\n    METADATA_KEYS,\n} from './http/decorators';\nexport {\n    PathParam,\n    QueryParam,\n    getHttpParameterDeclarations,\n} from './http/http-parameter-decorators';\nexport {\n    WpInternal,\n    WpIpcEndpoint,\n    isInternalApi,\n    getIpcApiId,\n    getIpcEndpoints,\n    getIpcEndpointKind,\n    getIpcMaskSpec,\n    assertInternalApi,\n    assertNotInternalApi,\n    IPC_METADATA_KEYS,\n} from './ipc/IpcDecorators';\nexport type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';\n// The runtime representation of ONE route (split out of decorators.ts for file size only).\nexport { RouteMetadata } from './http/RouteMetadata';\nexport { RouteMetadataFactory } from './http/RouteMetadataFactory';\nexport {\n    BoundHttpRequest,\n    HttpContractMapper,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n} from './http/HttpContract';\nexport {\n    StreamCorrelation,\n    StreamEnvelope,\n    StreamingEndpointMetadata,\n    StreamEventValidator,\n    StreamTransportError,\n    StreamWriter,\n    WpStream,\n    getStreamingEndpoint,\n} from './http/StreamingContract';\nexport type {\n    RequestStream,\n    ResponseStream,\n    StreamEnvelopeKind,\n    StreamFailureOptions,\n} from './http/StreamingContract';\nexport type {\n    EndpointResponseType,\n    HttpMethod,\n    HttpParameterSource,\n    HttpParameterValueType,\n} from './http/HttpContract';\nexport { GET, POST } from './http/HttpContract';\nexport type {\n    EndpointKind,\n    EndpointOperation,\n    EndpointOptions,\n    ExternalEndpointOptions,\n} from './http/decorators';\nexport {\n    RPC,\n    CLOUDTASKS,\n    CRON,\n    EXTERNAL,\n    READ,\n    WRITE_IDEMPOTENT,\n    WRITE,\n} from './http/decorators';\nexport {\n    WpMcpTool,\n    WpMcpToolHints,\n    WpMcpToolMetadata,\n    getWpMcpTools,\n    mcpHintsForOperation,\n} from './mcp/McpMetadata';\nexport type { WpMcpMethodDecorator, WpMcpToolOptions } from './mcp/McpMetadata';\nexport { WpMcpAuthJwt, WpMcpJwtAuthMetadata, getWpMcpAuthJwt } from './mcp/McpAuthMetadata';\nexport {\n    WpDto,\n    WpDtoField,\n    WpDtoFieldOptions,\n    WpMcpHeader,\n    WpDtoMapFieldOptions,\n    WpDtoFieldMetadata,\n    WpResponseDto,\n    ApiJsonSchema,\n    DtoValidationFailure,\n    DtoSchemaBuilder,\n} from './mcp/DtoSchema';\nexport type { DtoClass, DtoElementType, DtoValue } from './mcp/DtoSchema';\n// The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.\nexport { AuthMeta } from './http/auth-mode';\nexport type {\n    AuthMode,\n    ApiKeyCredential,\n    ApiKeyCredentials,\n    JwtRoles,\n    JwtRequirement,\n} from './http/auth-mode';\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming. Split out of decorators.ts for file size only;\n// one-way dependency api-kind -> decorators, and the barrel keeps the surface identical.\nexport {\n    Rpc,\n    PubSub,\n    Queue,\n    ENDPOINT_KINDS_BY_API_KIND,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n} from './http/api-kind';\nexport type { ApiKind } from './http/api-kind';\n// WHO calls an `external` endpoint — the caller declaration\n// @Endpoint(POST, ..., WRITE, EXTERNAL, { calledBy })\n// requires, and the reader for it.\nexport {\n    EXTERNAL_SYSTEM_KINDS,\n    DEFAULT_CALLER_KIND,\n    ExternalCaller,\n    isExternalSystemKind,\n    getEndpointCaller,\n} from './http/external-caller';\nexport type { ExternalSystemKind } from './http/external-caller';\n// Client-side shared-secret store (the value THIS service sends per @WpAuthSharedSecret key).\nexport { Secrets, SECRETS } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// Authentication subtype constants.\nexport {\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './errors';\n\nexport { NetworkRejectClassifier } from './http/networkReject';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { CallRegistry } from './http/CallRegistry';\nexport { CallDeadline } from './http/CallDeadline';\nexport { CallContext } from './http/CallStrategy';\nexport type { Attempt, CallStrategy } from './http/CallStrategy';\nexport { ApiCallTimeoutError } from './http/ApiCallTimeoutError';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n\n// \"What service am I\" — set once at startup, read by the logging backends and by\n// RequestContextHeaders (to stamp requestIdSource on ids this service mints).\nexport { ServiceInfo } from './http/ServiceInfo';\n// \"Where am I running\" — declared once at startup (setupRuntime, from RuntimeSetupOptions.locality).\n// The ONE input to @WpAuthLocalOnly enforcement. Undeclared reads as DEPLOYED (fail safe).\nexport { RuntimeLocality } from './http/RuntimeLocality';\nexport type { Locality } from './http/RuntimeLocality';\n// The ENTIRE HTTP response as pure data — the ONE form both transports (express, fetch) are\n// normalised into, so an ErrorTranslator implementation is written once and serves both.\nexport { HttpHeader, HttpResponseStatus, HttpResponseDto } from './http/HttpResponseDto';\n// Pluggable, bidirectional error translation (app exception <-> the WHOLE response). Set on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport type { ErrorTranslator } from './http/ErrorTranslator';\n// THE webpieces default translator — always installed, and what an app's own translator delegates to\n// in order to decline an error. ONE class, both halves, node and browser alike.\nexport {\n    WebpiecesDefaultErrorTranslator,\n    WEBPIECES_DEFAULT_ERROR_TRANSLATOR,\n} from './http/WebpiecesDefaultErrorTranslator';\n// WHICH KIND OF CALLER drove this request (gui / llm / public-api), and the per-request end-user\n// status derived from it — the replacement for the deleted per-router EndUserStatus.\nexport { SurfaceEndUserStatus } from './http/Surface';\nexport type { Surface } from './http/Surface';\n// The ONE rule for an error RECEIVED from another process, shared verbatim by HTTP and IPC.\nexport { ReceivedApiErrorRule } from './errors/ReceivedApiErrorRule';\n// Pluggable per-client failure classification (is a thrown API-call error a real failure or an\n// expected non-failure?). Registered on ClientRegistry at startup; consulted by LogApiCall.\nexport type { FailureClassifier } from './http/FailureClassifier';\nexport { KeyedFailureClassifier } from './http/FailureClassifier';\nexport {\n    WebpiecesDefaultFailureClassifier,\n    WEBPIECES_DEFAULT_FAILURE_CLASSIFIER,\n} from './http/WebpiecesDefaultFailureClassifier';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\n\n// The OUTBOUND half of the trust model: whether a TRUSTED context key may ride to the endpoint being\n// called. Built ONLY from the destination endpoint's AuthMode — see the class doc.\nexport { DestinationTrust } from './http/DestinationTrust';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). NOT a singleton: construct one per environment\n// with that environment's ApiCallContext — `new LogApiCallImpl(new RequestContextApiCallContext())`\n// on node, `new LogApiCallImpl(new BrowserApiCallContext())` in a browser.\nexport { LogApiCallImpl } from './http/LogApiCall';\n\n// Opt-in field masking for the LogApiCall log path — declare per-api sensitive fields so secrets\n// (OAuth refresh tokens, id-token JWTs) are masked in the logs while the real value stays on the wire.\nexport { MaskSpec } from './http/LogFieldMask';\nexport type { MaskMode } from './http/LogFieldMask';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl lives in @webpieces/core-context, the browser one in\n// @webpieces/http-client-browser; each is CONSTRUCTED by its package, never installed globally.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiType, ApiResult } from './http/ApiCallInfo';\n// Console-render bridge: turns LogApiCall's [LogApiCall] bracket into [API.{side}.{phase}] locally.\nexport {\n    ApiCallLogName,\n    ApiCallLogNameImpl,\n    LOG_API_CALL_LOGGER_NAME,\n} from './http/ApiCallLogName';\nexport { ApiMethodInfo } from './http/ApiMethodInfo';\nexport type { ApiSide } from './http/ApiMethodInfo';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport {\n    RecordedEndpoint,\n    RecordedError,\n    RecordedTestCase,\n} from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n\n// ---------------------------------------------------------------------------------------------\n// Filter-chain primitives, shared by BOTH chains: the inbound server chain\n// (`Filter<MethodMeta, WpResponse<unknown>>`, @webpieces/http-routing) and the outbound client\n// chain (`Filter<ClientRequest, Response>`, @webpieces/http-client-core). Declared once, here, in\n// the package both depend on — see the class doc for why a second pair would be a shim.\nexport { Filter } from './filters/Filter';\nexport type { Service } from './filters/Filter';\nexport { FilterChain } from './filters/FilterChain';\n\nexport {\n    ApiError,\n    ApiNotFoundError,\n    ApiDependencyError,\n    ApiBadGatewayError,\n    ApiUnavailableError,\n    ApiDependencyTimeoutError,\n    ApiImplementationError,\n    ApiRateLimitedError,\n    ApiForbiddenError,\n    ApiRequestTimeoutError,\n    ApiEndUserError,\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiDependencyBackoffError,\n    ApiConnectionError,\n    ApiEndpointNotFoundError,\n    ApiConflictError,\n    ApiUnprocessableError,\n    ApiPreconditionFailedError,\n    ApiUnsupportedMediaTypeError,\n    ApiNotImplementedError,\n    ApiCodedError,\n    ApiErrorCodec,\n    ApiErrorPayload,\n    ApiErrorBoundary,\n} from './errors';\nexport type { ApiErrorKind, ApiStatusCode, EdgeHttpStatus } from './errors';\nexport { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';\nexport type { PublishedKind, PublishedApiError } from './http/ApiErrorHttpStatus';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport type {\n    AnyContextKey,\n    AnyTrustedContextKey,\n    AnyUntrustedContextKey,\n    Trust,\n} from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\nexport {\n    LogChunker,\n    LogChunkerImpl,\n    LogChunkInfo,\n    MAX_GCP_LOG_BYTES,\n    GCP_LOG_BUDGET_BYTES,\n} from './logging/LogChunker';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the API error taxonomy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    WpAuthPublic,\n    WpAuthJwt,\n    rolesRequired,\n    MISSING_AUTH_DECORATOR_FIX,\n    WpAuthOidc,\n    WpAuthSharedSecret,\n    WpAuthWebhook,\n    WpAuthApiKey,\n    WpAuthLocalOnly,\n    MaskLog,\n    getApiPath,\n    getEndpoints,\n    getEndpointHttpMethod,\n    getEndpointOptions,\n    getEndpointOperation,\n    getEndpointKind,\n    getEndpointKinds,\n    getMaskSpec,\n    isFormPost,\n    isRawBody,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    assertEveryExternalEndpointDeclaresCaller,\n    assertEveryWebhookEndpointRetainsRawBody,\n    validateNoConflictingDecorators,\n    METADATA_KEYS,\n} from './http/decorators';\nexport {\n    PathParam,\n    QueryParam,\n    getHttpParameterDeclarations,\n} from './http/http-parameter-decorators';\nexport {\n    WpInternal,\n    WpIpcEndpoint,\n    isInternalApi,\n    getIpcApiId,\n    getIpcEndpoints,\n    getIpcEndpointKind,\n    getIpcMaskSpec,\n    assertInternalApi,\n    assertNotInternalApi,\n    IPC_METADATA_KEYS,\n} from './ipc/IpcDecorators';\nexport type { IpcApiType, IpcEndpointKind, IpcEndpointOptions } from './ipc/IpcDecorators';\n// The runtime representation of ONE route (split out of decorators.ts for file size only).\nexport { RouteMetadata } from './http/RouteMetadata';\nexport { RouteMetadataFactory } from './http/RouteMetadataFactory';\nexport {\n    BoundHttpRequest,\n    HttpContractMapper,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n} from './http/HttpContract';\nexport {\n    StreamCorrelation,\n    StreamEnvelope,\n    StreamingEndpointMetadata,\n    StreamEventValidator,\n    StreamTransportError,\n    StreamWriter,\n    WpStream,\n    getStreamingEndpoint,\n} from './http/StreamingContract';\nexport type {\n    RequestStream,\n    ResponseStream,\n    StreamEnvelopeKind,\n    StreamFailureOptions,\n} from './http/StreamingContract';\nexport type {\n    EndpointResponseType,\n    HttpMethod,\n    HttpParameterSource,\n    HttpParameterValueType,\n} from './http/HttpContract';\nexport { GET, POST } from './http/HttpContract';\nexport type {\n    EndpointKind,\n    EndpointOperation,\n    EndpointOptions,\n    ExternalEndpointOptions,\n} from './http/decorators';\nexport {\n    RPC,\n    CLOUDTASKS,\n    CRON,\n    EXTERNAL,\n    READ,\n    WRITE_IDEMPOTENT,\n    WRITE,\n} from './http/decorators';\nexport {\n    WpMcpTool,\n    WpMcpToolHints,\n    WpMcpToolMetadata,\n    getWpMcpTools,\n    mcpHintsForOperation,\n} from './mcp/McpMetadata';\nexport type { WpMcpMethodDecorator, WpMcpToolOptions } from './mcp/McpMetadata';\nexport { WpMcpAuthJwt, WpMcpJwtAuthMetadata, getWpMcpAuthJwt } from './mcp/McpAuthMetadata';\nexport {\n    WpDto,\n    WpDtoField,\n    WpDtoFieldOptions,\n    WpMcpHeader,\n    WpDtoMapFieldOptions,\n    WpDtoFieldMetadata,\n    WpResponseDto,\n    ApiJsonSchema,\n    DtoValidationFailure,\n    DtoSchemaBuilder,\n} from './mcp/DtoSchema';\nexport type { DtoClass, DtoElementType, DtoValue } from './mcp/DtoSchema';\n// The TYPE layer of the auth surface — likewise split out of decorators.ts for file size only.\nexport { AuthMeta } from './http/auth-mode';\nexport type {\n    AuthMode,\n    ApiKeyCredential,\n    ApiKeyCredentials,\n    JwtRoles,\n    JwtRequirement,\n} from './http/auth-mode';\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming. Split out of decorators.ts for file size only;\n// one-way dependency api-kind -> decorators, and the barrel keeps the surface identical.\nexport {\n    Rpc,\n    PubSub,\n    Queue,\n    ENDPOINT_KINDS_BY_API_KIND,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n} from './http/api-kind';\nexport type { ApiKind } from './http/api-kind';\n// WHO calls an `external` endpoint — the caller declaration\n// @Endpoint(POST, ..., WRITE, EXTERNAL, { calledBy })\n// requires, and the reader for it.\nexport {\n    EXTERNAL_SYSTEM_KINDS,\n    DEFAULT_CALLER_KIND,\n    ExternalCaller,\n    isExternalSystemKind,\n    getEndpointCaller,\n} from './http/external-caller';\nexport type { ExternalSystemKind } from './http/external-caller';\n// Client-side shared-secret store (the value THIS service sends per @WpAuthSharedSecret key).\nexport { Secrets, SECRETS } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// Authentication subtype constants.\nexport {\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './errors';\n\nexport { NetworkRejectClassifier } from './http/networkReject';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { CallRegistry } from './http/CallRegistry';\nexport { CallDeadline } from './http/CallDeadline';\nexport { CallContext } from './http/CallStrategy';\nexport type { Attempt, CallStrategy } from './http/CallStrategy';\nexport { ApiCallTimeoutError } from './http/ApiCallTimeoutError';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n\n// \"What service am I\" — set once at startup, read by the logging backends and by\n// RequestContextHeaders (to stamp requestIdSource on ids this service mints).\nexport { ServiceInfo } from './http/ServiceInfo';\n// \"Where am I running\" — declared once at startup (setupRuntime, from RuntimeSetupOptions.locality).\n// The ONE input to @WpAuthLocalOnly enforcement. Undeclared reads as DEPLOYED (fail safe).\nexport { RuntimeLocality } from './http/RuntimeLocality';\nexport type { Locality } from './http/RuntimeLocality';\n// The ENTIRE HTTP response as pure data — the ONE form both transports (express, fetch) are\n// normalised into, so an ErrorTranslator implementation is written once and serves both.\nexport { HttpHeader, HttpResponseStatus, HttpResponseDto } from './http/HttpResponseDto';\n// Pluggable, bidirectional error translation (app exception <-> the WHOLE response). Set on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport type { ErrorTranslator } from './http/ErrorTranslator';\n// THE webpieces default translator — always installed, and what an app's own translator delegates to\n// in order to decline an error. ONE class, both halves, node and browser alike.\nexport {\n    WebpiecesDefaultErrorTranslator,\n    WEBPIECES_DEFAULT_ERROR_TRANSLATOR,\n} from './http/WebpiecesDefaultErrorTranslator';\n// WHICH KIND OF CALLER drove this request (gui / llm / public-api), and the per-request end-user\n// status derived from it — the replacement for the deleted per-router EndUserStatus.\nexport { SurfaceEndUserStatus } from './http/Surface';\nexport type { Surface } from './http/Surface';\n// The ONE rule for an error RECEIVED from another process, shared verbatim by HTTP and IPC.\nexport { ReceivedApiErrorRule } from './errors/ReceivedApiErrorRule';\n// Pluggable per-client failure classification (is a thrown API-call error a real failure or an\n// expected non-failure?). Registered on ClientRegistry at startup; consulted by LogApiCall.\nexport type { FailureClassifier } from './http/FailureClassifier';\nexport { KeyedFailureClassifier } from './http/FailureClassifier';\nexport {\n    WebpiecesDefaultFailureClassifier,\n    WEBPIECES_DEFAULT_FAILURE_CLASSIFIER,\n} from './http/WebpiecesDefaultFailureClassifier';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\nexport { ContextWriter, ContextStore } from './http/ContextWriter';\n\n// The OUTBOUND half of the trust model: whether a TRUSTED context key may ride to the endpoint being\n// called. Built ONLY from the destination endpoint's AuthMode — see the class doc.\nexport { DestinationTrust } from './http/DestinationTrust';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above). NOT a singleton: construct one per environment\n// with that environment's ApiCallContext — `new LogApiCallImpl(new RequestContextApiCallContext())`\n// on node, `new LogApiCallImpl(new BrowserApiCallContext())` in a browser.\nexport { LogApiCallImpl } from './http/LogApiCall';\n\n// Opt-in field masking for the LogApiCall log path — declare per-api sensitive fields so secrets\n// (OAuth refresh tokens, id-token JWTs) are masked in the logs while the real value stays on the wire.\nexport { MaskSpec } from './http/LogFieldMask';\nexport type { MaskMode } from './http/LogFieldMask';\n\n// The structured `api` tag + the context-writer seam LogApiCall stamps through. The Node\n// RequestContext-backed impl lives in @webpieces/core-context, the browser one in\n// @webpieces/http-client-browser; each is CONSTRUCTED by its package, never installed globally.\nexport { ApiCallInfo } from './http/ApiCallInfo';\nexport type { ApiType, ApiResult } from './http/ApiCallInfo';\n// Console-render bridge: turns LogApiCall's [LogApiCall] bracket into [API.{side}.{phase}] locally.\nexport {\n    ApiCallLogName,\n    ApiCallLogNameImpl,\n    LOG_API_CALL_LOGGER_NAME,\n} from './http/ApiCallLogName';\nexport { ApiMethodInfo } from './http/ApiMethodInfo';\nexport type { ApiSide } from './http/ApiMethodInfo';\nexport type { ApiCallContext } from './http/ApiCallContext';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport {\n    RecordedEndpoint,\n    RecordedError,\n    RecordedTestCase,\n} from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n\n// ---------------------------------------------------------------------------------------------\n// Filter-chain primitives, shared by BOTH chains: the inbound server chain\n// (`Filter<MethodMeta, WpResponse<unknown>>`, @webpieces/http-routing) and the outbound client\n// chain (`Filter<ClientRequest, Response>`, @webpieces/http-client-core). Declared once, here, in\n// the package both depend on — see the class doc for why a second pair would be a shim.\nexport { Filter } from './filters/Filter';\nexport type { Service } from './filters/Filter';\nexport { FilterChain } from './filters/FilterChain';\n\nexport {\n    ApiError,\n    ApiNotFoundError,\n    ApiDependencyError,\n    ApiBadGatewayError,\n    ApiUnavailableError,\n    ApiDependencyTimeoutError,\n    ApiImplementationError,\n    ApiRateLimitedError,\n    ApiForbiddenError,\n    ApiRequestTimeoutError,\n    ApiEndUserError,\n    ApiBadRequestError,\n    ApiUnauthorizedError,\n    ApiDependencyBackoffError,\n    ApiConnectionError,\n    ApiEndpointNotFoundError,\n    ApiConflictError,\n    ApiUnprocessableError,\n    ApiPreconditionFailedError,\n    ApiUnsupportedMediaTypeError,\n    ApiNotImplementedError,\n    ApiCodedError,\n    ApiErrorCodec,\n    ApiErrorPayload,\n    ApiErrorBoundary,\n} from './errors';\nexport type { ApiErrorKind, ApiStatusCode, EdgeHttpStatus } from './errors';\nexport { ApiErrorHttpStatus } from './http/ApiErrorHttpStatus';\nexport type { PublishedKind, PublishedApiError } from './http/ApiErrorHttpStatus';\n"]}