@cosmicdrift/kumiko-testing 0.319.0 → 0.321.0

package/README.md

@@ -11,12 +11,14 @@ const persisted = await seedTenant(stack, { persist: true }); // real rows via t
 await tenant.api.writeOk("my-feature:write:thing:create", { title: "x" });
 ```
 
-- `preload/{temporal,ci-log,scrub-env,env,real,dom}`: bunfig `preload` entries. `scrub-env` removes
-  `PROVIDER_ENV_KEYS` (unit default); `env` adds the localhost service defaults (integration);
-  `real` refuses to run without `KUMIKO_REAL_PROVIDERS=1` and in CI, and keeps the keys; `dom`
-  registers happy-dom (window/document/HTMLElement) while preserving Bun's native
-  fetch/Request/Response, and cleans up (`@testing-library/react` unmount, Radix DOM/style leaks,
-  `window.location`) after every test.
+- `preload/{temporal,ci-log,scrub-env,schema-env-defaults,env,real,dom}`: bunfig `preload` entries.
+  `scrub-env` removes `PROVIDER_ENV_KEYS` (unit default); `schema-env-defaults` fills `JWT_SECRET`
+  and the `KUMIKO_SECRETS_MASTER_KEY_*` pair that the framework's own env schema requires (unit,
+  DOM, integration, real — never a service endpoint); `env` adds `schema-env-defaults` plus the
+  localhost service defaults (integration); `real` refuses to run without
+  `KUMIKO_REAL_PROVIDERS=1` and in CI, and keeps the keys; `dom` registers happy-dom
+  (window/document/HTMLElement) while preserving Bun's native fetch/Request/Response, and cleans up
+  (`@testing-library/react` unmount, Radix DOM/style leaks, `window.location`) after every test.
 - `kumiko-testing bunfig [--dom] [--coverage]`: writes `bunfig.toml`,
   `bunfig.integration.toml` and `bunfig.real.toml` (plus `bunfig.dom.toml`). `--dom` adds
   `preload/dom` (happy-dom + testing-library/react cleanup); `@happy-dom/global-registrator` and

package/bin/kumiko-testing.ts

@@ -5,15 +5,20 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { Glob } from "bun";
 import { BUNFIG_FILES, mergeBunfig, renderBunfigFiles } from "../src/bunfig";
-import { buildIntegrationTestArgs, selectIntegrationFiles } from "../src/integration-runner";
+import {
+  buildIntegrationTestArgs,
+  resolveRequestedIntegrationFiles,
+  selectIntegrationFiles,
+} from "../src/integration-runner";
 
 const USAGE = `kumiko-testing <command>
 
   bunfig [--dom] [--coverage] [--hoisted]  write bunfig.toml, bunfig.integration.toml and
                                            bunfig.real.toml (plus bunfig.dom.toml with --dom);
                                            --hoisted adds [install] linker = "hoisted"
-  integration [--parallel N]               run every *.integration.test.ts under the cwd
-              [--timings <file>] [--update-timings]
+  integration [--parallel N]               run every *.integration.test.ts under the cwd,
+              [--timings <file>] [--update-timings]  or only the given file(s) when passed
+              [file...]                               as positional args
 `;
 
 function runBunfig(args: readonly string[]): number {
@@ -53,25 +58,36 @@ function runBunfig(args: readonly string[]): number {
 }
 
 async function runIntegration(args: readonly string[]): Promise<number> {
-  const { values } = parseArgs({
+  const { values, positionals } = parseArgs({
     args: [...args],
     options: {
       parallel: { type: "string" },
       timings: { type: "string" },
       "update-timings": { type: "boolean" },
     },
+    allowPositionals: true,
     strict: true,
   });
   if (!existsSync(BUNFIG_FILES.integration)) {
     console.error(`${BUNFIG_FILES.integration} not found - run \`kumiko-testing bunfig\` first`);
     return 1;
   }
