@webpieces/core-util 0.4.957 → 0.4.959

package/package.json

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

package/src/http/ApiCallInfo.d.ts

@@ -1,4 +1,5 @@
 import { ApiMethodInfo } from './ApiMethodInfo';
+import { MaskSpec } from './LogFieldMask';
 /**
  * ApiCallInfo - the structured tag stamped into RequestContext around every API call
  * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable
@@ -15,6 +16,7 @@ import { ApiMethodInfo } from './ApiMethodInfo';
  * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)
  * - `jsonPayload.api.responseCount>100`         — responses containing many logical items
  * - `jsonPayload.api:*`                          — "API traffic only" (tracing + the recorder)
+ * - `jsonPayload.api.http.status=404`            — an HTTP client call the vendor answered 404 (#1339)
  *
  * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —
  * rename a field and the filter renames with it. The identity lives NESTED under `api.method`
@@ -47,6 +49,46 @@ export type ApiCallDirection = 'request' | 'response';
 export type ApiResult = 'success' | 'failure';
 /** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */
 export type { ApiSide } from './ApiMethodInfo';
+/**
+ * The HTTP facts of ONE client call's last transmission — surfaces as `jsonPayload.api.http.*`.
+ * Filled ONLY by the HTTP client (node and browser), which is the one layer that has a verb, a url
+ * and a status; in-process, pubsub and cloud-task calls leave {@link ApiCallInfo.http} unset. It
+ * exists because a vendor's 404 and its 500 were indistinguishable in the logs when only the DTOs
+ * were recorded.
+ *
+ * Never headers or tokens: the url is MASKED ({@link maskUrl}) before it gets here.
+ */
+export declare class HttpCallFacts {
+    /** The HTTP verb, e.g. `GET`. */
+    readonly method: string;
+    /** The final absolute url, masked: no userinfo, and `@MaskLog` field names' query values redacted. */
+    readonly url: string;
+    /** The status of the last response received. */
+    readonly status: number;
+    constructor(
+    /** The HTTP verb, e.g. `GET`. */
+    method: string, 
+    /** The final absolute url, masked: no userinfo, and `@MaskLog` field names' query values redacted. */
+    url: string, 
+    /** The status of the last response received. */
+    status: number);
+    /**
+     * The url as it may be logged: any `user:password@` userinfo is dropped, and the value of every
+     * query key the endpoint's `@MaskLog` names is replaced with `*****` (a `?token=` the DTO mask
+     * already hides must not reappear in the url).
+     */
+    static maskUrl(url: string, mask: MaskSpec | undefined): string;
+    private static decode;
+}
+/**
+ * The per-call slot the HTTP client fills with {@link HttpCallFacts} as each response arrives, and
+ * {@link LogApiCallImpl} reads when it stamps the response tag. A holder rather than a return value
+ * because the facts are known DEEP in the transport while the tag is written at the top of the call;
+ * the last transmission (after redirects, a 401 refresh or a retry) wins.
+ */
+export declare class HttpCallFactsHolder {
+    facts: HttpCallFacts | undefined;
+}
 export declare class ApiCallInfo {
     /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under
      *  `jsonPayload.api.method`. */
@@ -59,11 +101,13 @@ export declare class ApiCallInfo {
      * request has no duration yet. Present on BOTH the success and failure paths, so
      * `jsonPayload.api.durationMs>1000 AND api.result="failure"` finds slow failures.
      *
-     * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over
-     * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP
-     * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is
-     * the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
-     * portable Error TYPE rather than by status code.
+     * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the
+     * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have
+     * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})
+     * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
+     * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP
+     * client's status lives in the optional, nested {@link http} — present only where there IS an
+     * HTTP exchange, so nothing transport-neutral ever reads it.
      */
     readonly durationMs?: number | undefined;
     /**
@@ -81,6 +125,13 @@ export declare class ApiCallInfo {
     readonly responseSize?: number | undefined;
     /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */
     readonly responseCount?: number | undefined;
+    /**
+     * The HTTP verb, masked url and status of the call's last transmission — `jsonPayload.api.http.*`.
+     * RESPONSE tag only, and only for a call made by the HTTP client (success AND failure, so
+     * `api.result="failure" AND api.http.status=429` finds a vendor throttling us). Unset for
+     * in-process, pubsub and cloud-task calls. See {@link HttpCallFacts}.
+     */
+    readonly http?: HttpCallFacts | undefined;
     constructor(
     /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under
      *  `jsonPayload.api.method`. */
@@ -92,11 +143,13 @@ export declare class ApiCallInfo {
      * request has no duration yet. Present on BOTH the success and failure paths, so
      * `jsonPayload.api.durationMs>1000 AND api.result="failure"` finds slow failures.
      *
-     * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over
-     * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP
-     * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is
-     * the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
-     * portable Error TYPE rather than by status code.
+     * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the
+     * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have
+     * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})
+     * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
+     * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP
+     * client's status lives in the optional, nested {@link http} — present only where there IS an
+     * HTTP exchange, so nothing transport-neutral ever reads it.
      */
     durationMs?: number | undefined, 
     /**
@@ -113,5 +166,12 @@ export declare class ApiCallInfo {
      *  a thrown error produced no response body to measure. Total size, pre-chunking. */
     responseSize?: number | undefined, 
     /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */
-    responseCount?: number | undefined);
+    responseCount?: number | undefined, 
+    /**
+     * The HTTP verb, masked url and status of the call's last transmission — `jsonPayload.api.http.*`.
+     * RESPONSE tag only, and only for a call made by the HTTP client (success AND failure, so
+     * `api.result="failure" AND api.http.status=429` finds a vendor throttling us). Unset for
+     * in-process, pubsub and cloud-task calls. See {@link HttpCallFacts}.
+     */
+    http?: HttpCallFacts | undefined);
 }

package/src/http/ApiCallInfo.js

