@btravstack/testing 0.11.0 → 0.13.0

package/README.md

@@ -11,7 +11,6 @@ declare const OrderApi: Module<
   never,
   Env | Scope
 >;
-declare const RequestModule: Module<never, never, Logger>;
 -->
 
 # @btravstack/testing
@@ -35,7 +34,9 @@ pnpm add -D @btravstack/testing @btravstack/core @btravstack/config @btravstack/
 peer dependencies; the package depends on nothing else — not even `vitest`:
 `bootFixture` is a plain `(ctx, use) => Promise<void>` function, which is
 vitest's fixture protocol, so no import is needed to hand it to `test.extend`.
-Node `>=22`.
+`jose` is an **optional** peer behind the `@btravstack/testing/jwt` subpath —
+see below — so a consumer that never imports it installs nothing extra. Node
+`>=22`.
 
 ## A booted application, as a fixture
 
@@ -48,7 +49,7 @@ const it = test.extend<{ boot: Boot }>({
 });
 
 it("serves on an ephemeral port", async ({ boot }) => {
-  const app = boot(OrderApi, { unit: RequestModule });
+  const app = boot(OrderApi);
 
   await expect(app.runtimeInfo()).toBeOkWith(
     expect.objectContaining({ port: expect.any(Number) }),
@@ -57,7 +58,7 @@ it("serves on an ephemeral port", async ({ boot }) => {
 
 it("holds the very logger the use cases write to", async ({ boot }) => {
   const tap = tapped(OrderApi, [Logger]);
-  await boot(tap.module, { unit: RequestModule }).runtimeInfo();
+  await boot(tap.module).runtimeInfo();
 
   const [logger] = tap.services();
   expect(logger.lines()).toEqual([]);
@@ -85,15 +86,43 @@ answers the very instances the running graph holds once it is built — after
   are its types.
 - **`tapped(module, ports)`** → `{ module, services() }` — read services out
   of a booted application.
-- **`testRuntime(name?)`** / **`TestRuntimePort`** — an in-memory `Runtime`
-  with `submit()` to hold a unit open across a drain, and a `module` that
-  provides it where a starter would.
+- **`testRuntime(name?, { unit? })`** / **`TestRuntimePort`** — an in-memory
+  `Runtime` with `submit()` to hold a unit open across a drain, `host()` to
+  reach the `RuntimeHost` it was last started with, and a `module` that
+  provides it where a starter would; `unit` is a module every submitted unit
+  forks, with no seed, before its work runs — and what that module needs joins
+  `module`'s own, so `start` names it instead of the first `submit()` failing.
 - **`createFakeClock(start?)`** — a `Clock` for `StartOptions.clock` whose
   time moves only on `advance(ms)`.
 
 The teardown rule: a `Defect` on `exited` fails the test, a modeled `Err` does
 not.
 
+## A local JWT issuer, on its own subpath
+
+```ts
+import { localIssuer } from "@btravstack/testing/jwt";
+
+const issuer = await localIssuer({
+  issuer: "https://issuer.test",
+  audience: "orders-api",
+}).get();
+
+const token = await issuer.sign({ sub: "u-1" }).get();
+// verify `token` against `issuer.jwks`, the same way a real JWKS would be
+await issuer.close();
+```
+
+`@btravstack/testing/jwt`'s `localIssuer(options)` mints a generated key
+pair, a `node:http` listener answering its public key as a JWKS, and a
+`sign(claims?, options?)` closing over the private key — a real fetch against
+a real JWKS document, for a test that wants the verifying library's own
+behaviour rather than a double's. `sign`'s `expiresIn: false` mints a token
+with no `exp` claim; `localIssuer`'s `algorithm` picks the asymmetric algorithm
+(default `"RS256"`). The subpath needs Node ≥22.12 under CommonJS — `jose` is
+ESM-only, so the CJS build's `require("jose")` depends on `require(esm)`;
+ESM consumers, and anyone who never imports the subpath, are unaffected.
+
 ## License
 
 [MIT](./LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -15,7 +15,7 @@ let _btravstack_di = require("@btravstack/di");
 * });
 *
 * it("answers", async ({ boot }) => {
-*   const app = boot(OrderApi, { unit: RequestModule });
+*   const app = boot(OrderApi);
 *   …
 * });
 * ```
@@ -154,8 +154,8 @@ var Tap = class extends (0, _btravstack_di.Port)("@btravstack/testing/Tap") {};
 //#region src/test-runtime.ts
 /** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
 var TestRuntimePort = class extends _btravstack_core.RuntimePort {};
-const testRuntime = (name = "test") => {
-	let run;
+const testRuntime = (name = "test", options = {}) => {
+	let host;
 	let accepting = false;
 	let serving;
 	let submitted = 0;
@@ -184,8 +184,8 @@ const testRuntime = (name = "test") => {
 			exports: [TestRuntimePort]
 		}),
 		resolves: [],
-		start: (host) => {
-			run = host.run;
+		start: (h) => {
+			host = h;
 			accepting = true;
 			serving = make();
 			onStarted();
@@ -198,21 +198,26 @@ const testRuntime = (name = "test") => {
 			if (serving === void 0) throw new Error("[test-runtime] not started");
 			return serving;
 		},
+		host: () => {
+			if (host === void 0) throw new Error("[test-runtime] not started");
+			return host;
+		},
 		submit: () => {
-			if (run === void 0 || !accepting) throw new Error("[test-runtime] not accepting work");
+			if (host === void 0 || !accepting) throw new Error("[test-runtime] not accepting work");
 			submitted += 1;
 			let settle;
 			const held = new Promise((resolve) => {
 				settle = resolve;
 			});
 			const forwarded = new AbortController();
-			const result = run({
+			const unit = options.unit;
+			const result = host.run({
 				kind: "test",
 				id: `${submitted}`
-			}, (_ctx, signal) => {
+			}, (unitHost, signal) => {
 				if (signal.aborted) forwarded.abort(signal.reason);
 				else signal.addEventListener("abort", () => forwarded.abort(signal.reason), { once: true });
-				return held;
+				return unit === void 0 ? held : unitHost.fork(unit, []).flatMap(() => (0, unthrown.fromSafePromise)(held).flatMap((r) => r));
 			});
 			return {
 				settle,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Clock, RunningApp, Runtime, RuntimeInfoOf, RuntimePort, Serving, StartGate, StartOptions } from "@btravstack/core";
-import { AnyPort, Module, Provider, ServiceOf } from "@btravstack/di";
+import { Clock, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, RuntimePort, Serving, StartGate, StartOptions } from "@btravstack/core";
+import { AnyPort, Module, Provider, Scope, ServiceOf } from "@btravstack/di";
 import { AsyncResult, Result } from "unthrown";
 //#region src/boot-fixture.d.ts
 /**
@@ -7,9 +7,9 @@ import { AsyncResult, Result } from "unthrown";
  * gate, minus `signals` (always off) — every application it starts is stopped
  * when the test ends.
  */
-type Boot = <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: Omit<StartOptions<UnitX, UnitNeeds>, "signals">) => RunningApp<E, RuntimeInfoOf<X>>;
+type Boot = <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: Omit<StartOptions, "signals">) => RunningApp<E, RuntimeInfoOf<X>>;
 /** What every `boot` in the fixture starts with; a call's own options win. */
-type BootDefaults = Omit<StartOptions, "signals" | "unit">;
+type BootDefaults = Omit<StartOptions, "signals">;
 /**
  * A `test.extend` fixture that hands the test a {@link Boot} and stops every
  * application it started once the test is over — on every exit path, a failing
@@ -21,7 +21,7 @@ type BootDefaults = Omit<StartOptions, "signals" | "unit">;
  * });
  *
  * it("answers", async ({ boot }) => {
- *   const app = boot(OrderApi, { unit: RequestModule });
+ *   const app = boot(OrderApi);
  *   …
  * });
  * ```
@@ -142,7 +142,26 @@ type TestRuntimeInfo = {
 };
 /** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
 declare class TestRuntimePort extends RuntimePort<Runtime<never, TestRuntimeInfo>> {}
-type TestRuntime = Runtime<never, TestRuntimeInfo> & {
+/**
+ * A module `options.unit` may bind, as the upper bound `testRuntime`
+ * constrains its own `Unit` type parameter to. `Module`'s `_exports` channel is
+ * contravariant, so `Exports = never` — never `unknown` — is what makes a REAL
+ * module's own (necessarily narrower) export type assignable to this bound.
+ * `@btravstack/http-server`'s `AnyUnitModule` carries the same bound for the
+ * same reason.
+ */
+type AnyUnitModule = Module<never, never, unknown>;
+/**
+ * The needs a bound `unit` module still owes, or `never` when none is bound.
+ * `Scope` is excluded, since nothing can ever provide it — the same exemption
+ * `NeedsGate` itself carries.
+ */
+type UnitNeedsOf<Unit> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope> : never;
+type TestRuntimeOptions<Unit extends AnyUnitModule | undefined = undefined> = {
+  /** A module every submitted unit forks, with no seed, before its work runs. */
+  readonly unit?: Unit;
+};
+type TestRuntime<Unit extends AnyUnitModule | undefined = undefined> = Runtime<never, TestRuntimeInfo> & {
   /**
    * A module providing this very runtime on `TestRuntimePort`: import it next
    * to the module under test, export the port, and `start` finds it.
@@ -150,8 +169,14 @@ type TestRuntime = Runtime<never, TestRuntimeInfo> & {
    * It provides THIS object, so a wrapper built by spreading copies the module
    * too and that module still boots the inner runtime — a wrapper needs a module
    * of its own.
+   *
+   * Its Needs channel carries a bound `unit` module's own unmet needs, though
+   * nothing here reads them: the module is forked over the application context
+   * per unit, so what it needs is exactly what the test composition must
+   * supply — and this is what makes `start`'s `UNSATISFIED DEPENDENCIES` say so
+   * at boot instead of leaving a `WiringDefect` for the first `submit()`.
    */
-  readonly module: Module<TestRuntimePort, never, never>;
+  readonly module: Module<TestRuntimePort, never, UnitNeedsOf<Unit>>;
   readonly started: () => boolean;
   /** Resolves the first time the kernel calls `start` — `start` itself stays pending until shutdown. */
   readonly untilStarted: () => AsyncResult<void, never>;
@@ -163,7 +188,9 @@ type TestRuntime = Runtime<never, TestRuntimeInfo> & {
   readonly accepting: () => boolean;
   readonly serving: () => Serving<TestRuntimeInfo>;
   readonly submit: <T = string, E = never>() => SubmittedUnit<T, E>;
+  /** The `RuntimeHost` the kernel last called `start` with. **Throws** if the runtime was never started — the same misuse guard as `serving()`. */
+  readonly host: () => RuntimeHost<never>;
 };
-declare const testRuntime: (name?: string) => TestRuntime;
+declare const testRuntime: <Unit extends AnyUnitModule | undefined = undefined>(name?: string, options?: TestRuntimeOptions<Unit>) => TestRuntime<Unit>;
 //#endregion
-export { type Boot, type BootDefaults, type FakeClock, type ServicesOf, type SubmittedUnit, type TestRuntime, type TestRuntimeInfo, TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };
+export { type Boot, type BootDefaults, type FakeClock, type ServicesOf, type SubmittedUnit, type TestRuntime, type TestRuntimeInfo, type TestRuntimeOptions, TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };

package/dist/index.d.mts

@@ -1,15 +1,15 @@
-import { Clock, RunningApp, Runtime, RuntimeInfoOf, RuntimePort, Serving, StartGate, StartOptions } from "@btravstack/core";
+import { Clock, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, RuntimePort, Serving, StartGate, StartOptions } from "@btravstack/core";
 import { AsyncResult, Result } from "unthrown";
-import { AnyPort, Module, Provider, ServiceOf } from "@btravstack/di";
+import { AnyPort, Module, Provider, Scope, ServiceOf } from "@btravstack/di";
 //#region src/boot-fixture.d.ts
 /**
  * `start`, as a test hands it out: the same signature and the same phantom
  * gate, minus `signals` (always off) — every application it starts is stopped
  * when the test ends.
  */
-type Boot = <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: Omit<StartOptions<UnitX, UnitNeeds>, "signals">) => RunningApp<E, RuntimeInfoOf<X>>;
+type Boot = <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: Omit<StartOptions, "signals">) => RunningApp<E, RuntimeInfoOf<X>>;
 /** What every `boot` in the fixture starts with; a call's own options win. */
-type BootDefaults = Omit<StartOptions, "signals" | "unit">;
+type BootDefaults = Omit<StartOptions, "signals">;
 /**
  * A `test.extend` fixture that hands the test a {@link Boot} and stops every
  * application it started once the test is over — on every exit path, a failing
@@ -21,7 +21,7 @@ type BootDefaults = Omit<StartOptions, "signals" | "unit">;
  * });
  *
  * it("answers", async ({ boot }) => {
- *   const app = boot(OrderApi, { unit: RequestModule });
+ *   const app = boot(OrderApi);
  *   …
  * });
  * ```
@@ -142,7 +142,26 @@ type TestRuntimeInfo = {
 };
 /** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
 declare class TestRuntimePort extends RuntimePort<Runtime<never, TestRuntimeInfo>> {}
-type TestRuntime = Runtime<never, TestRuntimeInfo> & {
+/**
+ * A module `options.unit` may bind, as the upper bound `testRuntime`
+ * constrains its own `Unit` type parameter to. `Module`'s `_exports` channel is
+ * contravariant, so `Exports = never` — never `unknown` — is what makes a REAL
+ * module's own (necessarily narrower) export type assignable to this bound.
+ * `@btravstack/http-server`'s `AnyUnitModule` carries the same bound for the
+ * same reason.
+ */
+type AnyUnitModule = Module<never, never, unknown>;
+/**
+ * The needs a bound `unit` module still owes, or `never` when none is bound.
+ * `Scope` is excluded, since nothing can ever provide it — the same exemption
+ * `NeedsGate` itself carries.
+ */
+type UnitNeedsOf<Unit> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope> : never;
+type TestRuntimeOptions<Unit extends AnyUnitModule | undefined = undefined> = {
+  /** A module every submitted unit forks, with no seed, before its work runs. */
+  readonly unit?: Unit;
+};
+type TestRuntime<Unit extends AnyUnitModule | undefined = undefined> = Runtime<never, TestRuntimeInfo> & {
   /**
    * A module providing this very runtime on `TestRuntimePort`: import it next
    * to the module under test, export the port, and `start` finds it.
@@ -150,8 +169,14 @@ type TestRuntime = Runtime<never, TestRuntimeInfo> & {
    * It provides THIS object, so a wrapper built by spreading copies the module
    * too and that module still boots the inner runtime — a wrapper needs a module
    * of its own.
+   *
+   * Its Needs channel carries a bound `unit` module's own unmet needs, though
+   * nothing here reads them: the module is forked over the application context
+   * per unit, so what it needs is exactly what the test composition must
+   * supply — and this is what makes `start`'s `UNSATISFIED DEPENDENCIES` say so
+   * at boot instead of leaving a `WiringDefect` for the first `submit()`.
    */
-  readonly module: Module<TestRuntimePort, never, never>;
+  readonly module: Module<TestRuntimePort, never, UnitNeedsOf<Unit>>;
   readonly started: () => boolean;
   /** Resolves the first time the kernel calls `start` — `start` itself stays pending until shutdown. */
   readonly untilStarted: () => AsyncResult<void, never>;
@@ -163,7 +188,9 @@ type TestRuntime = Runtime<never, TestRuntimeInfo> & {
   readonly accepting: () => boolean;
   readonly serving: () => Serving<TestRuntimeInfo>;
   readonly submit: <T = string, E = never>() => SubmittedUnit<T, E>;
+  /** The `RuntimeHost` the kernel last called `start` with. **Throws** if the runtime was never started — the same misuse guard as `serving()`. */
+  readonly host: () => RuntimeHost<never>;
 };
-declare const testRuntime: (name?: string) => TestRuntime;
+declare const testRuntime: <Unit extends AnyUnitModule | undefined = undefined>(name?: string, options?: TestRuntimeOptions<Unit>) => TestRuntime<Unit>;
 //#endregion
-export { type Boot, type BootDefaults, type FakeClock, type ServicesOf, type SubmittedUnit, type TestRuntime, type TestRuntimeInfo, TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };
+export { type Boot, type BootDefaults, type FakeClock, type ServicesOf, type SubmittedUnit, type TestRuntime, type TestRuntimeInfo, type TestRuntimeOptions, TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };

package/dist/index.mjs

@@ -14,7 +14,7 @@ import { Module, Port, Provider, overrideProvider } from "@btravstack/di";
 * });
 *
 * it("answers", async ({ boot }) => {
-*   const app = boot(OrderApi, { unit: RequestModule });
+*   const app = boot(OrderApi);
 *   …
 * });
 * ```
@@ -153,8 +153,8 @@ var Tap = class extends Port("@btravstack/testing/Tap") {};
 //#region src/test-runtime.ts
 /** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
 var TestRuntimePort = class extends RuntimePort {};
-const testRuntime = (name = "test") => {
-	let run;
+const testRuntime = (name = "test", options = {}) => {
+	let host;
 	let accepting = false;
 	let serving;
 	let submitted = 0;
@@ -183,8 +183,8 @@ const testRuntime = (name = "test") => {
 			exports: [TestRuntimePort]
 		}),
 		resolves: [],
-		start: (host) => {
-			run = host.run;
+		start: (h) => {
+			host = h;
 			accepting = true;
 			serving = make();
 			onStarted();
@@ -197,21 +197,26 @@ const testRuntime = (name = "test") => {
 			if (serving === void 0) throw new Error("[test-runtime] not started");
 			return serving;
 		},
+		host: () => {
+			if (host === void 0) throw new Error("[test-runtime] not started");
+			return host;
+		},
 		submit: () => {
-			if (run === void 0 || !accepting) throw new Error("[test-runtime] not accepting work");
+			if (host === void 0 || !accepting) throw new Error("[test-runtime] not accepting work");
 			submitted += 1;
 			let settle;
 			const held = new Promise((resolve) => {
 				settle = resolve;
 			});
 			const forwarded = new AbortController();
-			const result = run({
+			const unit = options.unit;
+			const result = host.run({
 				kind: "test",
 				id: `${submitted}`
-			}, (_ctx, signal) => {
+			}, (unitHost, signal) => {
 				if (signal.aborted) forwarded.abort(signal.reason);
 				else signal.addEventListener("abort", () => forwarded.abort(signal.reason), { once: true });
-				return held;
+				return unit === void 0 ? held : unitHost.fork(unit, []).flatMap(() => fromSafePromise(held).flatMap((r) => r));
 			});
 			return {
 				settle,

package/dist/jwt.cjs

@@ -0,0 +1,49 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let unthrown = require("unthrown");
+let node_http = require("node:http");
+let jose = require("jose");
+//#region src/jwt.ts
+const KID = "k1";
+/**
+* A real JWKS endpoint and a matching signer, for a test that wants a genuine
+* fetch and a genuine verify rather than a double for either.
+*
+* The whole `LocalIssuer` is minted from one call: a key pair, a `node:http`
+* listener answering the JWKS on any path, and `sign` closing over the
+* private key. `close()` stops the listener; nothing else needs tearing down.
+*/
+const localIssuer = (options) => {
+	const algorithm = options.algorithm ?? "RS256";
+	return (0, unthrown.fromSafePromise)((async () => {
+		const { publicKey, privateKey } = await (0, jose.generateKeyPair)(algorithm, { extractable: true });
+		const jwk = {
+			...await (0, jose.exportJWK)(publicKey),
+			kid: KID,
+			alg: algorithm,
+			use: "sig"
+		};
+		const server = (0, node_http.createServer)((_request, response) => {
+			response.setHeader("content-type", "application/json");
+			response.end(JSON.stringify({ keys: [jwk] }));
+		});
+		await new Promise((done) => server.listen(0, "127.0.0.1", done));
+		const { port } = server.address();
+		return {
+			jwks: `http://127.0.0.1:${port}/jwks.json`,
+			jwk,
+			issuer: options.issuer,
+			audience: options.audience,
+			sign: (claims = {}, signOptions = {}) => (0, unthrown.fromSafePromise)((async () => {
+				const token = new jose.SignJWT(claims).setProtectedHeader({
+					alg: algorithm,
+					kid: KID
+				}).setIssuer(signOptions.issuer ?? options.issuer).setAudience(signOptions.audience ?? options.audience).setIssuedAt();
+				if (signOptions.expiresIn !== false) token.setExpirationTime(signOptions.expiresIn ?? "5m");
+				return token.sign(privateKey);
+			})()),
+			close: () => (0, unthrown.fromSafePromise)(new Promise((done) => server.close(() => done())))
+		};
+	})());
+};
+//#endregion
+exports.localIssuer = localIssuer;