-  const files = selectIntegrationFiles(
-    await Array.fromAsync(new Glob("**/*.integration.test.ts").scan({ cwd: process.cwd() })),
-  );
-  if (files.length === 0) {
-    console.error("no *.integration.test.ts files found");
-    return 1;
+  let files: string[];
+  if (positionals.length > 0) {
+    try {
+      files = resolveRequestedIntegrationFiles(process.cwd(), positionals);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 1;
+    }
+  } else {
+    files = selectIntegrationFiles(
+      await Array.fromAsync(new Glob("**/*.integration.test.ts").scan({ cwd: process.cwd() })),
+    );
+    if (files.length === 0) {
+      console.error("no *.integration.test.ts files found");
+      return 1;
+    }
   }
   const testArgs = buildIntegrationTestArgs({
     files,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.319.0",
+  "version": "0.321.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -42,6 +42,10 @@
       "types": "./src/preload/scrub-env.ts",
       "default": "./src/preload/scrub-env.ts"
     },
+    "./preload/schema-env-defaults": {
+      "types": "./src/preload/schema-env-defaults.ts",
+      "default": "./src/preload/schema-env-defaults.ts"
+    },
     "./preload/env": {
       "types": "./src/preload/env.ts",
       "default": "./src/preload/env.ts"
@@ -71,9 +75,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.319.0",
-    "@cosmicdrift/kumiko-dev-server": "0.319.0",
-    "@cosmicdrift/kumiko-framework": "0.319.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.321.0",
+    "@cosmicdrift/kumiko-dev-server": "0.321.0",
+    "@cosmicdrift/kumiko-framework": "0.321.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/bunfig.ts

@@ -28,7 +28,11 @@ const PRELOAD_PREFIX = "@cosmicdrift/kumiko-testing/preload";
 const DOM_PRELOAD = `${PRELOAD_PREFIX}/dom`;
 
 const PRELOADS = {
-  unit: [`${PRELOAD_PREFIX}/temporal`, `${PRELOAD_PREFIX}/scrub-env`],
+  unit: [
+    `${PRELOAD_PREFIX}/temporal`,
+    `${PRELOAD_PREFIX}/scrub-env`,
+    `${PRELOAD_PREFIX}/schema-env-defaults`,
+  ],
   integration: [`${PRELOAD_PREFIX}/temporal`, `${PRELOAD_PREFIX}/env`],
   real: [`${PRELOAD_PREFIX}/temporal`, `${PRELOAD_PREFIX}/real`],
 } as const satisfies Record<BunfigVariant, readonly string[]>;

package/src/changes.json

@@ -1,4 +1,37 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "kumiko-testing integration accepts positional test-file args",
+    "detail": "`kumiko-testing integration` now runs only the given files/globs when\npositional args are passed, instead of always discovering every\n`*.integration.test.ts` file.",
+    "migration": "No action needed — omitting positional args keeps the previous full-discovery behavior."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "defineAppE2eConfig reserves KUMIKO_TRUSTED_PROXY_HOPS; loginViaApi sends a synthetic per-user X-Forwarded-For",
+    "detail": "`defineAppE2eConfig`'s `webServer.env` now sets\n`KUMIKO_TRUSTED_PROXY_HOPS=1` and rejects that key in a consumer's own\n`env` (template-owned, added to `RESERVED_ENV_KEYS`). `loginViaApi` sends\n`x-forwarded-for: syntheticClientIpFor(credentials.email)`, a new\nexported helper deriving a deterministic private-range IP from\n`sha256(email)`, so each seeded user's login lands in its own\nrate-limit bucket instead of every ::1 client sharing one.\n`loginViaUi` is unchanged.",
+    "migration": "Consumers using `defineAppE2eConfig` + `loginViaApi` (incl. the\n`seedTenant` fixture) need no changes — each seeded user now logs in\nfrom its own bucket. Browser logins (`loginViaUi`, raw `fetch` to\n`/api/auth/login` from a page) still share the `::1` bucket. A consumer\nwith its own e2e login helper (bypassing `loginViaApi`) should send\n`x-forwarded-for: syntheticClientIpFor(email)` (exported from\n`@cosmicdrift/kumiko-testing`) themselves, and must not set\n`KUMIKO_TRUSTED_PROXY_HOPS` in `defineAppE2eConfig`'s `env` — it's now\nreserved."
+  },
+  {
+    "version": "0.321.0",
+    "type": "fix",
+    "title": "e2e test fixture gives every test its own synthetic client IP",
+    "detail": "`test` from `@cosmicdrift/kumiko-testing/e2e` overrides the `context`\nfixture with a `context.route(\"**/api/**\")` that adds\n`x-forwarded-for: syntheticClientIpFor(perTestClientIpKey(testInfo))` to\nsame-origin requests; an explicit `x-forwarded-for` wins. Cross-origin\nrequests stay untouched because an extra header would force a CORS\npreflight. Routing disables the HTTP cache of the test's context.\n`seedTenant`'s per-user API contexts send\n`syntheticClientIpFor(user.email)`. The built-in `request` fixture is not\ncovered.",
+    "migration": "Specs that import `test` from `@cosmicdrift/kumiko-testing/e2e` need no\nchange. Specs importing `test` straight from `@playwright/test` keep\nsharing the `::1` bucket; switch their import to kumiko-testing."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "requireRealProviders from kumiko-testing/e2e, SSE events for seedTenant tenants",
+    "detail": "`@cosmicdrift/kumiko-testing/e2e` re-exports `requireRealProviders`, `isRealProviderRun` and `REAL_PROVIDERS_ENV` from the framework's `testing/real-providers` subpath instead of keeping its own copy. Playwright specs and configs, which load under Node, no longer have to avoid the framework's `./testing` barrel.\n\n`seedTenant(stack, …)` subscribes `stack.events.sse` to the seeded tenant's SSE channel. Before, `setupTestStack` only listened on test tenant 1, so writes in a seeded tenant never showed up on `events.sse` and tests had to call `stack.sseBroker.addClient(tenantChannel(id), …)` themselves; that manual call can go. Events from `persist: true` seeding (tenant, user, membership) now also land on `events.sse` after the next drain."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "Schema-required test env keys (JWT_SECRET, secrets master key) now default in every bunfig variant",
+    "detail": "Apps with the secrets, field-encryption or auth-mfa features previously had\nto hand-roll a `test-setup/env.preload.ts` to satisfy the env schema's\n`JWT_SECRET` and `KUMIKO_SECRETS_MASTER_KEY_*` in unit and DOM tests, since\nonly `SERVICE_ENV_DEFAULTS` (integration/real only) carried a `JWT_SECRET`\ndefault and no map carried the master key. The new `SCHEMA_ENV_DEFAULTS`\nmap lives next to `SERVICE_ENV_DEFAULTS` and is preloaded in all four bunfig\nvariants (unit, DOM, integration, real) via a new `preload/schema-env-defaults`\nmodule, filled with `??=` so an app's own value is kept; only a\n`JWT_SECRET` shorter than 32 characters is replaced.\n`SERVICE_ENV_DEFAULTS` no longer duplicates `JWT_SECRET` — it has one home\nnow. Unit and DOM still carry no service-endpoint defaults."
+  },
   {
     "version": "0.318.0",
     "type": "improvement",

package/src/e2e/auth-kit.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { currentTotpCode } from "@cosmicdrift/kumiko-bundled-features/auth-mfa/testing";
 import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
 import { type APIRequestContext, type APIResponse, expect, type Page } from "@playwright/test";
@@ -34,12 +35,23 @@ export async function csrfFetch(
   return request.post(path, { headers: csrfHeaderFromCookies(cookies), data });
 }
 
+// Deterministic IP in the RFC 1918 private range, so the same key (a seeded
+// user's email, a test's id) always lands in the same rate-limit bucket while
+// different keys get distinct buckets (3 varying bytes ~= 16M slots).
+export function syntheticClientIpFor(key: string): string {
+  const digest = createHash("sha256").update(key).digest();
+  return `10.${digest[0]}.${digest[1]}.${digest[2]}`;
+}
+
+export const CLIENT_IP_HEADER = "x-forwarded-for";
+
 export async function loginViaApi(
   request: APIRequestContext,
   credentials: LoginCredentials,
 ): Promise<void> {
   const response = await request.post("/api/auth/login", {
     data: { email: credentials.email, password: credentials.password },
+    headers: { [CLIENT_IP_HEADER]: syntheticClientIpFor(credentials.email) },
   });
   if (!response.ok()) {
     throw new Error(

package/src/e2e/constants.ts

@@ -15,18 +15,6 @@ export const SEED_TOKEN_ENV = "KUMIKO_TEST_SEED_TOKEN";
 export const SEED_TOKEN_HEADER = "x-kumiko-test-seed";
 export const E2E_WORKERS_ENV = "KUMIKO_E2E_WORKERS";
 
-// Same literal as the framework's requireRealProviders()/isRealProviderRun(),
-// duplicated because the Playwright config runs under Node and importing the
-// framework's "./testing" barrel there would pull in its full Bun-toolchain
-// dependency graph for a single string constant.
-export const REAL_PROVIDERS_ENV = "KUMIKO_REAL_PROVIDERS";
-
-export function isRealProviderRun(
-  env: Readonly<Record<string, string | undefined>> = process.env,
-): boolean {
-  return env[REAL_PROVIDERS_ENV] === "1";
-}
-
 // Same literal as kumiko-dev-server's createKumikoServer (STYLESHEET_WATCH_ENV),
 // duplicated because the Playwright config runs under Node and can't import
 // that Bun-toolchain-adjacent module.
@@ -36,6 +24,10 @@ export const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
 // duplicated for the same Node/Bun-toolchain reason.
 export const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";
 
+// Same literal as kumiko-framework's client-ip.ts (TRUSTED_PROXY_HOPS_ENV),
+// duplicated for the same Node/Bun-toolchain reason.
+export const TRUSTED_PROXY_HOPS_ENV = "KUMIKO_TRUSTED_PROXY_HOPS";
+
 export const SEED_ROUTE_PREFIX = "/__test";
 
 export const SEED_ROUTES = {

package/src/e2e/define-app-e2e-config.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { availableParallelism } from "node:os";
+import { isRealProviderRun } from "@cosmicdrift/kumiko-framework/testing/real-providers";
 import {
   defineConfig,
   devices,
@@ -12,13 +13,13 @@ import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values";
 import {
   DESKTOP_VIEWPORT,
   E2E_WORKERS_ENV,
-  isRealProviderRun,
   PLAYWRIGHT_DEMO_ENV,
   PROD_BUNDLES_ENV,
   SCREENSHOT_DEVICE_SCALE_FACTOR,
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
   STYLESHEET_WATCH_ENV,
+  TRUSTED_PROXY_HOPS_ENV,
 } from "./constants";
 import { isScreenshotRun, requireScreenshotDir, screenshotSpecsIgnore } from "./screenshot-dir";
 import { E2E_TIMEOUT_MS } from "./timeouts";
@@ -61,6 +62,7 @@ const RESERVED_ENV_KEYS = [
   SEED_TOKEN_ENV,
   STYLESHEET_WATCH_ENV,
   PROD_BUNDLES_ENV,
+  TRUSTED_PROXY_HOPS_ENV,
 ] as const;
 
 type ProjectUse = Partial<PlaywrightTestOptions & PlaywrightWorkerOptions>;
@@ -205,6 +207,11 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
         // E2E runs against prod-shaped bundles: splitting, no sourcemap,
         // NODE_ENV=production — matches what actually ships.
         [PROD_BUNDLES_ENV]: "1",
+        // E2e clients all share ::1, so the default trustedProxyHops (0,
+        // socket-only) would collapse every seeded user into one rate-limit
+        // bucket. loginViaApi sends a synthetic per-user X-Forwarded-For, so
+        // trust exactly one hop to give each user its own bucket.
+        [TRUSTED_PROXY_HOPS_ENV]: "1",
       },
       reuseExistingServer: false,
       timeout: E2E_TIMEOUT_MS.webServer,

package/src/e2e/index.ts

@@ -1,3 +1,8 @@
+export {
+  isRealProviderRun,
+  REAL_PROVIDERS_ENV,
+  requireRealProviders,
+} from "@cosmicdrift/kumiko-framework/testing/real-providers";
 export { expect } from "@playwright/test";
 export {
   apiCommand,
@@ -10,16 +15,15 @@ export {
   type LoginCredentials,
   loginViaApi,
   loginViaUi,
+  syntheticClientIpFor,
   totpCode,
 } from "./auth-kit";
 export {
   CSRF_COOKIE_NAME,
   CSRF_HEADER_NAME,
   E2E_WORKERS_ENV,
-  isRealProviderRun,
   KUMIKO_SECRETS_MASTER_KEY_V1,
   PLAYWRIGHT_DEMO_ENV,
-  REAL_PROVIDERS_ENV,
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
 } from "./constants";

package/src/e2e/screenshots.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
+import { isRealProviderRun } from "@cosmicdrift/kumiko-framework/testing/real-providers";
 import { expect, type Page, type Request } from "@playwright/test";
-import { DESKTOP_VIEWPORT, isRealProviderRun } from "./constants";
+import { DESKTOP_VIEWPORT } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
 import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";
 import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";

package/src/e2e/seeded-tenant-fixture.ts

@@ -1,11 +1,14 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import {
   type APIRequestContext,
+  type BrowserContext,
   test as base,
   type Page,
+  type Request as PlaywrightRequest,
   type PlaywrightTestArgs,
   type PlaywrightTestOptions,
   type PlaywrightWorkerArgs,
+  type TestInfo,
 } from "@playwright/test";
 import type * as z from "zod";
 import {
@@ -16,8 +19,14 @@ import {
   type SeedTenantOptions,
   withSession,
 } from "../seed-types";
-import { clearSession, createHttpApi, loginViaApi } from "./auth-kit";
-import { SEED_ROUTES } from "./constants";
+import {
+  CLIENT_IP_HEADER,
+  clearSession,
+  createHttpApi,
+  loginViaApi,
+  syntheticClientIpFor,
+} from "./auth-kit";
+import { SEED_ROUTES, SEED_TOKEN_ENV } from "./constants";
 import { seedRouteHeaders } from "./mail-capture";
 import {
   type ExtraSeedRequest,
@@ -77,7 +86,10 @@ export async function provideSeedTenant(
 
   // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
   const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
-    const ctx = await playwright.request.newContext({ baseURL });
+    const ctx = await playwright.request.newContext({
+      baseURL,
+      extraHTTPHeaders: { [CLIENT_IP_HEADER]: syntheticClientIpFor(user.email) },
+    });
     openedContexts.push(ctx);
     await loginViaApi(ctx, user);
     return createHttpApi(ctx);
@@ -166,6 +178,65 @@ export async function provideSeedTenant(
   await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
 }
 
+// Every e2e client connects from ::1, and the e2e webServer trusts one proxy
+// hop (defineAppE2eConfig). Without a distinct X-Forwarded-For per test, all
+// browser pages of a run would share one `per: "ip"` rate-limit bucket and
+// 429 under parallel load. The run token keeps a rerun within the limiter
+// window out of the previous run's buckets; the retry index keeps a retry
+// out of the bucket its failed attempt already drained.
+export function perTestClientIpKey(
+  testInfo: Pick<TestInfo, "testId" | "repeatEachIndex" | "retry">,
+  runToken: string | undefined = process.env[SEED_TOKEN_ENV],
+): string {
+  return `${runToken ?? ""}:${testInfo.testId}:${testInfo.repeatEachIndex}:${testInfo.retry}`;
+}
+
+// Same-origin only: on a cross-origin fetch the extra header would force a
+// CORS preflight the target never agreed to (why extraHTTPHeaders is no option
+// here). An explicit X-Forwarded-For set by the test wins.
+export function headersWithClientIp(
+  request: { readonly url: string; readonly frameUrl: string | undefined },
+  headers: Readonly<Record<string, string>>,
+  clientIp: string,
+): Record<string, string> | undefined {
+  if (request.frameUrl === undefined) return undefined;
+  let sameOrigin: boolean;
+  try {
+    sameOrigin = new URL(request.frameUrl).origin === new URL(request.url).origin;
+  } catch {
+    return undefined;
+  }
+  return sameOrigin ? { [CLIENT_IP_HEADER]: clientIp, ...headers } : undefined;
+}
+
+function frameUrlOf(request: PlaywrightRequest): string | undefined {
+  try {
+    return request.frame().url();
+  } catch {
+    // Service-worker requests have no frame.
+    return undefined;
+  }
+}
+
+export async function providePerTestClientIpContext(
+  { context }: Pick<PlaywrightTestArgs, "context">,
+  use: (context: BrowserContext) => Promise<void>,
+  testInfo: Pick<TestInfo, "testId" | "repeatEachIndex" | "retry">,
+): Promise<void> {
+  const clientIp = syntheticClientIpFor(perTestClientIpKey(testInfo));
+  await context.route("**/api/**", (route) => {
+    const request = route.request();
+    const headers = headersWithClientIp(
+      { url: request.url(), frameUrl: frameUrlOf(request) },
+      request.headers(),
+      clientIp,
+    );
+    return headers === undefined ? route.fallback() : route.fallback({ headers });
+  });
+  await use(context);
+}
+
 export const test = base.extend<E2eFixtures>({
+  context: providePerTestClientIpContext,
   seedTenant: provideSeedTenant,
 });

package/src/integration-runner.ts

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { BUNFIG_FILES, TEST_TIMEOUT_MS } from "./bunfig";
 
 export type IntegrationRunOptions = {
@@ -16,6 +18,26 @@ export function selectIntegrationFiles(paths: readonly string[]): string[] {
     .sort();
 }
 
+/** Resolves `kumiko-testing integration`'s positional file args against `cwd`
+ *  into absolute paths — absolute (not glob-relative) so bun's own
+ *  `bun test <path>` treats them as files to run, not filter patterns.
+ *  `exists` is injectable so this stays unit-testable without touching the
+ *  real filesystem. Throws on the first missing file — the caller decides
+ *  how to report it (CLI: print + exit 1). */
+export function resolveRequestedIntegrationFiles(
+  cwd: string,
+  positionals: readonly string[],
+  exists: (path: string) => boolean = existsSync,
+): string[] {
+  return positionals.map((arg) => {
+    const resolved = resolve(cwd, arg);
+    if (!exists(resolved)) {
+      throw new Error(`kumiko-testing integration: file not found: ${arg}`);
+    }
+    return resolved;
+  });
+}
+
 const isPositiveInteger = (value: number): boolean => Number.isInteger(value) && value > 0;
 
 export function buildIntegrationTestArgs(opts: IntegrationRunOptions): string[] {

package/src/preload/env.ts

@@ -1,2 +1,3 @@
 import "./scrub-env";
+import "./schema-env-defaults";
 import "./service-env-defaults";

package/src/preload/real.ts

@@ -1,4 +1,5 @@
 import { requireRealProviders } from "@cosmicdrift/kumiko-framework/testing";
+import "./schema-env-defaults";
 import "./service-env-defaults";
 
 requireRealProviders();

package/src/preload/schema-env-defaults-values.ts

@@ -0,0 +1,6 @@
+// KUMIKO_SECRETS_MASTER_KEY_V1 must base64-decode to exactly 32 bytes (AES-256 KEK).
+export const SCHEMA_ENV_DEFAULTS = {
+  JWT_SECRET: "test-jwt-secret-at-least-32-characters-long",
+  KUMIKO_SECRETS_MASTER_KEY_V1: "a3VtaWtvLXNjaGVtYS1lbnYtZGVmYXVsdC0zMmJ5dGU=",
+  KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+} as const satisfies Record<string, string>;

package/src/preload/schema-env-defaults.ts

@@ -0,0 +1,18 @@
+import { SCHEMA_ENV_DEFAULTS } from "./schema-env-defaults-values";
+
+// Mirrors authEmailPasswordEnvSchema's JWT_SECRET.min(32) / jwt.ts's HS256
+// floor: a too-short value from a stray .env is replaced, not kept, same as
+// the app-local preloads this centralizes did before it.
+const MIN_JWT_SECRET_LENGTH = 32;
+
+function isTooShortJwtSecret(key: string, value: string | undefined): boolean {
+  return key === "JWT_SECRET" && (!value || value.length < MIN_JWT_SECRET_LENGTH);
+}
+
+for (const [key, value] of Object.entries(SCHEMA_ENV_DEFAULTS)) {
+  if (isTooShortJwtSecret(key, process.env[key])) {
+    process.env[key] = value;
+    continue;
+  }
+  process.env[key] ??= value;
+}

package/src/preload/service-env-defaults-values.ts

@@ -4,7 +4,6 @@ export const SERVICE_ENV_DEFAULTS = {
   REDIS_URL: "redis://localhost:16379",
   MEILI_URL: "http://localhost:17700",
   MEILI_MASTER_KEY: "kumiko-dev-key",
-  JWT_SECRET: "test-jwt-secret-at-least-32-characters-long",
   MINIO_ENDPOINT: "http://localhost:19000",
   MINIO_ACCESS_KEY: "kumiko",
   MINIO_SECRET_KEY: "kumiko-dev-secret",

package/src/scaffold.ts

@@ -1,6 +1,6 @@
 // @runtime tooling
+import { REAL_PROVIDERS_ENV } from "@cosmicdrift/kumiko-framework/testing/real-providers";
 import { BUNFIG_FILES, renderBunfigFiles, TEST_TIMEOUT_MS } from "./bunfig";
-import { REAL_PROVIDERS_ENV } from "./e2e/constants";
 
 export type ScaffoldTestSetup = {
   readonly files: Readonly<Record<string, string>>;

package/src/seed-tenant.ts

@@ -7,6 +7,7 @@ import {
   createSystemUser,
   type SessionUser,
   type TenantId,
+  tenantChannel,
   type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
@@ -177,6 +178,13 @@ export async function seedTenant(
   const rows = persist ? await persistTenantRows(write, opts) : lightTenantRows(opts);
   const { id } = rows;
 
+  // setupTestStack subscribes events.sse only to test tenant 1; a seeded tenant has a fresh random id.
+  stack.sseBroker.addClient(
+    tenantChannel(id),
+    (event) => stack.events.sse.push(event),
+    () => {},
+  );
+
   const admin = withSession(rows.admin, id, [ROLES.TenantAdmin]);
   const tenant: SeededTenant = {
     id,