@@ -1,6 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiCallInfo = void 0;
+exports.ApiCallInfo = exports.HttpCallFactsHolder = exports.HttpCallFacts = void 0;
+/**
+ * The HTTP facts of ONE client call's last transmission — surfaces as `jsonPayload.api.http.*`.
+ * Filled ONLY by the HTTP client (node and browser), which is the one layer that has a verb, a url
+ * and a status; in-process, pubsub and cloud-task calls leave {@link ApiCallInfo.http} unset. It
+ * exists because a vendor's 404 and its 500 were indistinguishable in the logs when only the DTOs
+ * were recorded.
+ *
+ * Never headers or tokens: the url is MASKED ({@link maskUrl}) before it gets here.
+ */
+class HttpCallFacts {
+    method;
+    url;
+    status;
+    constructor(
+    /** The HTTP verb, e.g. `GET`. */
+    method, 
+    /** The final absolute url, masked: no userinfo, and `@MaskLog` field names' query values redacted. */
+    url, 
+    /** The status of the last response received. */
+    status) {
+        this.method = method;
+        this.url = url;
+        this.status = status;
+    }
+    /**
+     * The url as it may be logged: any `user:password@` userinfo is dropped, and the value of every
+     * query key the endpoint's `@MaskLog` names is replaced with `*****` (a `?token=` the DTO mask
+     * already hides must not reappear in the url).
+     */
+    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds
+    static maskUrl(url, mask) {
+        const withoutUserInfo = url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@?#]*@/i, '$1');
+        const queryAt = withoutUserInfo.indexOf('?');
+        if (queryAt < 0 || mask === undefined)
+            return withoutUserInfo;
+        const query = withoutUserInfo
+            .slice(queryAt + 1)
+            .split('&')
+            .map((pair) => {
+            const equals = pair.indexOf('=');
+            const key = equals < 0 ? pair : pair.slice(0, equals);
+            return mask.modeFor(HttpCallFacts.decode(key)) === undefined ? pair : `${key}=*****`;
+        })
+            .join('&');
+        return `${withoutUserInfo.slice(0, queryAt)}?${query}`;
+    }
+    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds
+    static decode(key) {
+        // A malformed escape is logged as written; it can never be a masked field name anyway.
+        return /%(?![0-9a-f]{2})/i.test(key) ? key : decodeURIComponent(key);
+    }
+}
+exports.HttpCallFacts = HttpCallFacts;
+/**
+ * The per-call slot the HTTP client fills with {@link HttpCallFacts} as each response arrives, and
+ * {@link LogApiCallImpl} reads when it stamps the response tag. A holder rather than a return value
+ * because the facts are known DEEP in the transport while the tag is written at the top of the call;
+ * the last transmission (after redirects, a 401 refresh or a retry) wins.
+ */
+class HttpCallFactsHolder {
+    facts = undefined;
+}
+exports.HttpCallFactsHolder = HttpCallFactsHolder;
 class ApiCallInfo {
     method;
     type;
@@ -9,6 +72,7 @@ class ApiCallInfo {
     requestSize;
     responseSize;
     responseCount;
+    http;
     constructor(
     /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under
      *  `jsonPayload.api.method`. */
@@ -20,11 +84,13 @@ class ApiCallInfo {
      * request has no duration yet. Present on BOTH the success and failure paths, so
      * `jsonPayload.api.durationMs>1000 AND api.result="failure"` finds slow failures.
      *
-     * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over
-     * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP
-     * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is
-     * the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
-     * portable Error TYPE rather than by status code.
+     * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the
+     * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have
+     * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})
+     * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
+     * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP
+     * client's status lives in the optional, nested {@link http} — present only where there IS an
+     * HTTP exchange, so nothing transport-neutral ever reads it.
      */
     durationMs, 
     /**
@@ -41,7 +107,14 @@ class ApiCallInfo {
      *  a thrown error produced no response body to measure. Total size, pre-chunking. */
     responseSize, 
     /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */
-    responseCount) {
+    responseCount, 
+    /**
+     * The HTTP verb, masked url and status of the call's last transmission — `jsonPayload.api.http.*`.
+     * RESPONSE tag only, and only for a call made by the HTTP client (success AND failure, so
+     * `api.result="failure" AND api.http.status=429` finds a vendor throttling us). Unset for
+     * in-process, pubsub and cloud-task calls. See {@link HttpCallFacts}.
+     */
+    http) {
         this.method = method;
         this.type = type;
         this.result = result;
@@ -49,6 +122,7 @@ class ApiCallInfo {
         this.requestSize = requestSize;
         this.responseSize = responseSize;
         this.responseCount = responseCount;
+        this.http = http;
     }
 }
 exports.ApiCallInfo = ApiCallInfo;

package/src/http/ApiCallInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiCallInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallInfo.ts"],"names":[],"mappings":";;;AAsDA,MAAa,WAAW;IAIP;IACA;IAEA;IAYA;IAUA;IAGA;IAEA;IAjCb;IACI;oCACgC;IACvB,MAAqB,EACrB,IAAsB;IAC/B,sDAAsD;IAC7C,MAAkB;IAC3B;;;;;;;;;;OAUG;IACM,UAAmB;IAC5B;;;;;;;;OAQG;IACM,WAAoB;IAC7B;yFACqF;IAC5E,YAAqB;IAC9B,4FAA4F;IACnF,aAAsB;QA9BtB,WAAM,GAAN,MAAM,CAAe;QACrB,SAAI,GAAJ,IAAI,CAAkB;QAEtB,WAAM,GAAN,MAAM,CAAY;QAYlB,eAAU,GAAV,UAAU,CAAS;QAUnB,gBAAW,GAAX,WAAW,CAAS;QAGpB,iBAAY,GAAZ,YAAY,CAAS;QAErB,kBAAa,GAAb,aAAa,CAAS;IAChC,CAAC;CACP;AApCD,kCAoCC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * ApiCallInfo - the structured tag stamped into RequestContext around every API call\n * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable\n * `api` object rather than only the req/resp text lines.\n *\n * The node logging backends (winston/bunyan) read this struct out of context via\n * `RequestContext.buildStructuredLogFields()` and emit it AS AN OBJECT under `jsonPayload.api`,\n * which unlocks GCP Cloud Logging filters like:\n * - `jsonPayload.api.method.side=\"client\"`     — every outbound call this process made\n * - `jsonPayload.api.method.side=\"server\"`      — every inbound call it handled\n * - `jsonPayload.api.method.apiClass=\"SaveApi\"` — one logical method, BOTH sides (client + server)\n * - `jsonPayload.api.result=\"failure\"`          — failed exchanges only\n * - `jsonPayload.api.durationMs>1000`           — slow calls, either side\n * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)\n * - `jsonPayload.api.responseCount>100`         — responses containing many logical items\n * - `jsonPayload.api:*`                          — \"API traffic only\" (tracing + the recorder)\n *\n * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —\n * rename a field and the filter renames with it. The identity lives NESTED under `api.method`\n * (`api.method.{side,apiClass,methodName,controllerName}`); `api.type` and `api.result` sit at the top.\n *\n * NOTE: the request `httpMethod`/`path` are NOT here — an inbound request stamps them as the separate\n * top-level logged keys `jsonPayload.httpMethod` / `jsonPayload.requestPath` (see\n * {@link WebpiecesCoreHeaders} + `RequestContextHeaders.fillFromRequest`). Outbound client calls have\n * no inbound path, so they carry only the `api` identity.\n *\n * Per-hop only: the underlying `API_CALL_INFO` ContextKey is NOT transferred over the wire, so a\n * downstream server stamps its own `side:'server'` rather than inheriting the caller's `side:'client'`.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\n/** Which half of the exchange this tag describes: the outgoing 'request' or the returning 'response'. */\n/**\n * Which HALF of one api call a log line describes.\n *\n * Renamed from `ApiType`, which collided with the `@ApiType(...)` CONTRACT decorator and read as if\n * it were about the kind of API rather than the direction of one line. Per\n * `.claude/rules/no-backwards-compat.md` the old spelling is deleted rather than aliased, so a caller\n * on the old name stops compiling and the error names this one.\n */\nexport type ApiCallDirection = 'request' | 'response';\n\n/**\n * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully\n * handled \"you made a mistake\"); 'failure' is a genuine server error. `success` = {@link CallOutcome.EXPECTED} from {@link ClientRegistry.classify}.\n */\nexport type ApiResult = 'success' | 'failure';\n\n/** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */\nexport type { ApiSide } from './ApiMethodInfo';\n\nexport class ApiCallInfo {\n    constructor(\n        /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under\n         *  `jsonPayload.api.method`. */\n        readonly method: ApiMethodInfo,\n        readonly type: ApiCallDirection,\n        /** Response only — undefined on the 'request' tag. */\n        readonly result?: ApiResult,\n        /**\n         * Wall-clock milliseconds the call took. RESPONSE tag only (undefined on 'request') — a\n         * request has no duration yet. Present on BOTH the success and failure paths, so\n         * `jsonPayload.api.durationMs>1000 AND api.result=\"failure\"` finds slow failures.\n         *\n         * There is deliberately no `statusCode` beside this. LogApiCall runs deep in the stack over\n         * in-process calls, pubsub handlers, and cloud-task enqueues — none of which have an HTTP\n         * status — and business logic must not know about HTTP. `result` (see {@link ApiResult}) is\n         * the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by\n         * portable Error TYPE rather than by status code.\n         */\n        readonly durationMs?: number,\n        /**\n         * Bytes of the serialized request DTO. Stamped on BOTH tags: the 'request' tag reports it as\n         * soon as it is known, and the 'response' tag repeats it so one record shows the whole\n         * exchange (`api.requestSize` + `api.responseSize` without a join).\n         *\n         * This is the TOTAL size of the body, measured BEFORE any log chunking — chunking is a\n         * transport concern handled by the GCP backends, and a body split across 3 records still\n         * reports its one true size here.\n         */\n        readonly requestSize?: number,\n        /** Bytes of the serialized response. RESPONSE tag only, and only when the call succeeded —\n         *  a thrown error produced no response body to measure. Total size, pre-chunking. */\n        readonly responseSize?: number,\n        /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */\n        readonly responseCount?: number,\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiCallInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallInfo.ts"],"names":[],"mappings":";;;AAwDA;;;;;;;;GAQG;AACH,MAAa,aAAa;IAGT;IAEA;IAEA;IANb;IACI,iCAAiC;IACxB,MAAc;IACvB,sGAAsG;IAC7F,GAAW;IACpB,gDAAgD;IACvC,MAAc;QAJd,WAAM,GAAN,MAAM,CAAQ;QAEd,QAAG,GAAH,GAAG,CAAQ;QAEX,WAAM,GAAN,MAAM,CAAQ;IACxB,CAAC;IAEJ;;;;OAIG;IACH,8FAA8F;IAC9F,MAAM,CAAC,OAAO,CAAC,GAAW,EAAE,IAA0B;QAClD,MAAM,eAAe,GAAG,GAAG,CAAC,OAAO,CAAC,qCAAqC,EAAE,IAAI,CAAC,CAAC;QACjF,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,OAAO,GAAG,CAAC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,eAAe,CAAC;QAC9D,MAAM,KAAK,GAAG,eAAe;aACxB,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;aAClB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,IAAY,EAAE,EAAE;YAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC;QACzF,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC;IAC3D,CAAC;IAED,8FAA8F;IACtF,MAAM,CAAC,MAAM,CAAC,GAAW;QAC7B,uFAAuF;QACvF,OAAO,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;CACJ;AArCD,sCAqCC;AAED;;;;;GAKG;AACH,MAAa,mBAAmB;IAC5B,KAAK,GAA8B,SAAS,CAAC;CAChD;AAFD,kDAEC;AAED,MAAa,WAAW;IAIP;IACA;IAEA;IAcA;IAUA;IAGA;IAEA;IAOA;IA1Cb;IACI;oCACgC;IACvB,MAAqB,EACrB,IAAsB;IAC/B,sDAAsD;IAC7C,MAAkB;IAC3B;;;;;;;;;;;;OAYG;IACM,UAAmB;IAC5B;;;;;;;;OAQG;IACM,WAAoB;IAC7B;yFACqF;IAC5E,YAAqB;IAC9B,4FAA4F;IACnF,aAAsB;IAC/B;;;;;OAKG;IACM,IAAoB;QAvCpB,WAAM,GAAN,MAAM,CAAe;QACrB,SAAI,GAAJ,IAAI,CAAkB;QAEtB,WAAM,GAAN,MAAM,CAAY;QAclB,eAAU,GAAV,UAAU,CAAS;QAUnB,gBAAW,GAAX,WAAW,CAAS;QAGpB,iBAAY,GAAZ,YAAY,CAAS;QAErB,kBAAa,GAAb,aAAa,CAAS;QAOtB,SAAI,GAAJ,IAAI,CAAgB;IAC9B,CAAC;CACP;AA7CD,kCA6CC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\nimport { MaskSpec } from './LogFieldMask';\n\n/**\n * ApiCallInfo - the structured tag stamped into RequestContext around every API call\n * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable\n * `api` object rather than only the req/resp text lines.\n *\n * The node logging backends (winston/bunyan) read this struct out of context via\n * `RequestContext.buildStructuredLogFields()` and emit it AS AN OBJECT under `jsonPayload.api`,\n * which unlocks GCP Cloud Logging filters like:\n * - `jsonPayload.api.method.side=\"client\"`     — every outbound call this process made\n * - `jsonPayload.api.method.side=\"server\"`      — every inbound call it handled\n * - `jsonPayload.api.method.apiClass=\"SaveApi\"` — one logical method, BOTH sides (client + server)\n * - `jsonPayload.api.result=\"failure\"`          — failed exchanges only\n * - `jsonPayload.api.durationMs>1000`           — slow calls, either side\n * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)\n * - `jsonPayload.api.responseCount>100`         — responses containing many logical items\n * - `jsonPayload.api:*`                          — \"API traffic only\" (tracing + the recorder)\n * - `jsonPayload.api.http.status=404`            — an HTTP client call the vendor answered 404 (#1339)\n *\n * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —\n * rename a field and the filter renames with it. The identity lives NESTED under `api.method`\n * (`api.method.{side,apiClass,methodName,controllerName}`); `api.type` and `api.result` sit at the top.\n *\n * NOTE: the request `httpMethod`/`path` are NOT here — an inbound request stamps them as the separate\n * top-level logged keys `jsonPayload.httpMethod` / `jsonPayload.requestPath` (see\n * {@link WebpiecesCoreHeaders} + `RequestContextHeaders.fillFromRequest`). Outbound client calls have\n * no inbound path, so they carry only the `api` identity.\n *\n * Per-hop only: the underlying `API_CALL_INFO` ContextKey is NOT transferred over the wire, so a\n * downstream server stamps its own `side:'server'` rather than inheriting the caller's `side:'client'`.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\n/** Which half of the exchange this tag describes: the outgoing 'request' or the returning 'response'. */\n/**\n * Which HALF of one api call a log line describes.\n *\n * Renamed from `ApiType`, which collided with the `@ApiType(...)` CONTRACT decorator and read as if\n * it were about the kind of API rather than the direction of one line. Per\n * `.claude/rules/no-backwards-compat.md` the old spelling is deleted rather than aliased, so a caller\n * on the old name stops compiling and the error names this one.\n */\nexport type ApiCallDirection = 'request' | 'response';\n\n/**\n * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully\n * handled \"you made a mistake\"); 'failure' is a genuine server error. `success` = {@link CallOutcome.EXPECTED} from {@link ClientRegistry.classify}.\n */\nexport type ApiResult = 'success' | 'failure';\n\n/** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */\nexport type { ApiSide } from './ApiMethodInfo';\n\n/**\n * The HTTP facts of ONE client call's last transmission — surfaces as `jsonPayload.api.http.*`.\n * Filled ONLY by the HTTP client (node and browser), which is the one layer that has a verb, a url\n * and a status; in-process, pubsub and cloud-task calls leave {@link ApiCallInfo.http} unset. It\n * exists because a vendor's 404 and its 500 were indistinguishable in the logs when only the DTOs\n * were recorded.\n *\n * Never headers or tokens: the url is MASKED ({@link maskUrl}) before it gets here.\n */\nexport class HttpCallFacts {\n    constructor(\n        /** The HTTP verb, e.g. `GET`. */\n        readonly method: string,\n        /** The final absolute url, masked: no userinfo, and `@MaskLog` field names' query values redacted. */\n        readonly url: string,\n        /** The status of the last response received. */\n        readonly status: number,\n    ) {}\n\n    /**\n     * The url as it may be logged: any `user:password@` userinfo is dropped, and the value of every\n     * query key the endpoint's `@MaskLog` names is replaced with `*****` (a `?token=` the DTO mask\n     * already hides must not reappear in the url).\n     */\n    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds\n    static maskUrl(url: string, mask: MaskSpec | undefined): string {\n        const withoutUserInfo = url.replace(/^([a-z][a-z0-9+.-]*:\\/\\/)[^/@?#]*@/i, '$1');\n        const queryAt = withoutUserInfo.indexOf('?');\n        if (queryAt < 0 || mask === undefined) return withoutUserInfo;\n        const query = withoutUserInfo\n            .slice(queryAt + 1)\n            .split('&')\n            .map((pair: string) => {\n                const equals = pair.indexOf('=');\n                const key = equals < 0 ? pair : pair.slice(0, equals);\n                return mask.modeFor(HttpCallFacts.decode(key)) === undefined ? pair : `${key}=*****`;\n            })\n            .join('&');\n        return `${withoutUserInfo.slice(0, queryAt)}?${query}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds\n    private static decode(key: string): string {\n        // A malformed escape is logged as written; it can never be a masked field name anyway.\n        return /%(?![0-9a-f]{2})/i.test(key) ? key : decodeURIComponent(key);\n    }\n}\n\n/**\n * The per-call slot the HTTP client fills with {@link HttpCallFacts} as each response arrives, and\n * {@link LogApiCallImpl} reads when it stamps the response tag. A holder rather than a return value\n * because the facts are known DEEP in the transport while the tag is written at the top of the call;\n * the last transmission (after redirects, a 401 refresh or a retry) wins.\n */\nexport class HttpCallFactsHolder {\n    facts: HttpCallFacts | undefined = undefined;\n}\n\nexport class ApiCallInfo {\n    constructor(\n        /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under\n         *  `jsonPayload.api.method`. */\n        readonly method: ApiMethodInfo,\n        readonly type: ApiCallDirection,\n        /** Response only — undefined on the 'request' tag. */\n        readonly result?: ApiResult,\n        /**\n         * Wall-clock milliseconds the call took. RESPONSE tag only (undefined on 'request') — a\n         * request has no duration yet. Present on BOTH the success and failure paths, so\n         * `jsonPayload.api.durationMs>1000 AND api.result=\"failure\"` finds slow failures.\n         *\n         * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the\n         * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have\n         * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})\n         * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by\n         * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP\n         * client's status lives in the optional, nested {@link http} — present only where there IS an\n         * HTTP exchange, so nothing transport-neutral ever reads it.\n         */\n        readonly durationMs?: number,\n        /**\n         * Bytes of the serialized request DTO. Stamped on BOTH tags: the 'request' tag reports it as\n         * soon as it is known, and the 'response' tag repeats it so one record shows the whole\n         * exchange (`api.requestSize` + `api.responseSize` without a join).\n         *\n         * This is the TOTAL size of the body, measured BEFORE any log chunking — chunking is a\n         * transport concern handled by the GCP backends, and a body split across 3 records still\n         * reports its one true size here.\n         */\n        readonly requestSize?: number,\n        /** Bytes of the serialized response. RESPONSE tag only, and only when the call succeeded —\n         *  a thrown error produced no response body to measure. Total size, pre-chunking. */\n        readonly responseSize?: number,\n        /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */\n        readonly responseCount?: number,\n        /**\n         * The HTTP verb, masked url and status of the call's last transmission — `jsonPayload.api.http.*`.\n         * RESPONSE tag only, and only for a call made by the HTTP client (success AND failure, so\n         * `api.result=\"failure\" AND api.http.status=429` finds a vendor throttling us). Unset for\n         * in-process, pubsub and cloud-task calls. See {@link HttpCallFacts}.\n         */\n        readonly http?: HttpCallFacts,\n    ) {}\n}\n"]}