package/dist/jwt.d.cts

@@ -0,0 +1,36 @@
+import { AsyncResult } from "unthrown";
+import { JWK, JWTPayload } from "jose";
+//#region src/jwt.d.ts
+type LocalIssuerOptions = {
+  readonly issuer: string;
+  readonly audience: string;
+  /** Asymmetric only, the same list `jwtAuthenticator` accepts; default `"RS256"`. */
+  readonly algorithm?: "RS256" | "RS384" | "RS512" | "ES256" | "ES384";
+};
+type SignOptions = {
+  readonly issuer?: string;
+  readonly audience?: string;
+  /** `"5m"` by default; `false` mints a token with no `exp` at all. */
+  readonly expiresIn?: string | false;
+};
+type LocalIssuer = {
+  /** `http://127.0.0.1:<port>/jwks.json` — served on ANY path, so a caller need not match it exactly. */
+  readonly jwks: string;
+  /** The public key as served, with `kid`/`alg`/`use` already set. */
+  readonly jwk: JWK;
+  readonly issuer: string;
+  readonly audience: string;
+  readonly sign: (claims?: JWTPayload, options?: SignOptions) => AsyncResult<string, never>;
+  readonly close: () => AsyncResult<void, never>;
+};
+/**
+ * A real JWKS endpoint and a matching signer, for a test that wants a genuine
+ * fetch and a genuine verify rather than a double for either.
+ *
+ * The whole `LocalIssuer` is minted from one call: a key pair, a `node:http`
+ * listener answering the JWKS on any path, and `sign` closing over the
+ * private key. `close()` stops the listener; nothing else needs tearing down.
+ */
+declare const localIssuer: (options: LocalIssuerOptions) => AsyncResult<LocalIssuer, never>;
+//#endregion
+export { LocalIssuer, LocalIssuerOptions, SignOptions, localIssuer };

