@webpieces/core-context 0.4.605 → 0.4.607

package/src/CapturedContextCompileAssertions.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapturedContextCompileAssertions = void 0;
+const CapturedContext_1 = require("./CapturedContext");
+const RequestContext_1 = require("./RequestContext");
+/**
+ * COMPILE-TIME assertions that a context can only be restored from a REAL capture.
+ *
+ * The runtime half — that a snapshot round-trips, and that mutating the source afterwards does not
+ * reach it — is in `CapturedContext.spec.ts`. What a spec CANNOT express is the half that matters
+ * most: that `RequestContext.restoreContext(new Map([['userId', 'victim']]))` does not compile. Each
+ * `@ts-expect-error` below fails the build with TS2578 the day its line starts compiling again.
+ *
+ * In COMPILED source deliberately — `tsconfig.lib.json` excludes specs and vitest strips types with
+ * esbuild, so a `@ts-expect-error` in a `.spec.ts` is inert and the suite would pass either way. See
+ * `RequestContextTrustCompileAssertions` for the trust-verb half.
+ */
+class CapturedContextCompileAssertions {
+    /** THE hole this change closes: a hand-assembled payload forging a trusted value. */
+    cannotRestoreAHandBuiltMap() {
+        // @ts-expect-error - restoreContext takes an opaque CapturedContext, never a raw Map
+        RequestContext_1.RequestContext.restoreContext(new Map([['userId', 'victim']]));
+    }
+    /** Same hole through the other door. */
+    cannotRunWithAHandBuiltMap() {
+        // @ts-expect-error - runWithContext takes an opaque CapturedContext, never a raw Map
+        RequestContext_1.RequestContext.runWithContext(new Map([['userId', 'victim']]), () => undefined);
+    }
+    /** Nor by asserting an object literal into the shape — the private `#entries` makes it nominal. */
+    cannotFakeTheShape() {
+        // @ts-expect-error - an object literal is not a CapturedContext; #entries is not satisfiable
+        const forged = { size: () => 1 };
+        void forged;
+    }
+    /** Nor by constructing one directly — the constructor is private. */
+    cannotConstructOneDirectly() {
+        // @ts-expect-error - the constructor is private; copyContext() is the only producer
+        const forged = new CapturedContext_1.CapturedContext(new Map([['userId', 'victim']]));
+        void forged;
+    }
+    /**
+     * Nor by calling the factory: it demands a capability token whose own constructor is private, so
+     * even code that can NAME the token (this package) cannot mint a second one.
+     */
+    cannotMintAnAuthority() {
+        // @ts-expect-error - ContextCaptureAuthority's constructor is private; INTERNAL is the only one
+        const forgedAuthority = new CapturedContext_1.ContextCaptureAuthority();
+        void forgedAuthority;
+    }
+    /** And the factory is not callable without one at all. */
+    cannotCaptureWithoutAnAuthority() {
+        // @ts-expect-error - capture() requires a ContextCaptureAuthority as its first argument
+        CapturedContext_1.CapturedContext.capture(new Map([['userId', 'victim']]));
+    }
+    /**
+     * THE new hole this pair closes: a BARE capture must not run. If it did, `runWithContext(snapshot,
+     * fn)` would sit next to `runWithContext(snapshot.withTrusted(), fn)` as a second spelling whose
+     * shorter form silently carries a user identity — a widening that is an absence rather than a
+     * token, and ungreppable. The capture is inert until it states its intent.
+     */
+    cannotRunABareCapture() {
+        const captured = RequestContext_1.RequestContext.copyContext();
+        // @ts-expect-error - runWithContext takes a RestorableContext: say withTrusted() or withoutTrusted()
+        RequestContext_1.RequestContext.runWithContext(captured, () => undefined);
+    }
+    /** Same, through the in-place door. */
+    cannotRestoreABareCapture() {
+        const captured = RequestContext_1.RequestContext.copyContext();
+        // @ts-expect-error - restoreContext takes a RestorableContext: say withTrusted() or withoutTrusted()
+        RequestContext_1.RequestContext.restoreContext(captured);
+    }
+    /**
+     * And the intent is stated by NARROWING, never by a flag on the run call. A `keepTrusted: boolean`
+     * would make the wide intent as easy to type as the narrow one and impossible to grep; this line
+     * fails the build the day such a parameter appears.
+     */
+    cannotStateTheIntentViaAFlagOnTheRunCall() {
+        const captured = RequestContext_1.RequestContext.copyContext().withTrusted();
+        // @ts-expect-error - there is no third parameter; narrow the snapshot instead
+        RequestContext_1.RequestContext.runWithContext(captured, () => undefined, false);
+    }
+    /** Nor can a narrowed snapshot be minted directly — same private constructor, same token. */
+    cannotConstructARestorableContextDirectly() {
+        // @ts-expect-error - the constructor is private; withTrusted()/withoutTrusted() are the producers
+        const forged = new CapturedContext_1.RestorableContext(new Map([['userId', 'victim']]));
+        void forged;
+    }
+    /** Nor through its factory, which demands the same unobtainable authority. */
+    cannotMintARestorableContextWithoutAnAuthority() {
+        // @ts-expect-error - of() requires a ContextCaptureAuthority as its first argument
+        CapturedContext_1.RestorableContext.of(new Map([['userId', 'victim']]));
+    }
+    /** POSITIVE: both narrowings produce the ONE type both consumers take. */
+    bothNarrowingsFeedBothConsumers() {
+        const captured = RequestContext_1.RequestContext.copyContext();
+        const wide = captured.withTrusted();
+        const dropped = captured.withoutTrusted();
+        RequestContext_1.RequestContext.runWithContext(wide, () => {
+            RequestContext_1.RequestContext.restoreContext(dropped);
+        });
+    }
+    /** POSITIVE: the real round trip must keep compiling — restoring a proven value IS the point. */
+    theRealRoundTripCompiles() {
+        const captured = RequestContext_1.RequestContext.copyContext().withTrusted();
+        RequestContext_1.RequestContext.runWithContext(captured, () => {
+            RequestContext_1.RequestContext.restoreContext(captured);
+        });
+    }
+}
+exports.CapturedContextCompileAssertions = CapturedContextCompileAssertions;
+//# sourceMappingURL=CapturedContextCompileAssertions.js.map