package/src/http/ContextMgr.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextMgr = void 0;
+const ApiError_1 = require("../errors/ApiError");
 const HeaderRegistry_1 = require("./HeaderRegistry");
 const ServiceInfo_1 = require("./ServiceInfo");
 const WebpiecesCoreHeaders_1 = require("./WebpiecesCoreHeaders");
@@ -59,7 +60,9 @@ class ContextMgr {
      */
     buildOutboundHeaders(destination) {
         const outbound = new Map();
-        for (const key of HeaderRegistry_1.HeaderRegistry.get().getTransferredKeys()) {
+        // An EXTERNAL_OUTBOUND destination lists EXACTLY what it sends, and each listed key is required.
+        const listed = destination.listedKeys();
+        for (const key of listed ?? HeaderRegistry_1.HeaderRegistry.get().getTransferredKeys()) {
             if (!destination.allows(key)) {
                 continue;
             }
@@ -67,6 +70,13 @@ class ContextMgr {
             if (value !== undefined && value !== null && value !== '') {
                 outbound.set(key.httpHeader, value);
             }
+            else if (listed !== undefined) {
+                throw new ApiError_1.ApiImplementationError(`Context key '${key.name}' (header ${key.httpHeader}) is listed in @ExternalContextKeys for this ` +
+                    `outbound call but has no value in the context store. Set it before calling — nothing was sent.`);
+            }
+        }
+        if (!destination.allows(WebpiecesCoreHeaders_1.WebpiecesCoreHeaders.CLIENT_VERSION)) {
+            return outbound;
         }
         // CLIENT_VERSION: a browser ORIGINATES a call, so it sends its OWN app build version (from
         // ServiceInfo) and the server logs which client build called it — same rule as the server-side
@@ -103,7 +113,7 @@ class ContextMgr {
             if (value === null || value === '') {
                 continue;
             }
-            if (!destination.allows(key) || key.isTrusted()) {
+            if (!destination.believesResponse(key) || key.isTrusted()) {
                 // DROPPED: a browser proves nothing, so it may never hold a trusted value.
                 continue;
             }

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,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', ClientRole.SERVER));\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 OIDC (`oidcSameProject()` /\n     * `oidcSvcs(...)`) or `sharedSecret(...)` contract at all, so every browser destination is `jwt()` 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 `jwt()` 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"]}
+{"version":3,"file":"ContextMgr.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextMgr.ts"],"names":[],"mappings":";;;AACA,iDAA4D;AAG5D,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,iGAAiG;QACjG,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,MAAM,IAAI,+BAAc,CAAC,GAAG,EAAE,CAAC,kBAAkB,EAAE,EAAE,CAAC;YACpE,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;iBAAM,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,iCAAsB,CAC5B,gBAAgB,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,UAAU,+CAA+C;oBAC9F,gGAAgG,CACvG,CAAC;YACN,CAAC;QACL,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,2CAAoB,CAAC,cAAc,CAAC,EAAE,CAAC;YAC3D,OAAO,QAAQ,CAAC;QACpB,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,gBAAgB,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;gBACxD,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;AA/FD,gCA+FC","sourcesContent":["import { ContextKey } from '../ContextKey';\nimport { ApiImplementationError } from '../errors/ApiError';\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', ClientRole.SERVER));\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 OIDC (`oidcSameProject()` /\n     * `oidcSvcs(...)`) or `sharedSecret(...)` contract at all, so every browser destination is `jwt()` 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        // An EXTERNAL_OUTBOUND destination lists EXACTLY what it sends, and each listed key is required.\n        const listed = destination.listedKeys();\n        for (const key of listed ?? 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            } else if (listed !== undefined) {\n                throw new ApiImplementationError(\n                    `Context key '${key.name}' (header ${key.httpHeader}) is listed in @ExternalContextKeys for this ` +\n                        `outbound call but has no value in the context store. Set it before calling — nothing was sent.`,\n                );\n            }\n        }\n        if (!destination.allows(WebpiecesCoreHeaders.CLIENT_VERSION)) {\n            return outbound;\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 `jwt()` 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.believesResponse(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/DeletedAuthCompileAssertions.js

@@ -14,8 +14,10 @@ class DeletedAuthCompileAssertions {
         void CoreUtil.oidc;
         // @ts-expect-error use WpAuth([sharedSecret(...)]) and WpAuthorization
         void CoreUtil.WpAuthSharedSecret;
-        // @ts-expect-error use WpAuth([webhook(...)]) and WpAuthorization
+        // @ts-expect-error use WpAuth([vendorAuth(...)]) and WpAuthorization
         void CoreUtil.WpAuthWebhook;
+        // @ts-expect-error webhook(name) is renamed vendorAuth(name): one VendorAuthHook mints, refreshes and verifies
+        void CoreUtil.webhook;
         // @ts-expect-error use WpAuth([apiKey(...)]) and WpAuthorization
         void CoreUtil.WpAuthApiKey;
         // @ts-expect-error use separate WpLocalOnly, authentication and authorization

package/src/http/DeletedAuthCompileAssertions.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeletedAuthCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/DeletedAuthCompileAssertions.ts"],"names":[],"mappings":";;;;AAAA,2DAAqC;AAErC,4FAA4F;AAC5F,MAAa,4BAA4B;IACrC,cAAc;QACV,2DAA2D;QAC3D,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,oGAAoG;QACpG,KAAK,QAAQ,CAAC,UAAU,CAAC;QACzB,4HAA4H;QAC5H,KAAK,QAAQ,CAAC,IAAI,CAAC;QACnB,uEAAuE;QACvE,KAAK,QAAQ,CAAC,kBAAkB,CAAC;QACjC,kEAAkE;QAClE,KAAK,QAAQ,CAAC,aAAa,CAAC;QAC5B,iEAAiE;QACjE,KAAK,QAAQ,CAAC,YAAY,CAAC;QAC3B,8EAA8E;QAC9E,KAAK,QAAQ,CAAC,eAAe,CAAC;QAC9B,iEAAiE;QACjE,KAAK,QAAQ,CAAC,YAAY,CAAC;QAC3B,oEAAoE;QACpE,KAAK,QAAQ,CAAC,WAAW,CAAC;QAC1B,kEAAkE;QAClE,KAAK,QAAQ,CAAC,aAAa,CAAC;IAChC,CAAC;CACJ;AAvBD,oEAuBC","sourcesContent":["import * as CoreUtil from '../index';\n\n/** Each removed spelling has its own assertion so one missing export cannot mask a shim. */\nexport class DeletedAuthCompileAssertions {\n    removedExports(): void {\n        // @ts-expect-error use WpAuth([jwt()]) and WpAuthorization\n        void CoreUtil.WpAuthJwt;\n        // @ts-expect-error use WpAuth([oidcSameProject()]) or WpAuth([oidcSvcs([...])]) and WpAuthorization\n        void CoreUtil.WpAuthOidc;\n        // @ts-expect-error oidc(...) is removed: oidcSameProject() for this GCP project, oidcSvcs([...]) for named service accounts\n        void CoreUtil.oidc;\n        // @ts-expect-error use WpAuth([sharedSecret(...)]) and WpAuthorization\n        void CoreUtil.WpAuthSharedSecret;\n        // @ts-expect-error use WpAuth([webhook(...)]) and WpAuthorization\n        void CoreUtil.WpAuthWebhook;\n        // @ts-expect-error use WpAuth([apiKey(...)]) and WpAuthorization\n        void CoreUtil.WpAuthApiKey;\n        // @ts-expect-error use separate WpLocalOnly, authentication and authorization\n        void CoreUtil.WpAuthLocalOnly;\n        // @ts-expect-error MCP shares receiving endpoint WpAuthorization\n        void CoreUtil.WpMcpAuthJwt;\n        // @ts-expect-error unresolved credentials are read with getAuthMeta\n        void CoreUtil.getAuthMode;\n        // @ts-expect-error roles belong to common operation authorization\n        void CoreUtil.rolesRequired;\n    }\n}\n"]}
+{"version":3,"file":"DeletedAuthCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/DeletedAuthCompileAssertions.ts"],"names":[],"mappings":";;;;AAAA,2DAAqC;AAErC,4FAA4F;AAC5F,MAAa,4BAA4B;IACrC,cAAc;QACV,2DAA2D;QAC3D,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,oGAAoG;QACpG,KAAK,QAAQ,CAAC,UAAU,CAAC;QACzB,4HAA4H;QAC5H,KAAK,QAAQ,CAAC,IAAI,CAAC;QACnB,uEAAuE;QACvE,KAAK,QAAQ,CAAC,kBAAkB,CAAC;QACjC,qEAAqE;QACrE,KAAK,QAAQ,CAAC,aAAa,CAAC;QAC5B,+GAA+G;QAC/G,KAAK,QAAQ,CAAC,OAAO,CAAC;QACtB,iEAAiE;QACjE,KAAK,QAAQ,CAAC,YAAY,CAAC;QAC3B,8EAA8E;QAC9E,KAAK,QAAQ,CAAC,eAAe,CAAC;QAC9B,iEAAiE;QACjE,KAAK,QAAQ,CAAC,YAAY,CAAC;QAC3B,oEAAoE;QACpE,KAAK,QAAQ,CAAC,WAAW,CAAC;QAC1B,kEAAkE;QAClE,KAAK,QAAQ,CAAC,aAAa,CAAC;IAChC,CAAC;CACJ;AAzBD,oEAyBC","sourcesContent":["import * as CoreUtil from '../index';\n\n/** Each removed spelling has its own assertion so one missing export cannot mask a shim. */\nexport class DeletedAuthCompileAssertions {\n    removedExports(): void {\n        // @ts-expect-error use WpAuth([jwt()]) and WpAuthorization\n        void CoreUtil.WpAuthJwt;\n        // @ts-expect-error use WpAuth([oidcSameProject()]) or WpAuth([oidcSvcs([...])]) and WpAuthorization\n        void CoreUtil.WpAuthOidc;\n        // @ts-expect-error oidc(...) is removed: oidcSameProject() for this GCP project, oidcSvcs([...]) for named service accounts\n        void CoreUtil.oidc;\n        // @ts-expect-error use WpAuth([sharedSecret(...)]) and WpAuthorization\n        void CoreUtil.WpAuthSharedSecret;\n        // @ts-expect-error use WpAuth([vendorAuth(...)]) and WpAuthorization\n        void CoreUtil.WpAuthWebhook;\n        // @ts-expect-error webhook(name) is renamed vendorAuth(name): one VendorAuthHook mints, refreshes and verifies\n        void CoreUtil.webhook;\n        // @ts-expect-error use WpAuth([apiKey(...)]) and WpAuthorization\n        void CoreUtil.WpAuthApiKey;\n        // @ts-expect-error use separate WpLocalOnly, authentication and authorization\n        void CoreUtil.WpAuthLocalOnly;\n        // @ts-expect-error MCP shares receiving endpoint WpAuthorization\n        void CoreUtil.WpMcpAuthJwt;\n        // @ts-expect-error unresolved credentials are read with getAuthMeta\n        void CoreUtil.getAuthMode;\n        // @ts-expect-error roles belong to common operation authorization\n        void CoreUtil.rolesRequired;\n    }\n}\n"]}

package/src/http/DestinationTrust.d.ts

@@ -1,5 +1,6 @@
 import { AnyContextKey } from '../ContextKey';
 import { AuthMode } from './auth-mode';
+import { RouteMetadata } from './RouteMetadata';
 /**
  * DestinationTrust - the OUTBOUND half of the trust model: may a TRUSTED context key
  * ({@link ContextKey.trusted}) ride to the endpoint we are about to call?
@@ -32,6 +33,12 @@ import { AuthMode } from './auth-mode';
  */
 export declare class DestinationTrust {
     private readonly verifiesCaller;
+    /**
+     * Set ONLY for an `EXTERNAL_OUTBOUND` destination: the `@ExternalContextKeys` list, which is
+     * then the WHOLE of what may be sent. Undefined for every destination in this repo, whose wire
+     * is governed by {@link forAuthMode} exactly as before.
+     */
+    private readonly externalKeys;
     /**
      * The destination authenticates its CALLER (oidcSameProject() / oidcSvcs(...) / sharedSecret(...)), so it is entitled to
      * believe context WE vouch for — this is the service-to-service identity propagation that trusted
@@ -39,12 +46,26 @@ export declare class DestinationTrust {
      */
     private static readonly VERIFIES_CALLER;
     /**
-     * The destination cannot tell us from a browser with curl (jwt() / @WpAuthPublic / webhook(...) /
+     * The destination cannot tell us from a browser with curl (jwt() / @WpAuthPublic / vendorAuth(...) /
      * apiKey(...) / @WpLocalOnly / an endpoint with no declared mode), so trusted keys are omitted.
      * Untrusted keys still travel.
      */
     private static readonly CANNOT_VERIFY_CALLER;
     private constructor();
+    /**
+     * The destination of ONE route. An `EXTERNAL_OUTBOUND` route (an outside system's API) gets a
+     * destination that sends ONLY its `@ExternalContextKeys` and believes NO response header: a vendor
+     * is somebody else's process, so our `x-request-id`, `x-webpieces-*` and app keys stay home unless
+     * the contract lists them, and nothing it answers may write into our context. Every other route is
+     * {@link forAuthMode}, unchanged — so the wire to our own servers is identical.
+     */
+    static forRoute(route: RouteMetadata): DestinationTrust;
+    /**
+     * The keys an `EXTERNAL_OUTBOUND` destination sends — every one is REQUIRED, so a builder throws
+     * before any I/O when one has no value. Undefined for every other destination, whose builder
+     * iterates the registry's transferred keys and filters them with {@link allows}.
+     */
+    listedKeys(): readonly AnyContextKey[] | undefined;
     /**
      * The ONLY way to obtain one: state the destination endpoint's auth mode. `undefined` (an
      * endpoint that declared no mode) is treated as un-verifying, i.e. the SAFE answer — an absent
@@ -65,9 +86,17 @@ export declare class DestinationTrust {
      *   service in our own trust domain, while a `@WpAuthPublic` / `jwt()` / 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.
+     * For every destination in this repo the two directions are one question, so the response side
+     * ({@link believesResponse}) delegates here; only an `EXTERNAL_OUTBOUND` destination answers them
+     * differently (it sends listed keys and believes none).
      */
     allows(key: AnyContextKey): boolean;
+    /**
+     * May a key that came BACK on this destination's response be merged into our context? Exactly
+     * {@link allows} for a destination in this repo — and NOTHING from an `EXTERNAL_OUTBOUND` one,
+     * whose response headers are an outside system's, not a peer's. A separate method because for
+     * that destination the two directions genuinely differ: a key we LIST to send (`x-request-id`)
+     * is not thereby a key we let the vendor write back.
+     */
+    believesResponse(key: AnyContextKey): boolean;
 }

package/src/http/DestinationTrust.js

@@ -33,20 +33,50 @@ exports.DestinationTrust = void 0;
  */
 class DestinationTrust {
     verifiesCaller;
+    externalKeys;
     /**
      * The destination authenticates its CALLER (oidcSameProject() / oidcSvcs(...) / sharedSecret(...)), so it is entitled to
      * believe context WE vouch for — this is the service-to-service identity propagation that trusted
      * keys keep an `httpHeader` for.
      */
-    static VERIFIES_CALLER = new DestinationTrust(true);
+    static VERIFIES_CALLER = new DestinationTrust(true, undefined);
     /**
-     * The destination cannot tell us from a browser with curl (jwt() / @WpAuthPublic / webhook(...) /
+     * The destination cannot tell us from a browser with curl (jwt() / @WpAuthPublic / vendorAuth(...) /
      * apiKey(...) / @WpLocalOnly / an endpoint with no declared mode), so trusted keys are omitted.
      * Untrusted keys still travel.
      */
-    static CANNOT_VERIFY_CALLER = new DestinationTrust(false);
-    constructor(verifiesCaller) {
+    static CANNOT_VERIFY_CALLER = new DestinationTrust(false, undefined);
+    constructor(verifiesCaller, 
+    /**
+     * Set ONLY for an `EXTERNAL_OUTBOUND` destination: the `@ExternalContextKeys` list, which is
+     * then the WHOLE of what may be sent. Undefined for every destination in this repo, whose wire
+     * is governed by {@link forAuthMode} exactly as before.
+     */
+    externalKeys) {
         this.verifiesCaller = verifiesCaller;
+        this.externalKeys = externalKeys;
+    }
+    /**
+     * The destination of ONE route. An `EXTERNAL_OUTBOUND` route (an outside system's API) gets a
+     * destination that sends ONLY its `@ExternalContextKeys` and believes NO response header: a vendor
+     * is somebody else's process, so our `x-request-id`, `x-webpieces-*` and app keys stay home unless
+     * the contract lists them, and nothing it answers may write into our context. Every other route is
+     * {@link forAuthMode}, unchanged — so the wire to our own servers is identical.
+     */
+    // webpieces-disable no-function-outside-class -- static factory beside forAuthMode, for the same reason
+    static forRoute(route) {
+        if (route.externalOutbound) {
+            return new DestinationTrust(false, route.externalContextKeys);
+        }
+        return DestinationTrust.forAuthMode(route.authMeta?.methods[0]);
+    }
+    /**
+     * The keys an `EXTERNAL_OUTBOUND` destination sends — every one is REQUIRED, so a builder throws
+     * before any I/O when one has no value. Undefined for every other destination, whose builder
+     * iterates the registry's transferred keys and filters them with {@link allows}.
+     */
+    listedKeys() {
+        return this.externalKeys;
     }
     /**
      * The ONLY way to obtain one: state the destination endpoint's auth mode. `undefined` (an
@@ -64,12 +94,11 @@ class DestinationTrust {
                 return DestinationTrust.VERIFIES_CALLER;
             case 'jwt':
             case 'public':
-            // webhook(...) authenticates an OUTSIDE VENDOR, which is not the same thing as
+            // vendorAuth(...) authenticates an OUTSIDE VENDOR, which is not the same thing as
             // authenticating a peer in this repo. The vendor knows nothing of webpieces context
             // headers and would never send one, so there is no identity to propagate in either
-            // direction — and a webpieces client cannot call such an endpoint anyway (it cannot mint
-            // the vendor's signature). Trusted keys stay home.
-            case 'webhook':
+            // direction. Trusted keys stay home.
+            case 'vendorAuth':
             // apiKey(...) authenticates a CUSTOMER, not a peer service. The holder of the key is
             // another company's codebase, so nothing it forwards may be believed, and no webpieces
             // client can call it anyway (the framework extracts no api-key header — the app's hook
@@ -97,13 +126,27 @@ class DestinationTrust {
      *   service in our own trust domain, while a `@WpAuthPublic` / `jwt()` / 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.
+     * For every destination in this repo the two directions are one question, so the response side
+     * ({@link believesResponse}) delegates here; only an `EXTERNAL_OUTBOUND` destination answers them
+     * differently (it sends listed keys and believes none).
      */
     allows(key) {
+        if (this.externalKeys !== undefined)
+            return this.externalKeys.includes(key);
         return this.verifiesCaller || !key.isTrusted();
     }
+    /**
+     * May a key that came BACK on this destination's response be merged into our context? Exactly
+     * {@link allows} for a destination in this repo — and NOTHING from an `EXTERNAL_OUTBOUND` one,
+     * whose response headers are an outside system's, not a peer's. A separate method because for
+     * that destination the two directions genuinely differ: a key we LIST to send (`x-request-id`)
+     * is not thereby a key we let the vendor write back.
+     */
+    believesResponse(key) {
+        if (this.externalKeys !== undefined)
+            return false;
+        return this.allows(key);
+    }
 }
 exports.DestinationTrust = DestinationTrust;
 //# sourceMappingURL=DestinationTrust.js.map