package/dist/jwt.d.mts

@@ -0,0 +1,36 @@
+import { AsyncResult } from "unthrown";
+import { JWK, JWTPayload } from "jose";
+//#region src/jwt.d.ts
+type LocalIssuerOptions = {
+  readonly issuer: string;
+  readonly audience: string;
+  /** Asymmetric only, the same list `jwtAuthenticator` accepts; default `"RS256"`. */
+  readonly algorithm?: "RS256" | "RS384" | "RS512" | "ES256" | "ES384";
+};
+type SignOptions = {
+  readonly issuer?: string;
+  readonly audience?: string;
+  /** `"5m"` by default; `false` mints a token with no `exp` at all. */
+  readonly expiresIn?: string | false;
+};
+type LocalIssuer = {
+  /** `http://127.0.0.1:<port>/jwks.json` — served on ANY path, so a caller need not match it exactly. */
+  readonly jwks: string;
+  /** The public key as served, with `kid`/`alg`/`use` already set. */
+  readonly jwk: JWK;
+  readonly issuer: string;
+  readonly audience: string;
+  readonly sign: (claims?: JWTPayload, options?: SignOptions) => AsyncResult<string, never>;
+  readonly close: () => AsyncResult<void, never>;
+};
+/**
+ * A real JWKS endpoint and a matching signer, for a test that wants a genuine
+ * fetch and a genuine verify rather than a double for either.
+ *
+ * The whole `LocalIssuer` is minted from one call: a key pair, a `node:http`
+ * listener answering the JWKS on any path, and `sign` closing over the
+ * private key. `close()` stops the listener; nothing else needs tearing down.
+ */
+declare const localIssuer: (options: LocalIssuerOptions) => AsyncResult<LocalIssuer, never>;
+//#endregion
+export { LocalIssuer, LocalIssuerOptions, SignOptions, localIssuer };

