@shivaedev/test-story 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.10.0 - 2026-10-18
+
+### Added
+
+- Platform exports `authTestUtils(options?)` and `signedInUser(auth, fields)` from `server/better-auth/testing.ts` for typed Better Auth test utilities and signed-in story preconditions with user fields and roles, without OAuth or password hashing.
+- Test-story exports `seedCookies(cookies)` and `DomCookie` from `seedCookies.ts` to seed happy-dom's cookie container, including HttpOnly session cookies accepted by a real HTTP host.
+
+## 0.9.0 - 2026-10-18
+
+### Added
+
+- `forwardingProxy(upstream, options?)` and `ForwardingProxyOptions` from `@shivaedev/test-story/forwardingProxy.ts` provide a scoped loopback proxy for host stories. It forwards requests and responses, appends the caller to `x-forwarded-for`, and applies the story's configured headers.
+
 ## 0.8.0 - 2026-10-18
 
 ### Added

package/README.md

@@ -233,6 +233,24 @@ app.it("a request continues its supplied trace", [], function* ({ request, reque
 
 Detachment only removes the incoming parent: spans that application startup explicitly creates still follow native Effect semantics.
 
+#### Forwarding requests to a host
+
+Use `forwardingProxy` from `@shivaedev/test-story/forwardingProxy.ts` in the kit's scoped `create` or `after` hook after starting the host under test:
+
+```ts
+import { forwardingProxy } from "@shivaedev/test-story/forwardingProxy.ts";
+
+const proxy = yield* forwardingProxy(upstream, {
+  headers: {
+    host: "internal.test",
+    "x-forwarded-host": "app.example",
+    "x-forwarded-proto": "https",
+  },
+});
+```
+
+Point story requests at `proxy.url`. The proxy listens on IPv4 and IPv6 loopback on the same allocated port, forwards the request's method, path, query, body and headers to `upstream`, and returns the host's status, headers and body. It appends the connecting caller's address to `x-forwarded-for`, preserving any existing chain. The optional `headers` map overrides incoming and generated headers, including `x-forwarded-for` when the story needs a fixed chain. The proxy returns 502 if it cannot connect to the host. Both listeners close with the story's Scope.
+
 #### Reading OTLP exports
 
 Use `otlpReceiver` from `@shivaedev/test-story/otlpReceiver.ts` in a kit's scoped `create` hook. It listens on an allocated loopback port and closes with the story scope. Point the application's real exporter at `${receiver.url}/v1/traces`, then flush the exporter before reading:
@@ -459,6 +477,23 @@ const cookieApp = storyKit({
 
 `startHost`, `postgres` and `authVerbs` are application plumbing. Actions in `authVerbs` perform requests, and readouts return response data for assertions in the spec. A sign-in story drives its real sign-in flow; feature stories start from a faked signed-in precondition as described in the shared skill.
 
+#### Seeding a signed-in precondition
+
+`seedCookies(cookies)` from `@shivaedev/test-story/seedCookies.ts` returns an Effect that seeds the current happy-dom window's cookie container, including HttpOnly cookies. Call `domFetch(baseUrl)` first so the document and requests use the same origin. Each cookie has `name` and `value`, with optional `domain`, `path`, `httpOnly`, `secure`, `sameSite` (`Lax`, `Strict` or `None`) and `expires` (Unix seconds). Better Auth's test-utils login cookies fit this shape directly.
+
+```ts
+import { signedInUser } from "@shivaedev/platform/server/better-auth/testing.ts";
+import { seedCookies } from "@shivaedev/test-story/seedCookies.ts";
+
+const { cookies } = yield* Effect.promise(() => signedInUser(testAuth, {
+  email: "alice@example.test",
+  name: "Alice",
+}));
+yield* seedCookies(cookies);
+```
+
+`testAuth` is a test-only auth instance configured with Platform's `authTestUtils()` and the real host's database, secret and cookie policy. The seeded session travels on the document's fetch and stays hidden from `document.cookie` when HttpOnly. Use `http://localhost:<port>` for local DOM hosts with secure cookies: happy-dom matches secure cookies on localhost, but not on `http://127.0.0.1`. The listener can still bind to `127.0.0.1`.
+
 #### Social sign-in through an outbound provider
 
 Happy-dom's detached window records a location change without loading the next document. `domNavigate(url = window.location.href)` from `@shivaedev/test-story/domNavigate.ts` performs that load: it follows HTTP redirects through the document transport, keeps cookies for each destination, sets the final location, writes the returned HTML and returns the happy-dom response. Call it after the sign-in client has set the provider location, and before checking the returned page. An unrouted external redirect fails with its hostname.
@@ -513,12 +548,14 @@ Import each module with the prefix `@shivaedev/test-story/`; there is no root en
 | --- | --- |
 | `storyKit.ts` | `storyKit`, `Trait`, `RunUntilOptions`, `Story`, `RunHooks`, `StoryKitDefinition`, `Told`, `StoryBody`, `StoryTest`, `StoryIt`, `StoryKit` |
 | `domFetch.ts` | `domFetch(baseUrl)` |
+| `seedCookies.ts` | `seedCookies(cookies)`, `DomCookie` |
 | `routeOutbound.ts` | `routeOutbound(routes)` |
 | `screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver` |
 | `domNavigate.ts` | `domNavigate(url?)` |
 | `genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
 | `domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
 | `fakeHttpService.ts` | `fakeHttpService(options)`, `FakeHttpRoute`, `FakeHttpRequest`, `FakeHttpReply`, `FakeHttpHold`, `FakeHttpServiceOptions` |
+| `forwardingProxy.ts` | `forwardingProxy(upstream, options?)`, `ForwardingProxyOptions` |
 | `otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
 
 ### Install and limits

package/dist/server/forwardingProxy.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+export interface ForwardingProxyOptions {
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare const forwardingProxy: (upstream: string, options?: ForwardingProxyOptions | undefined) => Effect.Effect<{
+    url: string;
+}, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+//# sourceMappingURL=forwardingProxy.d.ts.map

package/dist/server/forwardingProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwardingProxy.d.ts","sourceRoot":"","sources":["../../src/server/forwardingProxy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,eAAO,MAAM,eAAe;;qEA8B1B,CAAC"}

package/dist/server/forwardingProxy.js

@@ -0,0 +1,32 @@
+import { createServer, request } from "node:http";
+import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
+export const forwardingProxy = Effect.fnUntraced(function* (upstream, options = {}) {
+    const forward = (incoming, response) => {
+        const outgoing = request(`${upstream}${incoming.url}`, {
+            headers: {
+                ...incoming.headers,
+                "x-forwarded-for": [incoming.headers["x-forwarded-for"], incoming.socket.remoteAddress].filter(Boolean).join(", "),
+                ...options.headers,
+            },
+            method: incoming.method,
+        }, (result) => {
+            response.writeHead(result.statusCode ?? 502, result.headers);
+            result.pipe(response);
+        });
+        outgoing.on("error", (error) => {
+            if (response.headersSent) {
+                response.destroy(error);
+            }
+            else {
+                response.writeHead(502).end();
+            }
+        });
+        response.on("close", () => outgoing.destroy());
+        incoming.pipe(outgoing);
+    };
+    const url = yield* loopbackServer(createServer(forward));
+    yield* loopbackServer(createServer(forward), { host: "::1", port: Number(new URL(url).port) });
+    return { url };
+});
+//# sourceMappingURL=forwardingProxy.js.map

package/dist/server/forwardingProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwardingProxy.js","sourceRoot":"","sources":["../../src/server/forwardingProxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAwB,OAAO,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAMvD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,QAAgB,EAAE,OAAO,GAA2B,EAAE;IACjH,MAAM,OAAO,GAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE;QACvD,MAAM,QAAQ,GAAG,OAAO,CACvB,GAAG,QAAQ,GAAG,QAAQ,CAAC,GAAG,EAAE,EAC5B;YACC,OAAO,EAAE;gBACR,GAAG,QAAQ,CAAC,OAAO;gBACnB,iBAAiB,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBAClH,GAAG,OAAO,CAAC,OAAO;aAClB;YACD,MAAM,EAAE,QAAQ,CAAC,MAAM;SACvB,EACD,CAAC,MAAM,EAAE,EAAE;YACV,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,IAAI,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7D,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC,CACD,CAAC;QACF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC9B,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;gBAC1B,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACP,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC/B,CAAC;QACF,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/C,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC,CAAC;IACF,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IACzD,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/F,OAAO,EAAE,GAAG,EAAE,CAAC;AAChB,CAAC,CAAC,CAAC"}

package/dist/server/internal/loopback.d.ts

@@ -1,4 +1,7 @@
 import type { Server } from "node:http";
 import { Effect } from "effect";
-export declare const loopbackServer: (server: Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>) => Effect.Effect<string, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+export declare const loopbackServer: (server: Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>, options?: {
+    readonly host?: string;
+    readonly port?: number;
+} | undefined) => Effect.Effect<string, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
 //# sourceMappingURL=loopback.d.ts.map

package/dist/server/internal/loopback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,cAAc,2LA0BzB,CAAC"}
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,cAAc;oBAA2E,MAAM;oBAAkB,MAAM;0GA0BlI,CAAC"}

package/dist/server/internal/loopback.js

@@ -1,8 +1,8 @@
 import { Effect } from "effect";
-export const loopbackServer = Effect.fnUntraced(function* (server) {
+export const loopbackServer = Effect.fnUntraced(function* (server, options = {}) {
     yield* Effect.acquireRelease(Effect.tryPromise(() => new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
+        server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
             server.off("error", reject);
             resolve();
         });

package/dist/server/internal/loopback.js.map

@@ -1 +1 @@
-{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAc;IACxE,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAC3B,MAAM,CAAC,UAAU,CAChB,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YAClC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CACH,EACD,GAAG,EAAE,CACJ,MAAM,CAAC,OAAO,CACb,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9B,CAAC,CAAC,CACH,CACF,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,+GAA+G,CAAC,CAAC;IAC3I,CAAC;IACD,OAAO,oBAAoB,OAAO,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC,CAAC,CAAC"}
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAc,EAAE,OAAO,GAAuD,EAAE;IAC1I,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAC3B,MAAM,CAAC,UAAU,CAChB,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,GAAG,EAAE;YAClE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CACH,EACD,GAAG,EAAE,CACJ,MAAM,CAAC,OAAO,CACb,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9B,CAAC,CAAC,CACH,CACF,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,+GAA+G,CAAC,CAAC;IAC3I,CAAC;IACD,OAAO,oBAAoB,OAAO,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC,CAAC,CAAC"}

package/dist/server/seedCookies.d.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+export interface DomCookie {
+    readonly domain?: string;
+    readonly expires?: number;
+    readonly httpOnly?: boolean;
+    readonly name: string;
+    readonly path?: string;
+    readonly sameSite?: "Lax" | "Strict" | "None";
+    readonly secure?: boolean;
+    readonly value: string;
+}
+export declare const seedCookies: (cookies: readonly DomCookie[]) => Effect.Effect<undefined, never, never>;
+//# sourceMappingURL=seedCookies.d.ts.map

package/dist/server/seedCookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seedCookies.d.ts","sourceRoot":"","sources":["../../src/server/seedCookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAID,eAAO,MAAM,WAAW,2EAqBtB,CAAC"}

package/dist/server/seedCookies.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { BrowserWindow, CookieSameSiteEnum } from "happy-dom";
+import WindowBrowserContext from "happy-dom/lib/window/WindowBrowserContext.js";
+const sameSites = { Lax: CookieSameSiteEnum.lax, None: CookieSameSiteEnum.none, Strict: CookieSameSiteEnum.strict };
+export const seedCookies = Effect.fnUntraced(function* (cookies) {
+    if (!(window instanceof BrowserWindow)) {
+        return yield* Effect.die("Cookie preconditions need a happy-dom window.\nhelp: Use test-story's DOM environment before seeding cookies.");
+    }
+    const context = new WindowBrowserContext(window).getBrowserContext();
+    if (context === null) {
+        return yield* Effect.die("Cannot seed cookies after the document has closed.");
+    }
+    context.cookieContainer.addCookies(cookies.map((cookie) => ({
+        key: cookie.name,
+        "originURL": new URL(window.location.href),
+        value: cookie.value,
+        ...(cookie.domain === undefined ? {} : { domain: cookie.domain }),
+        ...(cookie.path === undefined ? {} : { path: cookie.path }),
+        ...(cookie.httpOnly === undefined ? {} : { httpOnly: cookie.httpOnly }),
+        ...(cookie.secure === undefined ? {} : { secure: cookie.secure }),
+        ...(cookie.sameSite === undefined ? {} : { sameSite: sameSites[cookie.sameSite] }),
+        ...(cookie.expires === undefined ? {} : { expires: new Date(cookie.expires * 1000) }),
+    })));
+});
+//# sourceMappingURL=seedCookies.js.map

package/dist/server/seedCookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seedCookies.js","sourceRoot":"","sources":["../../src/server/seedCookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,oBAAoB,MAAM,8CAA8C,CAAC;AAahF,MAAM,SAAS,GAAG,EAAE,GAAG,EAAE,kBAAkB,CAAC,GAAG,EAAE,IAAI,EAAE,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,CAAC;AAEpH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,OAA6B;IACpF,IAAI,CAAC,CAAC,MAAM,YAAY,aAAa,CAAC,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,+GAA+G,CAAC,CAAC;IAC3I,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACrE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,CAAC,eAAe,CAAC,UAAU,CACjC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACxB,GAAG,EAAE,MAAM,CAAC,IAAI;QAChB,WAAW,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAC3D,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;QACvE,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClF,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;KACrF,CAAC,CAAC,CACH,CAAC;AACH,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
   "bugs": {
@@ -46,7 +46,7 @@
   },
   "devDependencies": {
     "@effect/vitest": "4.0.4",
-    "@shivaedev/quality": "0.26.0",
+    "@shivaedev/quality": "0.27.1",
     "@types/node": "24.19.2",
     "effect": "4.0.4",
     "happy-dom": "20.14.6",

package/src/server/forwardingProxy.ts

@@ -0,0 +1,39 @@
+import { createServer, type RequestListener, request } from "node:http";
+import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
+
+export interface ForwardingProxyOptions {
+	readonly headers?: Readonly<Record<string, string>>;
+}
+
+export const forwardingProxy = Effect.fnUntraced(function* (upstream: string, options: ForwardingProxyOptions = {}) {
+	const forward: RequestListener = (incoming, response) => {
+		const outgoing = request(
+			`${upstream}${incoming.url}`,
+			{
+				headers: {
+					...incoming.headers,
+					"x-forwarded-for": [incoming.headers["x-forwarded-for"], incoming.socket.remoteAddress].filter(Boolean).join(", "),
+					...options.headers,
+				},
+				method: incoming.method,
+			},
+			(result) => {
+				response.writeHead(result.statusCode ?? 502, result.headers);
+				result.pipe(response);
+			},
+		);
+		outgoing.on("error", (error) => {
+			if (response.headersSent) {
+				response.destroy(error);
+			} else {
+				response.writeHead(502).end();
+			}
+		});
+		response.on("close", () => outgoing.destroy());
+		incoming.pipe(outgoing);
+	};
+	const url = yield* loopbackServer(createServer(forward));
+	yield* loopbackServer(createServer(forward), { host: "::1", port: Number(new URL(url).port) });
+	return { url };
+});

package/src/server/internal/loopback.ts

@@ -1,13 +1,13 @@
 import type { Server } from "node:http";
 import { Effect } from "effect";
 
-export const loopbackServer = Effect.fnUntraced(function* (server: Server) {
+export const loopbackServer = Effect.fnUntraced(function* (server: Server, options: { readonly host?: string; readonly port?: number } = {}) {
 	yield* Effect.acquireRelease(
 		Effect.tryPromise(
 			() =>
 				new Promise<void>((resolve, reject) => {
 					server.once("error", reject);
-					server.listen(0, "127.0.0.1", () => {
+					server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
 						server.off("error", reject);
 						resolve();
 					});

package/src/server/seedCookies.ts

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import { BrowserWindow, CookieSameSiteEnum } from "happy-dom";
+import WindowBrowserContext from "happy-dom/lib/window/WindowBrowserContext.js";
+
+export interface DomCookie {
+	readonly domain?: string;
+	readonly expires?: number;
+	readonly httpOnly?: boolean;
+	readonly name: string;
+	readonly path?: string;
+	readonly sameSite?: "Lax" | "Strict" | "None";
+	readonly secure?: boolean;
+	readonly value: string;
+}
+
+const sameSites = { Lax: CookieSameSiteEnum.lax, None: CookieSameSiteEnum.none, Strict: CookieSameSiteEnum.strict };
+
+export const seedCookies = Effect.fnUntraced(function* (cookies: readonly DomCookie[]) {
+	if (!(window instanceof BrowserWindow)) {
+		return yield* Effect.die("Cookie preconditions need a happy-dom window.\nhelp: Use test-story's DOM environment before seeding cookies.");
+	}
+	const context = new WindowBrowserContext(window).getBrowserContext();
+	if (context === null) {
+		return yield* Effect.die("Cannot seed cookies after the document has closed.");
+	}
+	context.cookieContainer.addCookies(
+		cookies.map((cookie) => ({
+			key: cookie.name,
+			"originURL": new URL(window.location.href),
+			value: cookie.value,
+			...(cookie.domain === undefined ? {} : { domain: cookie.domain }),
+			...(cookie.path === undefined ? {} : { path: cookie.path }),
+			...(cookie.httpOnly === undefined ? {} : { httpOnly: cookie.httpOnly }),
+			...(cookie.secure === undefined ? {} : { secure: cookie.secure }),
+			...(cookie.sameSite === undefined ? {} : { sameSite: sameSites[cookie.sameSite] }),
+			...(cookie.expires === undefined ? {} : { expires: new Date(cookie.expires * 1000) }),
+		})),
+	);
+});