package/src/CapturedContextCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapturedContextCompileAssertions.js","sourceRoot":"","sources":["../../../../../packages/core/core-context/src/CapturedContextCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,uDAAgG;AAChG,qDAAkD;AAElD;;;;;;;;;;;GAWG;AACH,MAAa,gCAAgC;IACzC,qFAAqF;IACrF,0BAA0B;QACtB,qFAAqF;QACrF,+BAAc,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,wCAAwC;IACxC,0BAA0B;QACtB,qFAAqF;QACrF,+BAAc,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACpF,CAAC;IAED,mGAAmG;IACnG,kBAAkB;QACd,6FAA6F;QAC7F,MAAM,MAAM,GAAoB,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;QAClD,KAAK,MAAM,CAAC;IAChB,CAAC;IAED,qEAAqE;IACrE,0BAA0B;QACtB,oFAAoF;QACpF,MAAM,MAAM,GAAG,IAAI,iCAAe,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,KAAK,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,qBAAqB;QACjB,gGAAgG;QAChG,MAAM,eAAe,GAAG,IAAI,yCAAuB,EAAE,CAAC;QACtD,KAAK,eAAe,CAAC;IACzB,CAAC;IAED,0DAA0D;IAC1D,+BAA+B;QAC3B,wFAAwF;QACxF,iCAAe,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;OAKG;IACH,qBAAqB;QACjB,MAAM,QAAQ,GAAoB,+BAAc,CAAC,WAAW,EAAE,CAAC;QAC/D,qGAAqG;QACrG,+BAAc,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;IAED,uCAAuC;IACvC,yBAAyB;QACrB,MAAM,QAAQ,GAAoB,+BAAc,CAAC,WAAW,EAAE,CAAC;QAC/D,qGAAqG;QACrG,+BAAc,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,wCAAwC;QACpC,MAAM,QAAQ,GAAsB,+BAAc,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/E,8EAA8E;QAC9E,+BAAc,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACpE,CAAC;IAED,6FAA6F;IAC7F,yCAAyC;QACrC,kGAAkG;QAClG,MAAM,MAAM,GAAG,IAAI,mCAAiB,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,KAAK,MAAM,CAAC;IAChB,CAAC;IAED,8EAA8E;IAC9E,8CAA8C;QAC1C,mFAAmF;QACnF,mCAAiB,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,0EAA0E;IAC1E,+BAA+B;QAC3B,MAAM,QAAQ,GAAoB,+BAAc,CAAC,WAAW,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAsB,QAAQ,CAAC,WAAW,EAAE,CAAC;QACvD,MAAM,OAAO,GAAsB,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC7D,+BAAc,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE;YACrC,+BAAc,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;IACP,CAAC;IAED,iGAAiG;IACjG,wBAAwB;QACpB,MAAM,QAAQ,GAAsB,+BAAc,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/E,+BAAc,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;YACzC,+BAAc,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AAvGD,4EAuGC","sourcesContent":["import { CapturedContext, ContextCaptureAuthority, RestorableContext } from './CapturedContext';\nimport { RequestContext } from './RequestContext';\n\n/**\n * COMPILE-TIME assertions that a context can only be restored from a REAL capture.\n *\n * The runtime half — that a snapshot round-trips, and that mutating the source afterwards does not\n * reach it — is in `CapturedContext.spec.ts`. What a spec CANNOT express is the half that matters\n * most: that `RequestContext.restoreContext(new Map([['userId', 'victim']]))` does not compile. Each\n * `@ts-expect-error` below fails the build with TS2578 the day its line starts compiling again.\n *\n * In COMPILED source deliberately — `tsconfig.lib.json` excludes specs and vitest strips types with\n * esbuild, so a `@ts-expect-error` in a `.spec.ts` is inert and the suite would pass either way. See\n * `RequestContextTrustCompileAssertions` for the trust-verb half.\n */\nexport class CapturedContextCompileAssertions {\n    /** THE hole this change closes: a hand-assembled payload forging a trusted value. */\n    cannotRestoreAHandBuiltMap(): void {\n        // @ts-expect-error - restoreContext takes an opaque CapturedContext, never a raw Map\n        RequestContext.restoreContext(new Map([['userId', 'victim']]));\n    }\n\n    /** Same hole through the other door. */\n    cannotRunWithAHandBuiltMap(): void {\n        // @ts-expect-error - runWithContext takes an opaque CapturedContext, never a raw Map\n        RequestContext.runWithContext(new Map([['userId', 'victim']]), () => undefined);\n    }\n\n    /** Nor by asserting an object literal into the shape — the private `#entries` makes it nominal. */\n    cannotFakeTheShape(): void {\n        // @ts-expect-error - an object literal is not a CapturedContext; #entries is not satisfiable\n        const forged: CapturedContext = { size: () => 1 };\n        void forged;\n    }\n\n    /** Nor by constructing one directly — the constructor is private. */\n    cannotConstructOneDirectly(): void {\n        // @ts-expect-error - the constructor is private; copyContext() is the only producer\n        const forged = new CapturedContext(new Map([['userId', 'victim']]));\n        void forged;\n    }\n\n    /**\n     * Nor by calling the factory: it demands a capability token whose own constructor is private, so\n     * even code that can NAME the token (this package) cannot mint a second one.\n     */\n    cannotMintAnAuthority(): void {\n        // @ts-expect-error - ContextCaptureAuthority's constructor is private; INTERNAL is the only one\n        const forgedAuthority = new ContextCaptureAuthority();\n        void forgedAuthority;\n    }\n\n    /** And the factory is not callable without one at all. */\n    cannotCaptureWithoutAnAuthority(): void {\n        // @ts-expect-error - capture() requires a ContextCaptureAuthority as its first argument\n        CapturedContext.capture(new Map([['userId', 'victim']]));\n    }\n\n    /**\n     * THE new hole this pair closes: a BARE capture must not run. If it did, `runWithContext(snapshot,\n     * fn)` would sit next to `runWithContext(snapshot.withTrusted(), fn)` as a second spelling whose\n     * shorter form silently carries a user identity — a widening that is an absence rather than a\n     * token, and ungreppable. The capture is inert until it states its intent.\n     */\n    cannotRunABareCapture(): void {\n        const captured: CapturedContext = RequestContext.copyContext();\n        // @ts-expect-error - runWithContext takes a RestorableContext: say withTrusted() or withoutTrusted()\n        RequestContext.runWithContext(captured, () => undefined);\n    }\n\n    /** Same, through the in-place door. */\n    cannotRestoreABareCapture(): void {\n        const captured: CapturedContext = RequestContext.copyContext();\n        // @ts-expect-error - restoreContext takes a RestorableContext: say withTrusted() or withoutTrusted()\n        RequestContext.restoreContext(captured);\n    }\n\n    /**\n     * And the intent is stated by NARROWING, never by a flag on the run call. A `keepTrusted: boolean`\n     * would make the wide intent as easy to type as the narrow one and impossible to grep; this line\n     * fails the build the day such a parameter appears.\n     */\n    cannotStateTheIntentViaAFlagOnTheRunCall(): void {\n        const captured: RestorableContext = RequestContext.copyContext().withTrusted();\n        // @ts-expect-error - there is no third parameter; narrow the snapshot instead\n        RequestContext.runWithContext(captured, () => undefined, false);\n    }\n\n    /** Nor can a narrowed snapshot be minted directly — same private constructor, same token. */\n    cannotConstructARestorableContextDirectly(): void {\n        // @ts-expect-error - the constructor is private; withTrusted()/withoutTrusted() are the producers\n        const forged = new RestorableContext(new Map([['userId', 'victim']]));\n        void forged;\n    }\n\n    /** Nor through its factory, which demands the same unobtainable authority. */\n    cannotMintARestorableContextWithoutAnAuthority(): void {\n        // @ts-expect-error - of() requires a ContextCaptureAuthority as its first argument\n        RestorableContext.of(new Map([['userId', 'victim']]));\n    }\n\n    /** POSITIVE: both narrowings produce the ONE type both consumers take. */\n    bothNarrowingsFeedBothConsumers(): void {\n        const captured: CapturedContext = RequestContext.copyContext();\n        const wide: RestorableContext = captured.withTrusted();\n        const dropped: RestorableContext = captured.withoutTrusted();\n        RequestContext.runWithContext(wide, () => {\n            RequestContext.restoreContext(dropped);\n        });\n    }\n\n    /** POSITIVE: the real round trip must keep compiling — restoring a proven value IS the point. */\n    theRealRoundTripCompiles(): void {\n        const captured: RestorableContext = RequestContext.copyContext().withTrusted();\n        RequestContext.runWithContext(captured, () => {\n            RequestContext.restoreContext(captured);\n        });\n    }\n}\n"]}

package/src/DetachedScopeCompileAssertions.d.ts

@@ -0,0 +1,62 @@
+import { AnyContextKey } from '@webpieces/core-util';
+/**
+ * COMPILE-TIME assertions for {@link RequestContext.runDetachedScope}.
+ *
+ * The runtime half — that the detached scope starts empty, that the enclosing scope survives, that a
+ * throw unwinds it — is in `DetachedScope.spec.ts`. What a spec CANNOT express is the half that makes
+ * the browser-log path safe BY CONSTRUCTION rather than by remembering to filter:
+ *
+ *  - `runDetachedScope` has NO container-taking form, so the deleted `runWithContext(map, fn)` forgery
+ *    path cannot come back through this door;
+ *  - a loop over a mixed `AnyContextKey[]` cannot write ANY key until it has tested that key's trust;
+ *  - and a TRUSTED key can never reach `putUntrusted`, so a browser — which proves nothing — cannot
+ *    FABRICATE a proven value by naming `userId` in its payload. It is a compile error at the write,
+ *    not a filter someone has to remember to write.
+ *
+ * That is about the SOURCE, not about the key. Writing a trusted key is ordinary and legitimate — see
+ * {@link putTrustedIsLegitimateInsideADetachedScope} — whenever the caller has actually proven the
+ * value. What cannot be written down is a claim of proof by code that has none.
+ *
+ * In COMPILED source deliberately — `tsconfig.lib.json` excludes specs and vitest strips types with
+ * esbuild, so a `@ts-expect-error` in a `.spec.ts` is inert and the suite would pass either way. Each
+ * one below fails the build with TS2578 the day its line starts compiling. See
+ * `CapturedContextCompileAssertions` and `RequestContextTrustCompileAssertions` for the sibling halves.
+ */
+export declare class DetachedScopeCompileAssertions {
+    private readonly trusted;
+    private readonly untrusted;
+    /**
+     * THE hole this whole shape exists to keep shut: no Map/object/array of entries may cross the
+     * boundary. Values are written INSIDE the closure, through the trust verbs.
+     */
+    cannotHandItAContainerOfEntries(): void;
+    /** Nor a plain object of entries, which is the same hole spelled differently. */
+    cannotHandItAnObjectOfEntries(): void;
+    /** A key of unknown trust cannot be written AT ALL — the branch is not optional. */
+    cannotWriteAMixedKeyWithoutTestingItsTrust(key: AnyContextKey): void;
+    /**
+     * And a TRUSTED key cannot be LAUNDERED through the untrusted verb, detached or not — which is
+     * what a caller with no proof would have to do, since `putTrusted` is the only other way in and
+     * saying it is a deliberate, greppable claim.
+     */
+    cannotLaunderATrustedKeyThroughTheUntrustedVerb(): void;
+    /**
+     * POSITIVE, and the point the negative above must not be mistaken for: writing a TRUSTED value
+     * inside a detached scope is ordinary and correct when the caller has actually proven it — the
+     * signed-webhook case (Twilio/WhatsApp proves the phone number, the app looks up the userId), or a
+     * verified JWT claim. `putTrusted` is the verb for exactly that, and a detached scope does not
+     * change it. Trust is about tamper-resistance, not secrecy: a trusted `userId` is a plain,
+     * fully-logged GUID; masking is the separate `maskInLogs` axis.
+     */
+    putTrustedIsLegitimateInsideADetachedScope(): void;
+    /**
+     * POSITIVE, and the shape the real consumer writes: emit one browser line under a fresh scope
+     * rebuilt from an EXTERNAL payload, driven off the registry's logged keys.
+     *
+     * The `isTrusted()` skip is what a reader sees; the compiler is what enforces it. Delete the skip
+     * and `isUntrusted()` still refuses the trusted key, so the trusted branch has no write at all.
+     */
+    theBrowserLogLoopCompiles(loggedKeys: AnyContextKey[], payload: Record<string, unknown>): void;
+    /** The return value flows through, and an async closure is a promise the caller can await. */
+    returnValuesFlowThrough(): Promise<void>;
+}

package/src/DetachedScopeCompileAssertions.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DetachedScopeCompileAssertions = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const RequestContext_1 = require("./RequestContext");
+/**
+ * COMPILE-TIME assertions for {@link RequestContext.runDetachedScope}.
+ *
+ * The runtime half — that the detached scope starts empty, that the enclosing scope survives, that a
+ * throw unwinds it — is in `DetachedScope.spec.ts`. What a spec CANNOT express is the half that makes
+ * the browser-log path safe BY CONSTRUCTION rather than by remembering to filter:
+ *
+ *  - `runDetachedScope` has NO container-taking form, so the deleted `runWithContext(map, fn)` forgery
+ *    path cannot come back through this door;
+ *  - a loop over a mixed `AnyContextKey[]` cannot write ANY key until it has tested that key's trust;
+ *  - and a TRUSTED key can never reach `putUntrusted`, so a browser — which proves nothing — cannot
+ *    FABRICATE a proven value by naming `userId` in its payload. It is a compile error at the write,
+ *    not a filter someone has to remember to write.
+ *
+ * That is about the SOURCE, not about the key. Writing a trusted key is ordinary and legitimate — see
+ * {@link putTrustedIsLegitimateInsideADetachedScope} — whenever the caller has actually proven the
+ * value. What cannot be written down is a claim of proof by code that has none.
+ *
+ * In COMPILED source deliberately — `tsconfig.lib.json` excludes specs and vitest strips types with
+ * esbuild, so a `@ts-expect-error` in a `.spec.ts` is inert and the suite would pass either way. Each
+ * one below fails the build with TS2578 the day its line starts compiling. See
+ * `CapturedContextCompileAssertions` and `RequestContextTrustCompileAssertions` for the sibling halves.
+ */
+class DetachedScopeCompileAssertions {
+    trusted = core_util_1.ContextKey.trusted('assertDetachedUserId', 'jwt claim `sub`');
+    untrusted = core_util_1.ContextKey.untrusted('assertDetachedActionId');
+    /**
+     * THE hole this whole shape exists to keep shut: no Map/object/array of entries may cross the
+     * boundary. Values are written INSIDE the closure, through the trust verbs.
+     */
+    cannotHandItAContainerOfEntries() {
+        // @ts-expect-error - runDetachedScope takes ONLY a closure; there is no map-taking form
+        RequestContext_1.RequestContext.runDetachedScope(new Map([['userId', 'victim']]), () => undefined);
+    }
+    /** Nor a plain object of entries, which is the same hole spelled differently. */
+    cannotHandItAnObjectOfEntries() {
+        // @ts-expect-error - the single parameter is the closure, not a bag of values
+        RequestContext_1.RequestContext.runDetachedScope({ userId: 'victim' });
+    }
+    /** A key of unknown trust cannot be written AT ALL — the branch is not optional. */
+    cannotWriteAMixedKeyWithoutTestingItsTrust(key) {
+        RequestContext_1.RequestContext.runDetachedScope(() => {
+            // @ts-expect-error - putUntrusted needs a key KNOWN to be untrusted; AnyContextKey is mixed
+            RequestContext_1.RequestContext.putUntrusted(key, 'from-the-browser');
+        });
+    }
+    /**
+     * And a TRUSTED key cannot be LAUNDERED through the untrusted verb, detached or not — which is
+     * what a caller with no proof would have to do, since `putTrusted` is the only other way in and
+     * saying it is a deliberate, greppable claim.
+     */
+    cannotLaunderATrustedKeyThroughTheUntrustedVerb() {
+        RequestContext_1.RequestContext.runDetachedScope(() => {
+            // @ts-expect-error - putUntrusted does not accept a trusted key
+            RequestContext_1.RequestContext.putUntrusted(this.trusted, 'browser-said-so');
+        });
+    }
+    /**
+     * POSITIVE, and the point the negative above must not be mistaken for: writing a TRUSTED value
+     * inside a detached scope is ordinary and correct when the caller has actually proven it — the
+     * signed-webhook case (Twilio/WhatsApp proves the phone number, the app looks up the userId), or a
+     * verified JWT claim. `putTrusted` is the verb for exactly that, and a detached scope does not
+     * change it. Trust is about tamper-resistance, not secrecy: a trusted `userId` is a plain,
+     * fully-logged GUID; masking is the separate `maskInLogs` axis.
+     */
+    putTrustedIsLegitimateInsideADetachedScope() {
+        RequestContext_1.RequestContext.runDetachedScope(() => {
+            RequestContext_1.RequestContext.putTrusted(this.trusted, 'proven-out-of-band');
+            const proven = RequestContext_1.RequestContext.getTrusted(this.trusted);
+            void proven;
+        });
+    }
+    /**
+     * POSITIVE, and the shape the real consumer writes: emit one browser line under a fresh scope
+     * rebuilt from an EXTERNAL payload, driven off the registry's logged keys.
+     *
+     * The `isTrusted()` skip is what a reader sees; the compiler is what enforces it. Delete the skip
+     * and `isUntrusted()` still refuses the trusted key, so the trusted branch has no write at all.
+     */
+    // webpieces-disable no-any-unknown -- the EXTERNAL payload is by definition untyped JSON off the wire; that is precisely why every value below is trust-branched and typeof-checked before it is written
+    theBrowserLogLoopCompiles(loggedKeys, payload) {
+        RequestContext_1.RequestContext.runDetachedScope(() => {
+            for (const key of loggedKeys) {
+                if (key.isTrusted()) {
+                    // A browser cannot vouch for a proven fact. There is no write in this branch, and
+                    // no cast that could produce one.
+                    continue;
+                }
+                const value = payload[key.name];
+                if (key.isUntrusted() && typeof value === 'string') {
+                    RequestContext_1.RequestContext.putUntrusted(key, value);
+                }
+            }
+            RequestContext_1.RequestContext.putUntrusted(this.untrusted, 'click-7');
+        });
+    }
+    /** The return value flows through, and an async closure is a promise the caller can await. */
+    async returnValuesFlowThrough() {
+        const sync = RequestContext_1.RequestContext.runDetachedScope(() => 'done');
+        const asyncResult = await RequestContext_1.RequestContext.runDetachedScope(async () => 'done');
+        void sync;
+        void asyncResult;
+    }
+}
+exports.DetachedScopeCompileAssertions = DetachedScopeCompileAssertions;
+//# sourceMappingURL=DetachedScopeCompileAssertions.js.map

package/src/DetachedScopeCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DetachedScopeCompileAssertions.js","sourceRoot":"","sources":["../../../../../packages/core/core-context/src/DetachedScopeCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,oDAAiE;AACjE,qDAAkD;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,8BAA8B;IACtB,OAAO,GAAG,sBAAU,CAAC,OAAO,CAAS,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;IAChF,SAAS,GAAG,sBAAU,CAAC,SAAS,CAAS,wBAAwB,CAAC,CAAC;IAEpF;;;OAGG;IACH,+BAA+B;QAC3B,wFAAwF;QACxF,+BAAc,CAAC,gBAAgB,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACtF,CAAC;IAED,iFAAiF;IACjF,6BAA6B;QACzB,8EAA8E;QAC9E,+BAAc,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,oFAAoF;IACpF,0CAA0C,CAAC,GAAkB;QACzD,+BAAc,CAAC,gBAAgB,CAAC,GAAG,EAAE;YACjC,4FAA4F;YAC5F,+BAAc,CAAC,YAAY,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;OAIG;IACH,+CAA+C;QAC3C,+BAAc,CAAC,gBAAgB,CAAC,GAAG,EAAE;YACjC,gEAAgE;YAChE,+BAAc,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACjE,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;OAOG;IACH,0CAA0C;QACtC,+BAAc,CAAC,gBAAgB,CAAC,GAAG,EAAE;YACjC,+BAAc,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;YAC9D,MAAM,MAAM,GAAuB,+BAAc,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3E,KAAK,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;OAMG;IACH,yMAAyM;IACzM,yBAAyB,CAAC,UAA2B,EAAE,OAAgC;QACnF,+BAAc,CAAC,gBAAgB,CAAC,GAAG,EAAE;YACjC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC3B,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;oBAClB,kFAAkF;oBAClF,kCAAkC;oBAClC,SAAS;gBACb,CAAC;gBACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAChC,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBACjD,+BAAc,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC5C,CAAC;YACL,CAAC;YACD,+BAAc,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;IACP,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,uBAAuB;QACzB,MAAM,IAAI,GAAW,+BAAc,CAAC,gBAAgB,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QACnE,MAAM,WAAW,GAAW,MAAM,+BAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC;QACtF,KAAK,IAAI,CAAC;QACV,KAAK,WAAW,CAAC;IACrB,CAAC;CACJ;AAvFD,wEAuFC","sourcesContent":["import { AnyContextKey, ContextKey } from '@webpieces/core-util';\nimport { RequestContext } from './RequestContext';\n\n/**\n * COMPILE-TIME assertions for {@link RequestContext.runDetachedScope}.\n *\n * The runtime half — that the detached scope starts empty, that the enclosing scope survives, that a\n * throw unwinds it — is in `DetachedScope.spec.ts`. What a spec CANNOT express is the half that makes\n * the browser-log path safe BY CONSTRUCTION rather than by remembering to filter:\n *\n *  - `runDetachedScope` has NO container-taking form, so the deleted `runWithContext(map, fn)` forgery\n *    path cannot come back through this door;\n *  - a loop over a mixed `AnyContextKey[]` cannot write ANY key until it has tested that key's trust;\n *  - and a TRUSTED key can never reach `putUntrusted`, so a browser — which proves nothing — cannot\n *    FABRICATE a proven value by naming `userId` in its payload. It is a compile error at the write,\n *    not a filter someone has to remember to write.\n *\n * That is about the SOURCE, not about the key. Writing a trusted key is ordinary and legitimate — see\n * {@link putTrustedIsLegitimateInsideADetachedScope} — whenever the caller has actually proven the\n * value. What cannot be written down is a claim of proof by code that has none.\n *\n * In COMPILED source deliberately — `tsconfig.lib.json` excludes specs and vitest strips types with\n * esbuild, so a `@ts-expect-error` in a `.spec.ts` is inert and the suite would pass either way. Each\n * one below fails the build with TS2578 the day its line starts compiling. See\n * `CapturedContextCompileAssertions` and `RequestContextTrustCompileAssertions` for the sibling halves.\n */\nexport class DetachedScopeCompileAssertions {\n    private readonly trusted = ContextKey.trusted<string>('assertDetachedUserId', 'jwt claim `sub`');\n    private readonly untrusted = ContextKey.untrusted<string>('assertDetachedActionId');\n\n    /**\n     * THE hole this whole shape exists to keep shut: no Map/object/array of entries may cross the\n     * boundary. Values are written INSIDE the closure, through the trust verbs.\n     */\n    cannotHandItAContainerOfEntries(): void {\n        // @ts-expect-error - runDetachedScope takes ONLY a closure; there is no map-taking form\n        RequestContext.runDetachedScope(new Map([['userId', 'victim']]), () => undefined);\n    }\n\n    /** Nor a plain object of entries, which is the same hole spelled differently. */\n    cannotHandItAnObjectOfEntries(): void {\n        // @ts-expect-error - the single parameter is the closure, not a bag of values\n        RequestContext.runDetachedScope({ userId: 'victim' });\n    }\n\n    /** A key of unknown trust cannot be written AT ALL — the branch is not optional. */\n    cannotWriteAMixedKeyWithoutTestingItsTrust(key: AnyContextKey): void {\n        RequestContext.runDetachedScope(() => {\n            // @ts-expect-error - putUntrusted needs a key KNOWN to be untrusted; AnyContextKey is mixed\n            RequestContext.putUntrusted(key, 'from-the-browser');\n        });\n    }\n\n    /**\n     * And a TRUSTED key cannot be LAUNDERED through the untrusted verb, detached or not — which is\n     * what a caller with no proof would have to do, since `putTrusted` is the only other way in and\n     * saying it is a deliberate, greppable claim.\n     */\n    cannotLaunderATrustedKeyThroughTheUntrustedVerb(): void {\n        RequestContext.runDetachedScope(() => {\n            // @ts-expect-error - putUntrusted does not accept a trusted key\n            RequestContext.putUntrusted(this.trusted, 'browser-said-so');\n        });\n    }\n\n    /**\n     * POSITIVE, and the point the negative above must not be mistaken for: writing a TRUSTED value\n     * inside a detached scope is ordinary and correct when the caller has actually proven it — the\n     * signed-webhook case (Twilio/WhatsApp proves the phone number, the app looks up the userId), or a\n     * verified JWT claim. `putTrusted` is the verb for exactly that, and a detached scope does not\n     * change it. Trust is about tamper-resistance, not secrecy: a trusted `userId` is a plain,\n     * fully-logged GUID; masking is the separate `maskInLogs` axis.\n     */\n    putTrustedIsLegitimateInsideADetachedScope(): void {\n        RequestContext.runDetachedScope(() => {\n            RequestContext.putTrusted(this.trusted, 'proven-out-of-band');\n            const proven: string | undefined = RequestContext.getTrusted(this.trusted);\n            void proven;\n        });\n    }\n\n    /**\n     * POSITIVE, and the shape the real consumer writes: emit one browser line under a fresh scope\n     * rebuilt from an EXTERNAL payload, driven off the registry's logged keys.\n     *\n     * The `isTrusted()` skip is what a reader sees; the compiler is what enforces it. Delete the skip\n     * and `isUntrusted()` still refuses the trusted key, so the trusted branch has no write at all.\n     */\n    // webpieces-disable no-any-unknown -- the EXTERNAL payload is by definition untyped JSON off the wire; that is precisely why every value below is trust-branched and typeof-checked before it is written\n    theBrowserLogLoopCompiles(loggedKeys: AnyContextKey[], payload: Record<string, unknown>): void {\n        RequestContext.runDetachedScope(() => {\n            for (const key of loggedKeys) {\n                if (key.isTrusted()) {\n                    // A browser cannot vouch for a proven fact. There is no write in this branch, and\n                    // no cast that could produce one.\n                    continue;\n                }\n                const value = payload[key.name];\n                if (key.isUntrusted() && typeof value === 'string') {\n                    RequestContext.putUntrusted(key, value);\n                }\n            }\n            RequestContext.putUntrusted(this.untrusted, 'click-7');\n        });\n    }\n\n    /** The return value flows through, and an async closure is a promise the caller can await. */\n    async returnValuesFlowThrough(): Promise<void> {\n        const sync: string = RequestContext.runDetachedScope(() => 'done');\n        const asyncResult: string = await RequestContext.runDetachedScope(async () => 'done');\n        void sync;\n        void asyncResult;\n    }\n}\n"]}

package/src/RequestContext.d.ts

@@ -1,5 +1,6 @@
 import { ContextKey, AnyContextKey } from '@webpieces/core-util';
 import { HttpRequest } from './HttpRequest';
+import { CapturedContext, RestorableContext } from './CapturedContext';
 /**
  * Context management using AsyncLocalStorage.
  * Similar to Java WebPieces Context class that uses ThreadLocal.
@@ -28,20 +29,100 @@ declare class RequestContextImpl {
      * With this guard the setup is right or it is loud. It mirrors
      * `RequestContextHeaders.fillFromRequest()`, which throws when there is NO active scope.
      *
+     * If you genuinely WANT a fresh empty scope inside an active one — work that must not inherit the
+     * surrounding request's actionId/requestId — that is {@link runDetachedScope}, which says so by
+     * name. This guard exists to stop the ACCIDENTAL empty scope, not the deliberate one.
+     *
      * @throws Error when a RequestContext is already active.
      */
     run<T>(fn: () => T): T;
     /**
-     * Run a function with a specific context — the restore half of {@link copyContext}, used to carry
-     * a context across an async boundary (XPromise).
+     * Open a NEW scope pre-loaded with a snapshot — the restore half of {@link copyContext}, for work
+     * whose async chain was broken and re-rooted elsewhere (a queued job drained by a background loop,
+     * a batch flushed on a timer, an event listener fired from a socket the request does not own). See
+     * {@link CapturedContext} for the full list and for why the payload is opaque.
+     *
+     * A restored context legitimately contains TRUSTED values — reinstating what the original scope
+     * proved is the entire point — so this cannot type-check its contents the way the trust verbs do.
+     * The guarantee instead comes from the PAYLOAD: a {@link RestorableContext} can only be narrowed
+     * out of a {@link CapturedContext}, which only {@link copyContext} produces, so there is no
+     * hand-assembled Map to hand it and no way to forge one.
+     *
+     * The caller must SAY whether the proven identity travels — `snapshot.withTrusted()` (runs as that
+     * user) or `snapshot.withoutTrusted()` (runs as the system, keeping only the trace fields). A bare
+     * `CapturedContext` is deliberately not accepted; see {@link CapturedContext} for the three-case
+     * table and why the wide branch is spelled out rather than defaulted.
+     *
+     * The snapshot is copied into a fresh store, so writes inside `fn` stay inside `fn` and the
+     * snapshot stays reusable.
+     *
+     * Deliberately NOT guarded against nesting the way {@link run} is. `run`'s guard exists because a
+     * second EMPTY scope shadowing the first is always a bug; here the inner scope is a faithful copy
+     * of a real one, which is the whole point — a worker that restores a snapshot inside a scope it
+     * opened per job is correct, not a mistake. Prefer this over {@link restoreContext} unless you
+     * specifically need the CURRENT scope overwritten in place.
+     */
+    runWithContext<T>(captured: RestorableContext, fn: () => T): T;
+    /**
+     * Open a FRESH, EMPTY, NESTED scope. Nothing is inherited from the enclosing scope, and nothing
+     * crosses the boundary as data — every value the work runs under is WRITTEN INSIDE `fn`, through
+     * the ordinary trust-typed verbs:
+     *
+     * ```typescript
+     * RequestContext.runDetachedScope(() => {
+     *     RequestContext.putUntrusted(WebpiecesCoreHeaders.ACTION_ID, line.actionId);
+     *     emit();   // runs under exactly what this closure wrote, and nothing else
+     * });
+     * ```
+     *
+     * ## When you want THIS and not {@link runWithContext}
+     *
+     * The two look similar and are opposites. `runWithContext` faithfully RE-ROOTS a real snapshot of a
+     * real scope, for work whose async chain was broken (a queued job, a timer flush) — it exists to
+     * PRESERVE a context. This one exists to DISCARD one: the values do not come from any scope this
+     * process ever had, they were reconstructed from somewhere else, and inheriting the ambient scope
+     * would be actively wrong.
+     *
+     * The live case is a browser-log shipper. A batch of browser lines arrives on one HTTP request; each
+     * line carries the context the BROWSER captured when it was written, and a single batch routinely
+     * spans several user actions. Emitting a line under the shipping request's own scope would stamp
+     * every line with that request's actionId and requestId, silently destroying the ability to grep an
+     * action while the feature still appeared to work. So each line is emitted detached, under exactly
+     * the keys the closure re-stated from the browser's payload.
      *
-     * FRAMEWORK-INTERNAL. Unlike the raw string accessors, this deliberately CANNOT be guarded against
-     * registered key names: a restored context legitimately contains trusted values, since restoring
-     * them is the entire purpose. So the guarantee here is narrower and worth stating plainly — the
-     * Map must be one this class produced via `copyContext()`, never one assembled by hand. Handing it
-     * a hand-built Map forges whatever it contains, and no type or check will stop you.
+     * ## Why it MAY nest when {@link run} may not
+     *
+     * `run`'s nesting guard is right and is not softened here. It refuses a second EMPTY scope because
+     * there an empty scope is always an ACCIDENT — a transport opening the request scope twice, whose
+     * only effect is to hide the outer scope's values and mint a second request id. Here an empty scope
+     * is the thing that was ASKED for, in a distinctly-named verb, and the caller is normally already
+     * inside a request scope (the shipper's own). A guard would refuse the only situation the method has.
+     *
+     * ## No Map-taking form, ever
+     *
+     * There is deliberately no overload accepting a `Map`, an object, or an array of entries. That was
+     * the DELETED `runWithContext(map, fn)`, and it was a forgery path: a hand-built map is
+     * indistinguishable from a genuine snapshot, so `new Map([['userId','victim']])` minted a proven
+     * identity in one line without ever typing a trust verb. Writing the values INSIDE the closure is
+     * what closes it — a loop over a mixed `AnyContextKey[]` must branch on `key.isTrusted()` before it
+     * can write anything, and `putUntrusted` does not compile for a trusted key, so code fed by a
+     * BROWSER (which proves nothing) cannot fabricate a proven value. (See
+     * `DetachedScopeCompileAssertions`.)
+     *
+     * That is a limit on the SOURCE, not on the key. `putTrusted` inside a detached scope is ordinary
+     * and correct whenever the caller has actually proven the value — a verified JWT claim, or the
+     * signed-webhook case where Twilio/WhatsApp proves the phone number and the app looks up the
+     * userId. Trust is tamper-resistance, not secrecy (a trusted `userId` is a plain, fully-logged
+     * GUID; redaction is the separate `maskInLogs` axis on the key).
+     *
+     * SYNC AND ASYNC BOTH: `fn` may return a promise, and the detached scope follows every `await`
+     * inside it exactly as `run`/`runWithContext` do — same `AsyncLocalStorage.run` underneath. The
+     * enclosing scope is reinstated for everything after the synchronous return, INCLUDING when `fn`
+     * throws (AsyncLocalStorage unwinds the store as the frame unwinds); an async `fn` that is not
+     * awaited will therefore keep the detached scope for its own continuation while the caller has
+     * already resumed under the enclosing one, which is the intended and only sane reading of "detached".
      */
-    runWithContext<T>(context: Map<string, any>, fn: () => T): T;
+    runDetachedScope<T>(fn: () => T): T;
     /**
      * Read a value the framework PROVED — a verified JWT claim, or a fact an app derived from a
      * verified credential. Does not compile for an untrusted key, so a reader can never mistake a
@@ -193,22 +274,38 @@ declare class RequestContextImpl {
      */
     clear(): void;
     /**
-     * Copy the current context to a new Map.
-     * Used by XPromise to preserve context across async boundaries.
-     */
-    copyContext(): Map<string, any>;
-    /**
-     * Set the entire context from a Map. Used by XPromise to restore context.
+     * Snapshot this scope so the work you are about to hand off keeps its request id, log fields and
+     * proven identity. The ONLY producer of a {@link CapturedContext} — which is what makes the
+     * restore side unforgeable, since there is no other way to obtain the payload it accepts.
+     *
+     * Outside a `run(...)` block this returns an EMPTY snapshot rather than throwing: capturing "no
+     * context" is a legitimate thing for a background caller to do, and restoring it simply installs
+     * nothing.
      *
-     * Same FRAMEWORK-INTERNAL caveat as {@link runWithContext}: the Map must have come from
-     * `copyContext()`. It cannot be trust-checked, because a faithful restore has to reinstate the
-     * trusted values the original scope had proven.
+     * The snapshot is a defensive COPY — writes to this context after capturing do not reach it.
      */
-    setContext(context: Map<string, any>): void;
+    copyContext(): CapturedContext;
     /**
-     * Get all context entries.
+     * Overwrite the ACTIVE scope with a snapshot. The in-place twin of {@link runWithContext}, and the
+     * one you almost never want: prefer `runWithContext`, which gives the restored work its OWN scope
+     * and cannot disturb the caller's. Reach for this only when something else owns the scope and it
+     * must be re-pointed in place.
+     *
+     * OVERWRITE, not merge — `clear()` runs first, so every entry the active scope holds and the
+     * snapshot does not is DROPPED. That includes the empty case:
+     * `restoreContext(copyContext().withTrusted())` taken outside a scope wipes the request id and
+     * every proven identity from a live request, and says nothing. That is faithful (a snapshot
+     * restores exactly what it captured) but it is the sharp edge of this method and the reason
+     * `runWithContext` is the default.
+     *
+     * Takes only a {@link RestorableContext} for the reason spelled out there — the DELETED Map-taking
+     * form let `new Map([['userId','victim']])` forge a proven identity in one line — and that type
+     * exists only via `withTrusted()` / `withoutTrusted()`, so this call site states whether the proven
+     * identity survives the re-point.
+     *
+     * @throws Error when no RequestContext is active.
      */
-    getAll(): Map<string, any>;
+    restoreContext(captured: RestorableContext): void;
     /**
      * Check if a key exists in the context.
      */