package/dist/jwt.mjs

@@ -0,0 +1,48 @@
+import { fromSafePromise } from "unthrown";
+import { createServer } from "node:http";
+import { SignJWT, exportJWK, generateKeyPair } from "jose";
+//#region src/jwt.ts
+const KID = "k1";
+/**
+* A real JWKS endpoint and a matching signer, for a test that wants a genuine
+* fetch and a genuine verify rather than a double for either.
+*
+* The whole `LocalIssuer` is minted from one call: a key pair, a `node:http`
+* listener answering the JWKS on any path, and `sign` closing over the
+* private key. `close()` stops the listener; nothing else needs tearing down.
+*/
+const localIssuer = (options) => {
+	const algorithm = options.algorithm ?? "RS256";
+	return fromSafePromise((async () => {
+		const { publicKey, privateKey } = await generateKeyPair(algorithm, { extractable: true });
+		const jwk = {
+			...await exportJWK(publicKey),
+			kid: KID,
+			alg: algorithm,
+			use: "sig"
+		};
+		const server = createServer((_request, response) => {
+			response.setHeader("content-type", "application/json");
+			response.end(JSON.stringify({ keys: [jwk] }));
+		});
+		await new Promise((done) => server.listen(0, "127.0.0.1", done));
+		const { port } = server.address();
+		return {
+			jwks: `http://127.0.0.1:${port}/jwks.json`,
+			jwk,
+			issuer: options.issuer,
+			audience: options.audience,
+			sign: (claims = {}, signOptions = {}) => fromSafePromise((async () => {
+				const token = new SignJWT(claims).setProtectedHeader({
+					alg: algorithm,
+					kid: KID
+				}).setIssuer(signOptions.issuer ?? options.issuer).setAudience(signOptions.audience ?? options.audience).setIssuedAt();
+				if (signOptions.expiresIn !== false) token.setExpirationTime(signOptions.expiresIn ?? "5m");
+				return token.sign(privateKey);
+			})()),
+			close: () => fromSafePromise(new Promise((done) => server.close(() => done())))
+		};
+	})());
+};
+//#endregion
+export { localIssuer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/testing",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Test the applications @btravstack/core boots: an in-memory runtime, a fake clock, a boot fixture that stops what it started, and a tap into a running graph",
   "keywords": [
     "dependency-injection",
@@ -41,34 +41,52 @@
         "default": "./dist/index.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./jwt": {
+      "import": {
+        "types": "./dist/jwt.d.mts",
+        "default": "./dist/jwt.mjs"
+      },
+      "require": {
+        "types": "./dist/jwt.d.cts",
+        "default": "./dist/jwt.cjs"
+      }
+    }
   },
   "devDependencies": {
-    "@btravstack/tsconfig": "0.2.0",
+    "@btravstack/tsconfig": "0.4.0",
     "@types/node": "26.4.0",
     "@unthrown/vitest": "5.7.0",
     "@vitest/coverage-v8": "4.1.11",
+    "jose": "6.2.10",
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.11.0",
-    "@btravstack/core": "0.11.0",
-    "@btravstack/di": "0.11.0"
+    "@btravstack/config": "0.13.0",
+    "@btravstack/core": "0.13.0",
+    "@btravstack/di": "0.13.0"
   },
   "peerDependencies": {
+    "jose": "^6",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.11.0",
-    "@btravstack/core": "^0.11.0",
-    "@btravstack/di": "^0.11.0"
+    "@btravstack/config": "^0.13.0",
+    "@btravstack/core": "^0.13.0",
+    "@btravstack/di": "^0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "jose": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsdown src/index.ts src/jwt.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts src/jwt.ts --format cjs,esm --dts --watch",
     "test": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "test:types": "tsc --noEmit -p tsconfig.test-d.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
   }
 }