@cosmicdrift/kumiko-testing 0.388.0 → 0.390.0

package/src/stack/test-stack-setup.ts

@@ -1,13 +1,24 @@
 // @runtime dev
 import { createHash } from "node:crypto";
 import { buildServer, createSseBroker } from "@cosmicdrift/kumiko-framework/api";
-import type { DbConnection, EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  assertRowLevelSecurityBootState,
+  type DbConnection,
+  type EntityTableMeta,
+  knownTablesOf,
+  type RowLevelSecurityMode,
+} from "@cosmicdrift/kumiko-framework/db";
 import { createRegistry, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine/types";
 import {
   createArchivedStreamsTable,
   createEventsTable,
 } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  appHookScopedRunner,
+  DEFAULT_ROW_LEVEL_SECURITY_MODE,
+  systemScopedRunner,
+} from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import {
   createRateLimitResolver,
   unsafePushTables,
@@ -31,9 +42,11 @@ import {
 import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { createInMemorySearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
 import {
   createTestDb,
   ensureTestDbTemplate,
+  TEST_APPLICATION_ROLE,
   TEST_DB_TEMPLATE_RUN_ENV,
   testDbTemplatePrefix,
 } from "./db.ts";
@@ -94,7 +107,7 @@ async function pushStackSchema(
   // setupTestStack call is ready for writes without needing a manual
   // createEventsTable().
   await createEventsTable(db);
-  // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
+  // Archive-stream metadata — needed by ctx.events.append's archive guard and
   // loadAggregate's default-skip. Idempotent, so production boot running
   // the same call is fine.
   await createArchivedStreamsTable(db);
@@ -134,6 +147,7 @@ async function resolveTestDbTemplateName(
   options: TestStackOptions,
   metas: readonly EntityTableMeta[],
   withFileTables: boolean,
+  rowLevelSecurity: RowLevelSecurityMode,
 ): Promise<string | undefined> {
   const runId = process.env[TEST_DB_TEMPLATE_RUN_ENV];
   if (runId === undefined || options.persistentDb === true || options.dbName !== undefined) {
@@ -141,7 +155,14 @@ async function resolveTestDbTemplateName(
   }
   const { renderTablesDdl } = await import("@cosmicdrift/kumiko-framework/db");
   const fingerprint = createHash("sha256")
-    .update(JSON.stringify({ withFileTables, ddl: renderTablesDdl(metas) }))
+    .update(
+      JSON.stringify({
+        withFileTables,
+        rowLevelSecurity,
+        role: rowLevelSecurity === "on" ? TEST_APPLICATION_ROLE : "superuser",
+        ddl: renderTablesDdl(metas, { rowLevelSecurity }),
+      }),
+    )
     .digest("hex")
     .slice(0, 16);
   return `${testDbTemplatePrefix(runId)}${fingerprint}`;
@@ -192,8 +213,17 @@ export async function provisionStackStorage(options: TestStackOptions): Promise<
   const withFileTables = options.files !== undefined;
   const buildStackSchema = (db: DbConnection): Promise<void> =>
     pushStackSchema(db, stackTableMetas, withFileTables);
-  const templateDbName = await resolveTestDbTemplateName(options, stackTableMetas, withFileTables);
-  if (templateDbName !== undefined) await ensureTestDbTemplate(templateDbName, buildStackSchema);
+  const rowLevelSecurity = options.rowLevelSecurity ?? "on";
+  const applicationRole = rowLevelSecurity === "on";
+  const templateDbName = await resolveTestDbTemplateName(
+    options,
+    stackTableMetas,
+    withFileTables,
+    rowLevelSecurity,
+  );
+  if (templateDbName !== undefined) {
+    await ensureTestDbTemplate(templateDbName, buildStackSchema, { applicationRole });
+  }
 
   // Forward db-name/persistent-flag through to createTestDb. The
   // defaults (undefined dbName, persistent:false) keep the legacy
@@ -208,6 +238,7 @@ export async function provisionStackStorage(options: TestStackOptions): Promise<
         outsideTransactionPoolMax: options.outsideTransactionPoolMax,
       }),
       ...(templateDbName !== undefined && { templateDbName }),
+      applicationRole,
     }),
     createTestRedis(
       options.sharedRedisWith && { borrowKeyPrefix: options.sharedRedisWith.redis.keyPrefix },
@@ -218,13 +249,16 @@ export async function provisionStackStorage(options: TestStackOptions): Promise<
   // DB/Redis — the caller never gets the stack object back to call
   // cleanup() itself (same "leaked ephemeral DB" failure class as the later
   // try/catch in setupTestStack, but for setup that runs before that try starts).
-  if (templateDbName === undefined) {
-    try {
-      await buildStackSchema(testDb.db);
-    } catch (error) {
-      await runCleanupsIgnoringErrors([() => testDb.cleanup(), () => testRedis.cleanup()]);
-      throw error;
-    }
+  try {
+    if (templateDbName === undefined) await buildStackSchema(testDb.db);
+    await assertRowLevelSecurityBootState(
+      testDb.db,
+      rowLevelSecurity,
+      knownTablesOf(options.features),
+    );
+  } catch (error) {
+    await runCleanupsIgnoringErrors([() => testDb.cleanup(), () => testRedis.cleanup()]);
+    throw error;
   }
   return { testDb, testRedis };
 }
@@ -248,14 +282,26 @@ export function createStackCacheSync(
 // A static `files.storageProvider` is wired as the per-tenant resolver — the
 // framework test seam that doesn't require mounting config + file-foundation.
 // (Bundled GDPR tests mount the real provider features instead.)
+function isClock(value: unknown): value is Clock {
+  return (
+    typeof value === "object" && value !== null && "now" in value && typeof value.now === "function"
+  );
+}
+
 async function resolveStackFileProvider(
   options: TestStackOptions,
   testDb: StackStorage["testDb"],
+  readClock: () => unknown,
 ): Promise<import("@cosmicdrift/kumiko-framework/files").FileProviderResolver | undefined> {
   if (!options.files) return undefined;
   const provider = options.files.storageProvider;
   const { withUploadLedger } = await import("@cosmicdrift/kumiko-framework/files");
-  return withUploadLedger(() => Promise.resolve(provider), testDb.db);
+  // Read per call: the clock arrives via extraContext, which is merged after this resolver is built.
+  const now = (): Temporal.Instant => {
+    const clock = readClock();
+    return isClock(clock) ? clock.now() : Temporal.Now.instant();
+  };
+  return withUploadLedger(() => Promise.resolve(provider), testDb.db, now);
 }
 
 export async function buildStackServices(
@@ -277,7 +323,12 @@ export async function buildStackServices(
   );
 
   const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
-  const fileProviderResolver = await resolveStackFileProvider(options, testDb);
+  const extraContextClock: { current: unknown } = { current: undefined };
+  const fileProviderResolver = await resolveStackFileProvider(
+    options,
+    testDb,
+    () => extraContextClock.current,
+  );
   const observability = options.observability ?? createNoopProvider();
 
   // Same AppContext buildServer() gets below (db/redis/searchAdapter/
@@ -290,8 +341,18 @@ export async function buildStackServices(
   // it there either (only dispatcherOptions.effectiveFeatures, consumed by
   // the command-dispatcher — see buildJobRunnerWithHook in entrypoint/
   // index.ts). Putting it here would reintroduce the exact test-vs-prod
-  // drift fixed: a job/handler reading `ctx.effectiveFeatures` would pass in
+  // drift fixed: a job/handler reading `ctx.services.effectiveFeatures` would pass in
   // tests and break in prod.
+  const extraContext =
+    typeof options.extraContext === "function"
+      ? options.extraContext({
+          registry,
+          // The raw pool, as in prod: request-time services keep the ambient request scope, so a tenant leak shows in tests.
+          db: testDb.db,
+          sseBroker,
+          redis: testRedis.redis,
+        })
+      : options.extraContext;
   const appContext = {
     db: testDb.db,
     redis: testRedis.redis,
@@ -301,10 +362,9 @@ export async function buildStackServices(
     ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
     ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
     ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
-    ...(typeof options.extraContext === "function"
-      ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
-      : options.extraContext),
+    ...extraContext,
   };
+  extraContextClock.current = extraContext?.["clock"];
   return { searchAdapter, events, registry, sseBroker, entityCache, observability, appContext };
 }
 
@@ -313,7 +373,7 @@ export type StackServices = Awaited<ReturnType<typeof buildStackServices>>;
 type JobFailureTracker = ReturnType<typeof createJobFailureTracker>;
 
 // Built before buildServer() so it can be merged into dispatcherOptions
-// (write handlers' `ctx.jobRunner.dispatch(...)` and the afterCommit
+// (write handlers' `ctx.services.jobRunner.dispatch(...)` and the afterCommit
 // event-trigger hook both need it present at dispatcher-construction
 // time, same as the prod entrypoint's buildJobRunnerWithHook). Uses the
 // test-stack's own ephemeral redis — no separate `redisUrl` seam needed.
@@ -409,7 +469,7 @@ async function configureStackSearch(
 
 // buildServer only auto-wires an L3 RateLimitResolver from
 // `context.redis` — a degradation test that nulls `redis` via
-// extraContext (to exercise a handler's own ctx.redis-down guard) also
+// extraContext (to exercise a handler's own ctx.services.redis-down guard) also
 // silently strips rate-limiting, even though every handler with a
 // `rateLimit` declaration still requires a resolver at dispatch time.
 // Since e7bf543ad, an IP-keyed bucket key is built unconditionally
@@ -436,6 +496,12 @@ function resolveStackRateLimitFallback(
   });
 }
 
+function testCodeDb<T extends object>(options: TestStackOptions, db: T): T {
+  return (options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE) === "on"
+    ? systemScopedRunner(db, "test stack seeds and reads rows across tenants")
+    : db;
+}
+
 async function resolveStackAnonymousAccess(
   options: TestStackOptions,
   testDb: StackStorage["testDb"],
@@ -443,12 +509,16 @@ async function resolveStackAnonymousAccess(
   services: StackServices,
 ): Promise<Pick<ServerBuildOptions, "anonymousAccess">> {
   const { registry, sseBroker } = services;
+  const hookDb = appHookScopedRunner(
+    testDb.db,
+    options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE,
+  );
   const baseAnon =
     typeof options.anonymousAccess === "function"
-      ? options.anonymousAccess({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
+      ? options.anonymousAccess({ registry, db: hookDb, sseBroker, redis: testRedis.redis })
       : options.anonymousAccess;
   const resolvedAnon = options.enrichAnonymousAccess
-    ? await options.enrichAnonymousAccess(baseAnon, { registry, db: testDb.db })
+    ? await options.enrichAnonymousAccess(baseAnon, { registry, db: hookDb })
     : baseAnon;
   return resolvedAnon ? { anonymousAccess: resolvedAnon } : {};
 }
@@ -557,7 +627,9 @@ function assembleTestStack(
     app: server.app,
     jwt: server.jwt,
     registry: services.registry,
-    db: testDb.db,
+    // Test code sees every tenant's rows; the services keep the enforced pool.
+    db: testCodeDb(options, testDb.db),
+    unscopedDb: testDb.db,
     dbPoolMax: testDb.poolMax,
     redis: testRedis,
     cacheSync,

package/src/stack/test-stack.ts

@@ -37,7 +37,10 @@ export type TestStack = {
   app: Hono;
   jwt: JwtHelper;
   registry: Registry;
+  /** Sees every tenant's rows (system scope) at rowLevelSecurity "on". */
   db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
+  /** The enforced pool the services use: a statement without a scope sees no tenant row. Same as `db` at "off". */
+  unscopedDb: import("@cosmicdrift/kumiko-framework/db").DbConnection;
   /** Resolved connection pool size of `db`. */
   readonly dbPoolMax: number;
   redis: TestRedis;
@@ -61,7 +64,7 @@ export type TestStack = {
   // wires itself (_fileProviderResolver). A dev-server that starts its own
   // lane job-runners beside this stack must hand them THIS, not a
   // `{ db, registry }` literal — that's the drift, and it makes an
-  // event-triggered job reaching for ctx.files die where the request path works.
+  // event-triggered job reaching for ctx.services.files die where the request path works.
   context: AppContext;
   // Present whenever a system consumer (SSE, Search) or
   // r.multiStreamProjection is wired. Tests drain it via runOnce() (or the
@@ -73,7 +76,7 @@ export type TestStack = {
   lifecycle?: Lifecycle;
   // Only set when `options.jobs` is truthy AND ≥1 `r.job(...)` is
   // registered in the mounted features. Lets integration tests call
-  // `stack.jobRunner.dispatch(...)` directly, mirroring `ctx.jobRunner`.
+  // `stack.jobRunner.dispatch(...)` directly, mirroring `ctx.services.jobRunner`.
   jobRunner?: JobRunner;
   // Waits for every in-flight job and its follow-up event-consumer /
   // job-trigger cascade to settle — instead of `waitFor` polling on a
@@ -116,7 +119,7 @@ export type TestStackOptions = {
   /** Wire up auth routes (login, tenant-switch). Leave undefined to skip. */
   authConfig?: AuthRoutesConfig;
   /** Register a file storage provider so uploads via POST /api/files work and
-   *  `ctx.files.ref(key)` is available to hooks/MSPs. Omit to skip — tests
+   *  `ctx.services.files.ref(key)` is available to hooks/MSPs. Omit to skip — tests
    *  without file handling don't need it. */
   files?: { storageProvider: import("@cosmicdrift/kumiko-framework/files").FileStorageProvider };
   /** Observability provider — omit for NoopProvider (no spans/metrics).
@@ -160,7 +163,7 @@ export type TestStackOptions = {
   persistentDb?: boolean;
   /** Cap on the main app pool (default: driver default). Lets tests saturate it deliberately. */
   dbPoolMax?: number;
-  /** Size of the dedicated pool behind ctx.dbOutsideTransaction / ctx.outsideTransaction. */
+  /** Size of the dedicated pool behind ctx.db.outsideTransaction / ctx.outsideTransaction. */
   outsideTransactionPoolMax?: number;
   /** Forwarded to buildServer — when set, requests without a JWT pass
    *  through as anonymous instead of 401. See AnonymousAccessConfig.
@@ -187,7 +190,7 @@ export type TestStackOptions = {
   ) => Promise<
     import("@cosmicdrift/kumiko-framework/api").ServerOptions["anonymousAccess"] | undefined
   >;
-  /** Opt-in JobRunner wired into ctx.jobRunner and merged into
+  /** Opt-in JobRunner wired into ctx.services.jobRunner and merged into
    *  dispatcherOptions so event-triggered jobs enqueue on commit — mirrors
    *  the prod entrypoint's `buildJobRunnerWithHook`. Unlike prod (which
    *  always builds one), this only builds a runner when `registry.getAllJobs()`
@@ -254,6 +257,8 @@ export type TestStackOptions = {
    *  entities across features included). Use it with the app's complete feature
    *  composition; the default only checks what is safe on a feature subset. */
   validateBoot?: "full";
+  /** Postgres tenant isolation, as in prod. "on" (default) runs the stack as the non-bypass role kumiko_app against policies; "off" uses the superuser without policies. */
+  rowLevelSecurity?: import("@cosmicdrift/kumiko-framework/db").RowLevelSecurityMode;
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";