@webpieces/core-util 0.4.598 → 0.4.600

package/package.json

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

package/src/ContextKey.d.ts

@@ -8,30 +8,85 @@
  * TestCaseRecorder) — is a `ContextKey`.
  *
  * The fields are named for what they DO (flipped from the old model):
- * - `name`       ALWAYS set. The context storage key, the log/MDC key, and the
- *                recorder name. e.g. 'requestId', 'tenantId', 'authorization'.
- * - `httpHeader` OPTIONAL. When set, this key is transferred over the wire under
- *                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).
- * - `isSecured`  When true, the value is masked (partially) in logs.
- * - `isLogged`   Defaults to true. When false, the value is NEVER logged (used for
- *                object-valued/internal keys like the recorder or method-meta that
- *                must not be serialized into log lines).
+ * - `name`        ALWAYS set. The context storage key, the log/MDC key, and the
+ *                 recorder name. e.g. 'requestId', 'tenantId', 'authorization'.
+ * - `httpHeader`  OPTIONAL. When set, this key is transferred over the wire under
+ *                 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).
+ * - `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
+ *                 trusted AND fully logged; a bearer token is untrusted AND masked.
+ *                 (Formerly `isSecured`, renamed because sitting next to `trust` the
+ *                 old name read as "this value is secure", which it never meant.)
+ * - `isLogged`    Defaults to true. When false, the value is NEVER logged (used for
+ *                 object-valued/internal keys like the recorder or method-meta that
+ *                 must not be serialized into log lines).
+ *
+ * ## TRUST — the whole point of this class
+ *
+ * A context value is either something the framework PROVED (`trusted`) or something a
+ * caller merely ASSERTED (`untrusted`). That distinction is invisible in a `Map<string,
+ * string>`, so code — human- or AI-written — routinely reads a spoofable header as if it
+ * were an authenticated fact. `userId` is the canonical example: it is a verified JWT
+ * claim on one route and an attacker-supplied `x-user-id` on the next, and nothing in the
+ * old API told them apart.
+ *
+ * So trust is declared ON THE KEY, at the single place the key is defined, and it is
+ * enforced at BOTH ends:
+ *
+ *   ContextKey.trusted<string>('userId', 'jwt claim `sub`, stamped by AuthFilter', 'x-user-id')
+ *   ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid')
+ *
+ * `grep -rn "ContextKey.trusted"` therefore enumerates every high-assurance field in the
+ * codebase, each with its `provenance` string on the same line saying WHY it is trusted.
+ * That is the AI-facing payoff: the answer is one grep, not an audit.
+ *
+ * The constructor is PRIVATE — you cannot make a key without picking a branch, and there
+ * is no default. A default would make the permissive branch the shortest thing to type,
+ * which is exactly the "widening that is an ABSENCE rather than a token" that CLAUDE.md
+ * rejects. `provenance` is a REQUIRED positional argument on the trusted factory only, so
+ * "trusted with no stated reason" cannot be written down.
+ *
+ * ## What makes the `trusted` label HONEST at runtime
+ *
+ * The label would be a lie if anything could write a trusted key from an unverified
+ * source. Three enforced facts prevent that:
+ *
+ * 1. WRITES are typed: only `RequestContext.putTrusted(key, value)` accepts a trusted key,
+ *    and it is a distinct, greppable verb an app has to type on purpose.
+ * 2. INBOUND wire values for trusted keys never enter the context directly.
+ *    `RequestContextHeaders.fillFromRequest` stashes them as PENDING, and `AuthFilter`
+ *    admits them only after it knows who the caller is (see {@link PendingWireTrust}).
+ * 3. READS are typed: `getTrusted(key)` does not compile for an untrusted key, and
+ *    `getUntrusted(key)` does not compile for a trusted one. Picking a verb is
+ *    unavoidable, so a reader always knows which kind of value it is holding.
+ *
+ * Trusted keys DO keep their `httpHeader` — service-to-service propagation of a verified
+ * userId is a first-class requirement, not a hole. It is safe because rule 2 gates it on
+ * the endpoint's own auth mode: a route that verified WHO called it (`@AuthOidc`,
+ * `@AuthSharedSecret`) accepts the caller's trusted headers; a route reachable by a
+ * browser (`@AuthJwt`, public) does not.
  *
  * Per CLAUDE.md: data-only structures are classes, not interfaces.
  *
  * The type parameter `V` is the TYPE OF THE VALUE stored under this key — `string` for the wire/log
  * keys (requestId, tenantId, ...), `ApiCallInfo` for the structured api tag, `TestCaseRecorder` for
- * the recorder. It is REQUIRED (no default): every key must state what it holds, so a legacy
- * `new ContextKey('x')` fails to compile until it declares `new ContextKey<string>('x')` — the
- * type system does the migration for you. A heterogeneous store CANNOT be a `Record<string, string>`
- * — the recorder and the api payload are not strings — so instead each KEY carries its own value
- * type, and `RequestContext.getHeader/putHeader` INFER it from the key. That keeps the backing Map
- * honestly type-erased while the public surface stays fully typed: a caller never asserts a value
- * type, the key already declares it. A genuinely mixed collection of keys is spelled explicitly as
- * `AnyContextKey[]`, so "I mean a mixed bag" is a visible, deliberate statement, never a default.
+ * the recorder. It is REQUIRED (no default): every key must state what it holds. A heterogeneous
+ * store CANNOT be a `Record<string, string>` — the recorder and the api payload are not strings — so
+ * instead each KEY carries its own value type, and the typed accessors INFER it from the key. That
+ * keeps the backing Map honestly type-erased while the public surface stays fully typed: a caller
+ * never asserts a value type, the key already declares it. A genuinely mixed collection of keys is
+ * spelled explicitly as `AnyContextKey[]`, so "I mean a mixed bag" is a visible, deliberate
+ * statement, never a default.
+ *
+ * The type parameter `T` is the TRUST LEVEL, carried as a phantom type so the accessor verbs can
+ * reject the wrong kind of key at COMPILE time rather than throwing at runtime (CLAUDE.md treats a
+ * runtime throw standing in for an expressible type as a defect).
  */
+/** The two kinds of context value. See the {@link ContextKey} class doc. */
+export type Trust = 'trusted' | 'untrusted';
 /**
  * A ContextKey whose value type is intentionally UNCONSTRAINED — a "key of any value type". Use this
  * (never a bare `ContextKey`, which no longer compiles) for genuinely mixed-bag collections and
@@ -39,16 +94,36 @@
  * reader that takes whatever key it is handed. Naming the mixed case makes "I mean any key" a visible,
  * deliberate statement, and confines the one sanctioned `unknown` to this single alias instead of
  * scattering `ContextKey<unknown>` — and its disable comment — across the codebase.
+ *
+ * NOTE this is mixed in TRUST as well as in value type, so it is READ-ONLY territory: `getAny(key)`
+ * takes one, but no WRITE verb does. A write must name the trust level, which is what keeps the
+ * `trusted` label honest.
  */
 export type AnyContextKey = ContextKey<unknown>;
-export declare class ContextKey<V> {
+/**
+ * A trusted key of any value type — what {@link ContextTuple} carries, and what the trusted write
+ * verb accepts when the value type is not statically known.
+ */
+export type AnyTrustedContextKey = ContextKey<unknown, 'trusted'>;
+/**
+ * An untrusted key of any value type — what the {@link ApiCallContext} seam stamps, so that seam
+ * cannot be used as a side door to forge a trusted value.
+ */
+export type AnyUntrustedContextKey = ContextKey<unknown, 'untrusted'>;
+export declare class ContextKey<V, T extends Trust = Trust> {
     /**
      * Phantom marker carrying the value type {@link V}. It has no runtime existence (`declare`, never
-     * assigned) — it exists ONLY so `getHeader(key)` returns `V` and `putHeader(key, value)` checks
-     * `value` against `V`, both inferred straight from the key. Optional, so `ContextKey<A>` stays
-     * assignable to `AnyContextKey` (i.e. `ContextKey<unknown>`) — arrays of mixed keys keep working.
+     * assigned) — it exists ONLY so the read verbs return `V` and the write verbs check `value`
+     * against `V`, both inferred straight from the key. Optional, so `ContextKey<A>` stays assignable
+     * to `AnyContextKey` (i.e. `ContextKey<unknown>`) — arrays of mixed keys keep working.
      */
     readonly __valueType?: V;
+    /**
+     * Phantom marker carrying the trust level {@link T} — the reason `getTrusted(SOME_UNTRUSTED_KEY)`
+     * is a COMPILE error and not a runtime throw. Like `__valueType` it never exists at runtime; the
+     * runtime answer is the {@link trust} field below, which the fill/reconcile path reads.
+     */
+    readonly __trust?: T;
     /** Context storage key + log/MDC key + recorder name. Always set. */
     readonly name: string;
     /**
@@ -56,19 +131,58 @@ export declare class ContextKey<V> {
      * 'x-request-id'). Undefined = context-only, never transferred.
      */
     readonly httpHeader?: string;
-    /** Mask this value (partially) in logs. */
-    readonly isSecured: boolean;
+    /** The runtime twin of the phantom {@link __trust}. See the class doc. */
+    readonly trust: Trust;
+    /**
+     * WHY this key is trusted, in prose — 'jwt claim `sub`, stamped by AuthFilter', or
+     * 'whatsapp webhook phone number -> user lookup'. Required on a trusted key, absent on an
+     * untrusted one. It exists so that grepping the trusted keys also tells you what proves each
+     * one, without opening another file.
+     */
+    readonly provenance?: string;
+    /** Mask this value (partially) in logs. Log redaction only — unrelated to {@link trust}. */
+    readonly maskInLogs: boolean;
     /** Whether this key is logged at all. Default true; false = never logged. */
     readonly isLogged: boolean;
-    constructor(name: string, httpHeader?: string, isSecured?: boolean, isLogged?: boolean);
+    /**
+     * PRIVATE — use {@link trusted} or {@link untrusted}. There is deliberately no way to build a key
+     * without stating its trust level: a defaulted trust argument would make the permissive branch
+     * the shortest thing to type and impossible to grep.
+     */
+    private constructor();
+    /**
+     * A key whose value the framework PROVED — a verified JWT claim, or a fact an app derived from a
+     * verified credential (a Twilio/WhatsApp webhook's signed phone number looked up to a userId).
+     *
+     * Only `RequestContext.putTrusted` can write one, only `RequestContext.getTrusted` can read one,
+     * and an inbound wire value for one is held PENDING until `AuthFilter` knows who the caller is.
+     *
+     * @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'>;
+    /**
+     * 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
+     * an input to an authorization decision.
+     *
+     * 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'>;
     /** True when this key is transferred over HTTP (has an httpHeader). */
     isTransferred(): boolean;
+    /**
+     * True for a key built by {@link trusted}. The RUNTIME check used by the inbound fill and the
+     * AuthFilter reconciliation; ordinary application code should never need it, because the typed
+     * verbs already made the decision at compile time.
+     */
+    isTrusted(): boolean;
     /**
      * The value as it should appear in a log line: returned as-is for a normal
-     * key, partially masked when this key is secured. Masking is length-based:
+     * key, partially masked when this key sets `maskInLogs`. Masking is length-based:
      * - Length > 15: first 3 + "..." + last 3
      * - Length 8-15: first 2 + "..."
      * - Length < 8: "<secure key too short to log>"
      */
-    maskIfSecured(value: string): string;
+    maskForLogs(value: string): string;
 }

package/src/ContextKey.js

@@ -1,4 +1,91 @@
 "use strict";
+/**
+ * ContextKey - a single key that travels in the request's "magic context"
+ * (RequestContext on the server, MutableContextStore in the browser).
+ *
+ * This ONE class replaces the old split of `Header` (interface) + `PlatformHeader`
+ * (class) + `ContextKey` (class). Every context value — whether it rides over HTTP
+ * (request-id, tenant, authorization) or stays in-process (method-meta, the
+ * TestCaseRecorder) — is a `ContextKey`.
+ *
+ * The fields are named for what they DO (flipped from the old model):
+ * - `name`        ALWAYS set. The context storage key, the log/MDC key, and the
+ *                 recorder name. e.g. 'requestId', 'tenantId', 'authorization'.
+ * - `httpHeader`  OPTIONAL. When set, this key is transferred over the wire under
+ *                 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).
+ * - `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
+ *                 trusted AND fully logged; a bearer token is untrusted AND masked.
+ *                 (Formerly `isSecured`, renamed because sitting next to `trust` the
+ *                 old name read as "this value is secure", which it never meant.)
+ * - `isLogged`    Defaults to true. When false, the value is NEVER logged (used for
+ *                 object-valued/internal keys like the recorder or method-meta that
+ *                 must not be serialized into log lines).
+ *
+ * ## TRUST — the whole point of this class
+ *
+ * A context value is either something the framework PROVED (`trusted`) or something a
+ * caller merely ASSERTED (`untrusted`). That distinction is invisible in a `Map<string,
+ * string>`, so code — human- or AI-written — routinely reads a spoofable header as if it
+ * were an authenticated fact. `userId` is the canonical example: it is a verified JWT
+ * claim on one route and an attacker-supplied `x-user-id` on the next, and nothing in the
+ * old API told them apart.
+ *
+ * So trust is declared ON THE KEY, at the single place the key is defined, and it is
+ * enforced at BOTH ends:
+ *
+ *   ContextKey.trusted<string>('userId', 'jwt claim `sub`, stamped by AuthFilter', 'x-user-id')
+ *   ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid')
+ *
+ * `grep -rn "ContextKey.trusted"` therefore enumerates every high-assurance field in the
+ * codebase, each with its `provenance` string on the same line saying WHY it is trusted.
+ * That is the AI-facing payoff: the answer is one grep, not an audit.
+ *
+ * The constructor is PRIVATE — you cannot make a key without picking a branch, and there
+ * is no default. A default would make the permissive branch the shortest thing to type,
+ * which is exactly the "widening that is an ABSENCE rather than a token" that CLAUDE.md
+ * rejects. `provenance` is a REQUIRED positional argument on the trusted factory only, so
+ * "trusted with no stated reason" cannot be written down.
+ *
+ * ## What makes the `trusted` label HONEST at runtime
+ *
+ * The label would be a lie if anything could write a trusted key from an unverified
+ * source. Three enforced facts prevent that:
+ *
+ * 1. WRITES are typed: only `RequestContext.putTrusted(key, value)` accepts a trusted key,
+ *    and it is a distinct, greppable verb an app has to type on purpose.
+ * 2. INBOUND wire values for trusted keys never enter the context directly.
+ *    `RequestContextHeaders.fillFromRequest` stashes them as PENDING, and `AuthFilter`
+ *    admits them only after it knows who the caller is (see {@link PendingWireTrust}).
+ * 3. READS are typed: `getTrusted(key)` does not compile for an untrusted key, and
+ *    `getUntrusted(key)` does not compile for a trusted one. Picking a verb is
+ *    unavoidable, so a reader always knows which kind of value it is holding.
+ *
+ * Trusted keys DO keep their `httpHeader` — service-to-service propagation of a verified
+ * userId is a first-class requirement, not a hole. It is safe because rule 2 gates it on
+ * the endpoint's own auth mode: a route that verified WHO called it (`@AuthOidc`,
+ * `@AuthSharedSecret`) accepts the caller's trusted headers; a route reachable by a
+ * browser (`@AuthJwt`, public) does not.
+ *
+ * Per CLAUDE.md: data-only structures are classes, not interfaces.
+ *
+ * The type parameter `V` is the TYPE OF THE VALUE stored under this key — `string` for the wire/log
+ * keys (requestId, tenantId, ...), `ApiCallInfo` for the structured api tag, `TestCaseRecorder` for
+ * the recorder. It is REQUIRED (no default): every key must state what it holds. A heterogeneous
+ * store CANNOT be a `Record<string, string>` — the recorder and the api payload are not strings — so
+ * instead each KEY carries its own value type, and the typed accessors INFER it from the key. That
+ * keeps the backing Map honestly type-erased while the public surface stays fully typed: a caller
+ * never asserts a value type, the key already declares it. A genuinely mixed collection of keys is
+ * spelled explicitly as `AnyContextKey[]`, so "I mean a mixed bag" is a visible, deliberate
+ * statement, never a default.
+ *
+ * The type parameter `T` is the TRUST LEVEL, carried as a phantom type so the accessor verbs can
+ * reject the wrong kind of key at COMPILE time rather than throwing at runtime (CLAUDE.md treats a
+ * runtime throw standing in for an expressible type as a defect).
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextKey = void 0;
 class ContextKey {
@@ -9,29 +96,78 @@ class ContextKey {
      * 'x-request-id'). Undefined = context-only, never transferred.
      */
     httpHeader;
-    /** Mask this value (partially) in logs. */
-    isSecured;
+    /** The runtime twin of the phantom {@link __trust}. See the class doc. */
+    trust;
+    /**
+     * WHY this key is trusted, in prose — 'jwt claim `sub`, stamped by AuthFilter', or
+     * 'whatsapp webhook phone number -> user lookup'. Required on a trusted key, absent on an
+     * untrusted one. It exists so that grepping the trusted keys also tells you what proves each
+     * one, without opening another file.
+     */
+    provenance;
+    /** Mask this value (partially) in logs. Log redaction only — unrelated to {@link trust}. */
+    maskInLogs;
     /** Whether this key is logged at all. Default true; false = never logged. */
     isLogged;
-    constructor(name, httpHeader, isSecured = false, isLogged = true) {
+    /**
+     * PRIVATE — use {@link trusted} or {@link untrusted}. There is deliberately no way to build a key
+     * 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) {
         this.name = name;
+        this.trust = trust;
+        this.provenance = provenance;
         this.httpHeader = httpHeader;
-        this.isSecured = isSecured;
+        this.maskInLogs = maskInLogs;
         this.isLogged = isLogged;
     }
+    /**
+     * A key whose value the framework PROVED — a verified JWT claim, or a fact an app derived from a
+     * verified credential (a Twilio/WhatsApp webhook's signed phone number looked up to a userId).
+     *
+     * Only `RequestContext.putTrusted` can write one, only `RequestContext.getTrusted` can read one,
+     * and an inbound wire value for one is held PENDING until `AuthFilter` knows who the caller is.
+     *
+     * @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);
+    }
+    /**
+     * 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
+     * an input to an authorization decision.
+     *
+     * 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.
+     */
+    // 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);
+    }
     /** True when this key is transferred over HTTP (has an httpHeader). */
     isTransferred() {
         return this.httpHeader !== undefined;
     }
+    /**
+     * True for a key built by {@link trusted}. The RUNTIME check used by the inbound fill and the
+     * AuthFilter reconciliation; ordinary application code should never need it, because the typed
+     * verbs already made the decision at compile time.
+     */
+    isTrusted() {
+        return this.trust === 'trusted';
+    }
     /**
      * The value as it should appear in a log line: returned as-is for a normal
-     * key, partially masked when this key is secured. Masking is length-based:
+     * key, partially masked when this key sets `maskInLogs`. Masking is length-based:
      * - Length > 15: first 3 + "..." + last 3
      * - Length 8-15: first 2 + "..."
      * - Length < 8: "<secure key too short to log>"
      */
-    maskIfSecured(value) {
-        if (!this.isSecured) {
+    maskForLogs(value) {
+        if (!this.maskInLogs) {
             return value;
         }
         const len = value.length;

package/src/ContextKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextKey.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextKey.ts"],"names":[],"mappings":";;;AA6CA,MAAa,UAAU;IASnB,qEAAqE;IAC5D,IAAI,CAAS;IAEtB;;;OAGG;IACM,UAAU,CAAU;IAE7B,2CAA2C;IAClC,SAAS,CAAU;IAE5B,6EAA6E;IACpE,QAAQ,CAAU;IAE3B,YACI,IAAY,EACZ,UAAmB,EACnB,SAAS,GAAG,KAAK,EACjB,QAAQ,GAAG,IAAI;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;IAED,uEAAuE;IACvE,aAAa;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC;IACzC,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CAAC,KAAa;QACvB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAClB,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;AA7DD,gCA6DC","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 * - `isSecured`  When true, the value is masked (partially) in logs.\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 * 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, so a legacy\n * `new ContextKey('x')` fails to compile until it declares `new ContextKey<string>('x')` — the\n * type system does the migration for you. A heterogeneous store CANNOT be a `Record<string, string>`\n * — the recorder and the api payload are not strings — so instead each KEY carries its own value\n * type, and `RequestContext.getHeader/putHeader` INFER it from the key. That keeps the backing Map\n * honestly type-erased while the public surface stays fully typed: a caller never asserts a value\n * type, the key already declares it. A genuinely mixed collection of keys is spelled explicitly as\n * `AnyContextKey[]`, so \"I mean a mixed bag\" is a visible, deliberate statement, never a default.\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, and confines the one sanctioned `unknown` to this single alias instead of\n * scattering `ContextKey<unknown>` — and its disable comment — across the codebase.\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 AnyContextKey instead of repeating this.\nexport type AnyContextKey = ContextKey<unknown>;\n\nexport class ContextKey<V> {\n    /**\n     * Phantom marker carrying the value type {@link V}. It has no runtime existence (`declare`, never\n     * assigned) — it exists ONLY so `getHeader(key)` returns `V` and `putHeader(key, value)` checks\n     * `value` against `V`, both inferred straight from the key. Optional, so `ContextKey<A>` stays\n     * assignable to `AnyContextKey` (i.e. `ContextKey<unknown>`) — arrays of mixed keys keep working.\n     */\n    declare readonly __valueType?: V;\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    /** Mask this value (partially) in logs. */\n    readonly isSecured: boolean;\n\n    /** Whether this key is logged at all. Default true; false = never logged. */\n    readonly isLogged: boolean;\n\n    constructor(\n        name: string,\n        httpHeader?: string,\n        isSecured = false,\n        isLogged = true,\n    ) {\n        this.name = name;\n        this.httpHeader = httpHeader;\n        this.isSecured = isSecured;\n        this.isLogged = isLogged;\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     * The value as it should appear in a log line: returned as-is for a normal\n     * key, partially masked when this key is secured. 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    maskIfSecured(value: string): string {\n        if (!this.isSecured) {\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":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;;;AAkCH,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,CAAe,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IACvG,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,CAAiB,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC1G,CAAC;IAED,uEAAuE;IACvE,aAAa;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC;IACzC,CAAC;IAED;;;;OAIG;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;AAvID,gCAuIC","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 CLAUDE.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 (`@AuthOidc`,\n * `@AuthSharedSecret`) accepts the caller's trusted headers; a route reachable by a\n * browser (`@AuthJwt`, 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.md 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 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, and confines the one sanctioned `unknown` to this single alias instead of\n * scattering `ContextKey<unknown>` — and its disable comment — across the codebase.\n *\n * NOTE this is mixed in TRUST as well as in value type, so it is READ-ONLY territory: `getAny(key)`\n * takes one, but no WRITE verb does. A write must name the trust level, which is what keeps the\n * `trusted` label honest.\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 AnyContextKey instead of repeating this.\nexport type AnyContextKey = ContextKey<unknown>;\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 -- same sanctioned mixed-bag alias as AnyContextKey, narrowed to the trusted branch\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 as AnyContextKey, narrowed to the untrusted branch\nexport type AnyUntrustedContextKey = ContextKey<unknown, 'untrusted'>;\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'>(name, 'trusted', provenance, httpHeader, maskInLogs, isLogged);\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'>(name, 'untrusted', undefined, httpHeader, maskInLogs, isLogged);\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}. The RUNTIME check used by the inbound fill and the\n     * AuthFilter reconciliation; ordinary application code should never need it, because the typed\n     * verbs already made the decision at compile time.\n     */\n    isTrusted(): boolean {\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/ContextKeyTrustCompileAssertions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * COMPILE-TIME assertions that the trust system cannot be bypassed by writing the wrong thing.
+ *
+ * Every `@ts-expect-error` below FAILS THE BUILD (TS2578, "unused '@ts-expect-error' directive") the
+ * day its line starts compiling — so this file is a tripwire, not documentation that can rot.
+ *
+ * It lives in COMPILED source, never in a `.spec.ts`, and that placement is load-bearing:
+ * `tsconfig.lib.json` excludes specs and vitest strips types with esbuild, so a `@ts-expect-error`
+ * in a spec is inert and the suite would pass either way. See the same pattern in
+ * `AuthJwtCompileAssertions.ts`.
+ *
+ * The verb-level assertions (`getTrusted` refusing an untrusted key, and vice versa) live in
+ * core-context beside `RequestContext`, which is where those verbs are declared.
+ */
+export declare class ContextKeyTrustCompileAssertions {
+    /** A trusted key MUST state its provenance — "trusted because reasons unstated" is unwritable. */
+    trustedRequiresProvenance(): void;
+    /**
+     * There is NO public constructor. A key cannot exist without picking a trust branch, so trust can
+     * never be defaulted, forgotten, or silently widened by an omitted argument.
+     */
+    noConstructorEscapeHatch(): void;
+    /**
+     * The two branches are NOT interchangeable types. This is what makes `getTrusted(SOME_UNTRUSTED)`
+     * a compile error rather than a runtime throw — assigning one to the other must not typecheck.
+     */
+    branchesAreNotInterchangeable(): void;
+    /**
+     * BOTH branches must still flow into the mixed-bag alias, or the registry's key arrays
+     * (`ALL_HEADERS`, `getLoggedKeys()`, `getTransferredKeys()`) would stop compiling. This one is a
+     * POSITIVE assertion: it must keep working.
+     */
+    bothBranchesAreAnyContextKey(): void;
+}

package/src/ContextKeyTrustCompileAssertions.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextKeyTrustCompileAssertions = void 0;
+const ContextKey_1 = require("./ContextKey");
+/**
+ * COMPILE-TIME assertions that the trust system cannot be bypassed by writing the wrong thing.
+ *
+ * Every `@ts-expect-error` below FAILS THE BUILD (TS2578, "unused '@ts-expect-error' directive") the
+ * day its line starts compiling — so this file is a tripwire, not documentation that can rot.
+ *
+ * It lives in COMPILED source, never in a `.spec.ts`, and that placement is load-bearing:
+ * `tsconfig.lib.json` excludes specs and vitest strips types with esbuild, so a `@ts-expect-error`
+ * in a spec is inert and the suite would pass either way. See the same pattern in
+ * `AuthJwtCompileAssertions.ts`.
+ *
+ * The verb-level assertions (`getTrusted` refusing an untrusted key, and vice versa) live in
+ * core-context beside `RequestContext`, which is where those verbs are declared.
+ */
+class ContextKeyTrustCompileAssertions {
+    /** A trusted key MUST state its provenance — "trusted because reasons unstated" is unwritable. */
+    trustedRequiresProvenance() {
+        // @ts-expect-error - provenance is required on ContextKey.trusted
+        ContextKey_1.ContextKey.trusted('userId');
+    }
+    /**
+     * There is NO public constructor. A key cannot exist without picking a trust branch, so trust can
+     * never be defaulted, forgotten, or silently widened by an omitted argument.
+     */
+    noConstructorEscapeHatch() {
+        // @ts-expect-error - the constructor is private; use ContextKey.trusted / ContextKey.untrusted
+        new ContextKey_1.ContextKey('userId', 'trusted', undefined, 'x-user-id', false, true);
+    }
+    /**
+     * The two branches are NOT interchangeable types. This is what makes `getTrusted(SOME_UNTRUSTED)`
+     * a compile error rather than a runtime throw — assigning one to the other must not typecheck.
+     */
+    branchesAreNotInterchangeable() {
+        const untrusted = ContextKey_1.ContextKey.untrusted('actionId');
+        // @ts-expect-error - an untrusted key is not a trusted key
+        const asTrusted = untrusted;
+        void asTrusted;
+        const trusted = ContextKey_1.ContextKey.trusted('userId', 'jwt claim');
+        // @ts-expect-error - a trusted key is not an untrusted key
+        const asUntrusted = trusted;
+        void asUntrusted;
+    }
+    /**
+     * BOTH branches must still flow into the mixed-bag alias, or the registry's key arrays
+     * (`ALL_HEADERS`, `getLoggedKeys()`, `getTransferredKeys()`) would stop compiling. This one is a
+     * POSITIVE assertion: it must keep working.
+     */
+    bothBranchesAreAnyContextKey() {
+        const keys = [
+            ContextKey_1.ContextKey.trusted('userId', 'jwt claim `sub`', 'x-user-id'),
+            ContextKey_1.ContextKey.untrusted('actionId', 'x-webpieces-actionid'),
+        ];
+        void keys;
+    }
+}
+exports.ContextKeyTrustCompileAssertions = ContextKeyTrustCompileAssertions;
+//# sourceMappingURL=ContextKeyTrustCompileAssertions.js.map

package/src/ContextKeyTrustCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextKeyTrustCompileAssertions.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextKeyTrustCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,6CAAyD;AAEzD;;;;;;;;;;;;;GAaG;AACH,MAAa,gCAAgC;IACzC,kGAAkG;IAClG,yBAAyB;QACrB,kEAAkE;QAClE,uBAAU,CAAC,OAAO,CAAS,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,wBAAwB;QACpB,+FAA+F;QAC/F,IAAI,uBAAU,CAAS,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACrF,CAAC;IAED;;;OAGG;IACH,6BAA6B;QACzB,MAAM,SAAS,GAAoC,uBAAU,CAAC,SAAS,CAAS,UAAU,CAAC,CAAC;QAC5F,2DAA2D;QAC3D,MAAM,SAAS,GAAkC,SAAS,CAAC;QAC3D,KAAK,SAAS,CAAC;QAEf,MAAM,OAAO,GAAkC,uBAAU,CAAC,OAAO,CAAS,QAAQ,EAAE,WAAW,CAAC,CAAC;QACjG,2DAA2D;QAC3D,MAAM,WAAW,GAAoC,OAAO,CAAC;QAC7D,KAAK,WAAW,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,4BAA4B;QACxB,MAAM,IAAI,GAAoB;YAC1B,uBAAU,CAAC,OAAO,CAAS,QAAQ,EAAE,iBAAiB,EAAE,WAAW,CAAC;YACpE,uBAAU,CAAC,SAAS,CAAS,UAAU,EAAE,sBAAsB,CAAC;SACnE,CAAC;QACF,KAAK,IAAI,CAAC;IACd,CAAC;CACJ;AA5CD,4EA4CC","sourcesContent":["import { ContextKey, AnyContextKey } from './ContextKey';\n\n/**\n * COMPILE-TIME assertions that the trust system cannot be bypassed by writing the wrong thing.\n *\n * Every `@ts-expect-error` below FAILS THE BUILD (TS2578, \"unused '@ts-expect-error' directive\") the\n * day its line starts compiling — so this file is a tripwire, not documentation that can rot.\n *\n * It lives in COMPILED source, never in a `.spec.ts`, and that placement is load-bearing:\n * `tsconfig.lib.json` excludes specs and vitest strips types with esbuild, so a `@ts-expect-error`\n * in a spec is inert and the suite would pass either way. See the same pattern in\n * `AuthJwtCompileAssertions.ts`.\n *\n * The verb-level assertions (`getTrusted` refusing an untrusted key, and vice versa) live in\n * core-context beside `RequestContext`, which is where those verbs are declared.\n */\nexport class ContextKeyTrustCompileAssertions {\n    /** A trusted key MUST state its provenance — \"trusted because reasons unstated\" is unwritable. */\n    trustedRequiresProvenance(): void {\n        // @ts-expect-error - provenance is required on ContextKey.trusted\n        ContextKey.trusted<string>('userId');\n    }\n\n    /**\n     * There is NO public constructor. A key cannot exist without picking a trust branch, so trust can\n     * never be defaulted, forgotten, or silently widened by an omitted argument.\n     */\n    noConstructorEscapeHatch(): void {\n        // @ts-expect-error - the constructor is private; use ContextKey.trusted / ContextKey.untrusted\n        new ContextKey<string>('userId', 'trusted', undefined, 'x-user-id', false, true);\n    }\n\n    /**\n     * The two branches are NOT interchangeable types. This is what makes `getTrusted(SOME_UNTRUSTED)`\n     * a compile error rather than a runtime throw — assigning one to the other must not typecheck.\n     */\n    branchesAreNotInterchangeable(): void {\n        const untrusted: ContextKey<string, 'untrusted'> = ContextKey.untrusted<string>('actionId');\n        // @ts-expect-error - an untrusted key is not a trusted key\n        const asTrusted: ContextKey<string, 'trusted'> = untrusted;\n        void asTrusted;\n\n        const trusted: ContextKey<string, 'trusted'> = ContextKey.trusted<string>('userId', 'jwt claim');\n        // @ts-expect-error - a trusted key is not an untrusted key\n        const asUntrusted: ContextKey<string, 'untrusted'> = trusted;\n        void asUntrusted;\n    }\n\n    /**\n     * BOTH branches must still flow into the mixed-bag alias, or the registry's key arrays\n     * (`ALL_HEADERS`, `getLoggedKeys()`, `getTransferredKeys()`) would stop compiling. This one is a\n     * POSITIVE assertion: it must keep working.\n     */\n    bothBranchesAreAnyContextKey(): void {\n        const keys: AnyContextKey[] = [\n            ContextKey.trusted<string>('userId', 'jwt claim `sub`', 'x-user-id'),\n            ContextKey.untrusted<string>('actionId', 'x-webpieces-actionid'),\n        ];\n        void keys;\n    }\n}\n"]}

package/src/ContextTuple.d.ts

@@ -1,12 +1,17 @@
-import { AnyContextKey } from './ContextKey';
+import { AnyTrustedContextKey } from './ContextKey';
 /**
  * ContextTuple - one (ContextKey, value) pair to be stamped into the request's
  * "magic context" (RequestContext on the server) — e.g. USER_ID, ORG_ID. The JWT
- * parse plugin returns these so the framework can set them via RequestContext.putHeader.
+ * parse plugin returns these so the framework can set them via `RequestContext.putTrusted`.
  * Data-only structure (a class, per the guidelines).
+ *
+ * The key is deliberately an {@link AnyTrustedContextKey}, not any old key: everything in here was
+ * derived from a VERIFIED credential, so stamping an untrusted key from a JWT parse is a category
+ * error and does not compile. This is also what lets `AuthFilter` treat "the authenticator claimed
+ * this key" as the definition of trusted — see its reconciliation of pending wire values.
  */
 export declare class ContextTuple {
-    readonly key: AnyContextKey;
+    readonly key: AnyTrustedContextKey;
     readonly value: unknown;
-    constructor(key: AnyContextKey, value: unknown);
+    constructor(key: AnyTrustedContextKey, value: unknown);
 }

package/src/ContextTuple.js

@@ -4,8 +4,13 @@ exports.ContextTuple = void 0;
 /**
  * ContextTuple - one (ContextKey, value) pair to be stamped into the request's
  * "magic context" (RequestContext on the server) — e.g. USER_ID, ORG_ID. The JWT
- * parse plugin returns these so the framework can set them via RequestContext.putHeader.
+ * parse plugin returns these so the framework can set them via `RequestContext.putTrusted`.
  * Data-only structure (a class, per the guidelines).
+ *
+ * The key is deliberately an {@link AnyTrustedContextKey}, not any old key: everything in here was
+ * derived from a VERIFIED credential, so stamping an untrusted key from a JWT parse is a category
+ * error and does not compile. This is also what lets `AuthFilter` treat "the authenticator claimed
+ * this key" as the definition of trusted — see its reconciliation of pending wire values.
  */
 class ContextTuple {
     key;

package/src/ContextTuple.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextTuple.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextTuple.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,MAAa,YAAY;IAED;IAEA;IAHpB,YACoB,GAAkB;IAClC,oFAAoF;IACpE,KAAc;QAFd,QAAG,GAAH,GAAG,CAAe;QAElB,UAAK,GAAL,KAAK,CAAS;IAC/B,CAAC;CACP;AAND,oCAMC","sourcesContent":["import { ContextKey, AnyContextKey } from './ContextKey';\n\n/**\n * ContextTuple - one (ContextKey, value) pair to be stamped into the request's\n * \"magic context\" (RequestContext on the server) — e.g. USER_ID, ORG_ID. The JWT\n * parse plugin returns these so the framework can set them via RequestContext.putHeader.\n * Data-only structure (a class, per the guidelines).\n */\nexport class ContextTuple {\n    constructor(\n        public readonly key: AnyContextKey,\n        // webpieces-disable no-any-unknown -- context values are arbitrary app-defined data\n        public readonly value: unknown,\n    ) {}\n}\n"]}
+{"version":3,"file":"ContextTuple.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextTuple.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;GAUG;AACH,MAAa,YAAY;IAED;IAEA;IAHpB,YACoB,GAAyB;IACzC,oFAAoF;IACpE,KAAc;QAFd,QAAG,GAAH,GAAG,CAAsB;QAEzB,UAAK,GAAL,KAAK,CAAS;IAC/B,CAAC;CACP;AAND,oCAMC","sourcesContent":["import { AnyTrustedContextKey } from './ContextKey';\n\n/**\n * ContextTuple - one (ContextKey, value) pair to be stamped into the request's\n * \"magic context\" (RequestContext on the server) — e.g. USER_ID, ORG_ID. The JWT\n * parse plugin returns these so the framework can set them via `RequestContext.putTrusted`.\n * Data-only structure (a class, per the guidelines).\n *\n * The key is deliberately an {@link AnyTrustedContextKey}, not any old key: everything in here was\n * derived from a VERIFIED credential, so stamping an untrusted key from a JWT parse is a category\n * error and does not compile. This is also what lets `AuthFilter` treat \"the authenticator claimed\n * this key\" as the definition of trusted — see its reconciliation of pending wire values.\n */\nexport class ContextTuple {\n    constructor(\n        public readonly key: AnyTrustedContextKey,\n        // webpieces-disable no-any-unknown -- context values are arbitrary app-defined data\n        public readonly value: unknown,\n    ) {}\n}\n"]}