@cosmicdrift/kumiko-framework 0.113.1 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.113.1",
+  "version": "1.0.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.113.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "1.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli.integration.test.ts

@@ -204,35 +204,6 @@ export const FEATURES = [];
     expect(code).toBe(0);
     expect(cap.log.join("\n")).toContain("feature configuration is valid");
   });
-
-  test("FEATURES with a bad nav→screen ref → validateBoot fails, exit 1 (512/1)", async () => {
-    // Absolute file import (not the package name): appCwd is a bare tmpdir
-    // with no node_modules of its own — a real app resolves
-    // "@cosmicdrift/kumiko-framework/engine" via its own install, but this
-    // synthetic fixture needs a resolvable path regardless of cwd.
-    const engineSrc = join(import.meta.dir, "../engine/index.ts");
-    writeFileSync(
-      join(appCwd, "kumiko/schema.ts"),
-      `import { defineFeature } from "${engineSrc}";
-export const ENTITY_METAS = [
-  { tableName: "read_widgets", source: "unmanaged", indexes: [],
-    columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true, defaultSql: "gen_random_uuid()" }] },
-];
-export const FEATURES = [
-  defineFeature("probe", (r) => {
-    r.nav({ id: "nav-ghost", label: "Ghost", screen: "probe:screen:ghost" });
-  }),
-];
-`,
-    );
-    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
-    const cap = captureOut();
-    const code = await runSchemaCli(["validate"], appCwd, cap.out);
-    expect(code).toBe(1);
-    expect(cap.err.join("\n")).toContain("boot:");
-    expect(cap.err.join("\n")).toContain("probe:screen:ghost");
-    expect(cap.err.join("\n")).toContain("is not registered");
-  });
 });
 
 describe("runSchemaCli — DB-backed paths", () => {

package/src/api/__tests__/batch.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
-import type { TableColumns } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
@@ -37,9 +36,7 @@ const auditEntity = createEntity({
     itemId: createTextField({ required: true }),
   },
 });
-// Brand (#742) is compile-time-only; the postSave hook writes this sink via method-form,
-// so hold it at the unbranded TableColumns view (identical runtime shape).
-const auditTable: TableColumns = buildEntityTable("audit", auditEntity);
+const auditTable = buildEntityTable("audit", auditEntity);
 
 // Hook invocation logs — reset per test. Captures which phase each hook saw.
 const inTxHookLog: Array<{ id: EntityId; name: string }> = [];

package/src/api/__tests__/request-id-middleware.test.ts

@@ -70,54 +70,3 @@ describe("requestIdMiddleware — signal propagation", () => {
     expect(captured?.aborted).toBe(true);
   });
 });
-describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
-  test("populates ip from x-forwarded-for and userAgent from the User-Agent header", async () => {
-    let captured: { ip: string | undefined; userAgent: string | undefined } = {
-      ip: undefined,
-      userAgent: undefined,
-    };
-
-    const app = new Hono();
-    app.use("/probe", requestIdMiddleware());
-    app.get("/probe", (c) => {
-      const ctx = requestContext.get();
-      captured = { ip: ctx?.ip, userAgent: ctx?.userAgent };
-      return c.text("ok");
-    });
-
-    const res = await app.request(
-      new Request("http://test.local/probe", {
-        method: "GET",
-        headers: {
-          "x-forwarded-for": "203.0.113.7, 10.0.0.1",
-          "user-agent": "Mozilla/5.0 (probe-test)",
-        },
-      }),
-    );
-
-    expect(res.status).toBe(200);
-    expect(captured.ip).toBe("203.0.113.7");
-    expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
-  });
-
-  test("no User-Agent header → userAgent stays undefined, not an empty string", async () => {
-    let captured: string | undefined = "unset";
-
-    const app = new Hono();
-    app.use("/probe", requestIdMiddleware());
-    app.get("/probe", (c) => {
-      captured = requestContext.get()?.userAgent;
-      return c.text("ok");
-    });
-
-    // fetch/undici always add a default User-Agent unless explicitly cleared —
-    // Hono's app.request accepts a raw Request, so an empty-but-present header
-    // simulates a client that sends the header with no value.
-    const res = await app.request(
-      new Request("http://test.local/probe", { method: "GET", headers: {} }),
-    );
-
-    expect(res.status).toBe(200);
-    expect(captured).toBeUndefined();
-  });
-});

package/src/api/auth-middleware.ts

@@ -16,12 +16,6 @@ export const AUTH_COOKIE_NAME = "kumiko_auth";
 export const CSRF_COOKIE_NAME = "kumiko_csrf";
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
 
-// Prefix that marks a bearer token as a long-lived Personal Access Token
-// rather than a JWT session. The PAT feature mints tokens with this prefix;
-// the middleware uses it to route to patResolver instead of jwt.verify. Kept
-// here so both sides import the same literal.
-export const PAT_TOKEN_PREFIX = "kpat_";
-
 // Which wire the current request authenticated over. Downstream
 // csrf-middleware reads this: cookie-auth gets a CSRF-token check, bearer
 // does not (headers aren't set cross-origin by browsers, so there is no
@@ -47,23 +41,11 @@ export type AuthSessionChecker = (
   expectedUserId: string,
 ) => Promise<AuthSessionStatus>;
 
-// Resolves a raw Personal Access Token (bearer, prefixed PAT_TOKEN_PREFIX)
-// into a SessionUser, or null when the token is unknown/revoked/expired. The
-// PAT feature owns the DB-backed implementation: hash the token, look up the
-// row, resolve the user's CURRENT roles live (not a snapshot), and expand the
-// token's granted scopes into `pat.allowedQns`. Middleware just consults it
-// and short-circuits the JWT path on a hit.
-export type PatResolver = (rawToken: string) => Promise<SessionUser | null>;
-
 export type AuthMiddlewareOptions = {
   // Called after JWT-verify when the token carries a sid. If the checker
   // reports anything other than "live", the request is rejected with 401.
   // Omit to run in stateless-JWT mode (any valid JWT is accepted).
   readonly sessionChecker?: AuthSessionChecker;
-  // Called for bearer tokens carrying the PAT prefix, BEFORE jwt.verify. On a
-  // hit the middleware sets the returned SessionUser and skips the JWT path
-  // entirely. Omit to disable PAT auth (bearer PATs then fail jwt.verify → 401).
-  readonly patResolver?: PatResolver;
   // When true, a JWT WITHOUT a sid is rejected. Leave false during rollout
   // so already-issued stateless JWTs keep working until they expire; flip
   // to true once the server has been emitting sid for longer than the JWT
@@ -187,7 +169,7 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, strictMode = false, anonymousAccess, patResolver } = options;
+  const { sessionChecker, strictMode = false, anonymousAccess } = options;
 
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
@@ -230,13 +212,6 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
     const { token, transport } = extracted;
 
-    // PAT path: a bearer token carrying the PAT prefix is a long-lived
-    // Personal Access Token, not a JWT. Short-circuit the JWT path entirely.
-    // Cookie transport is never a PAT (the browser holds the JWT).
-    if (patResolver && transport === "bearer" && token.startsWith(PAT_TOKEN_PREFIX)) {
-      return await handlePat(c, patResolver, token, next);
-    }
-
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
     try {
       payload = await jwt.verify(token);
@@ -302,45 +277,6 @@ export function getAuthTransport(c: Context): AuthTransport | undefined {
   return c.get(AUTH_TRANSPORT_KEY) as AuthTransport | undefined;
 }
 
-// PAT request flow. Resolve the hashed token → SessionUser (live roles +
-// granted scopes), then apply the same X-Tenant-mismatch guard as the JWT
-// path before continuing. A null resolve is an invalid/revoked/expired token
-// → 401. Structured like handleAnonymous so authMiddleware stays flat.
-async function handlePat(
-  c: Context,
-  patResolver: PatResolver,
-  token: string,
-  next: Next,
-): Promise<Response | undefined> {
-  const patUser = await patResolver(token);
-  if (!patUser) {
-    return middlewareReject(c, {
-      code: "invalid_token",
-      status: 401,
-      message: "personal access token invalid, revoked or expired",
-      i18nKey: "auth.errors.invalidToken",
-    });
-  }
-  // The PAT carries its own tenant; an X-Tenant header pointing elsewhere is a
-  // confused client — reject loudly, same stance as the JWT path.
-  const headerTenant = c.req.header(TENANT_HEADER_NAME);
-  if (headerTenant !== undefined && headerTenant !== patUser.tenantId) {
-    return middlewareReject(c, {
-      code: "tenant_mismatch",
-      status: 400,
-      message: "PAT tenantId and X-Tenant header disagree",
-      i18nKey: "auth.errors.tenantMismatch",
-      details: { patTenantId: patUser.tenantId, headerTenantId: headerTenant },
-    });
-  }
-  c.set(USER_KEY, patUser);
-  c.set(AUTH_TRANSPORT_KEY, "bearer");
-  await next();
-  // skip: PAT path completed — next() ran; explicit return keeps the
-  // Response|undefined union honest (same as handleAnonymous).
-  return;
-}
-
 // Anonymous request flow. Steps:
 //   1. Read raw client-supplied tenant from X-Tenant header / cookie.
 //   2. Validate format (UUID-shape) — junk strings get 400 right here.

package/src/api/auth-routes.ts

@@ -15,7 +15,6 @@ import {
   type AuthSessionStatus,
   CSRF_COOKIE_NAME,
   getUser,
-  type PatResolver,
 } from "./auth-middleware";
 import type { JwtHelper } from "./jwt";
 import { generateToken } from "./tokens";
@@ -233,16 +232,6 @@ export type AuthRoutesConfig = {
   // once all fresh JWTs emit a sid and the legacy stateless tokens are
   // expected to have expired. Default false keeps old tokens working.
   sessionStrictMode?: boolean;
-  // Resolves bearer Personal Access Tokens (PAT_TOKEN_PREFIX) into a
-  // SessionUser, consulted BEFORE jwt.verify. Wired by the
-  // personal-access-tokens feature; unwired = PAT auth disabled.
-  patResolver?: PatResolver;
-  // Per-token request-rate limiter for PAT-authenticated requests, keyed by
-  // the token id (SessionUser.pat.tokenId). Cookie/JWT requests are unaffected.
-  // Reuses the LoginRateLimiter shape (a generic keyed check/reset limiter).
-  // Wired by run-prod-app when the PAT feature is mounted; unwired = no PAT
-  // rate limiting.
-  patRateLimiter?: LoginRateLimiter;
   // Password-reset flow. When wired, POST /auth/request-password-reset and
   // POST /auth/reset-password are mounted as public routes. The framework
   // dispatches to the feature-level handlers (authoring QNs typically come

package/src/api/index.ts

@@ -5,11 +5,10 @@ export type {
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,
-  PatResolver,
   TenantExists,
   TenantResolver,
 } from "./auth-middleware";
-export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";
+export { authMiddleware, getUser } from "./auth-middleware";
 export type {
   AuthRoutesConfig,
   LoginRateLimiter,
@@ -31,7 +30,6 @@ export {
 } from "./http-cache";
 export type { JwtHelper, JwtPayload } from "./jwt";
 export { createJwtHelper } from "./jwt";
-export { patAllows, qnMatches } from "./pat-scope";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";

package/src/api/jwt.ts

@@ -50,7 +50,10 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
     async verify(token) {
       const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
 
-      // defence-in-depth: valid sig ≠ well-formed claims; malformed payload → throw → 401
+      // Defence in depth: a valid signature does not guarantee well-formed claims. A
+      // leaked secret, key confusion, or a hand-crafted token can still carry junk —
+      // validate the claim shape and reject (verify() throws → 401 in auth-middleware)
+      // instead of casting blindly.
       const tenantId = parseTenantId(payload["tenantId"]);
       if (tenantId === null) {
         throw new Error("JWT payload validation failed: tenantId claim is missing or malformed");

package/src/api/request-context.ts

@@ -30,9 +30,6 @@ export type RequestContextData = {
   // Populated by requestIdMiddleware from x-forwarded-for or the
   // socket address. Undefined for non-HTTP entry points (jobs, MSP).
   readonly ip?: string;
-  // Raw User-Agent header — audit trails (download tokens, GDPR export
-  // access) want it alongside `ip`. Undefined for non-HTTP entry points.
-  readonly userAgent?: string;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();

package/src/api/request-id-middleware.ts

@@ -37,14 +37,12 @@ export function requestIdMiddleware() {
     // than fabricate one.
     const xff = c.req.header("x-forwarded-for");
     const ip = xff?.split(",")[0]?.trim();
-    const userAgent = c.req.header("user-agent");
     await requestContext.run(
       {
         requestId,
         correlationId,
         ...(signal ? { signal } : {}),
         ...(ip && ip.length > 0 ? { ip } : {}),
-        ...(userAgent !== undefined ? { userAgent } : {}),
       },
       () => next(),
     );

package/src/api/routes.ts

@@ -1,8 +1,6 @@
 import { type Context, Hono } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
-import type { SessionUser } from "../engine/types/handlers";
 import {
-  AccessDeniedError,
   type KumikoError,
   reraiseAsKumikoError,
   serializeError,
@@ -14,7 +12,6 @@ import type { Dispatcher } from "../pipeline/dispatcher";
 import { stringifyJson } from "../utils/safe-json";
 import { Routes } from "./api-constants";
 import { getUser } from "./auth-middleware";
-import { patAllows } from "./pat-scope";
 import { requestContext } from "./request-context";
 
 export function createApiRoutes(dispatcher: Dispatcher) {
@@ -25,7 +22,6 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown; requestId?: string }>();
 
     try {
-      assertPatAllowed(user, body.type);
       const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
       if (!result.isSuccess) {
         return writeErrorResponse(c, reraiseAsKumikoError(result.error), body.type);
@@ -63,9 +59,6 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     }
 
     try {
-      if (user.pat) {
-        for (const cmd of body.commands) assertPatAllowed(user, cmd.type);
-      }
       const result = await dispatcher.batch(body.commands, user, body.requestId);
       if (!result.isSuccess) {
         const err = reraiseAsKumikoError(result.error);
@@ -90,10 +83,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       }
       return c.json(result);
     } catch (e) {
-      // 615/1: pass the batch's command types, not undefined — a single
-      // "type" doesn't apply to a batch, but logging none loses the fault
-      // context entirely.
-      return writeErrorResponse(c, toKumiko(e), body.commands?.map((cmd) => cmd.type).join(","));
+      return writeErrorResponse(c, toKumiko(e));
     }
   });
 
@@ -102,7 +92,6 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
-      assertPatAllowed(user, body.type);
       const result = await dispatcher.query(body.type, body.payload, user);
       return jsonResponse(c, { data: result });
     } catch (e) {
@@ -115,7 +104,6 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
-      assertPatAllowed(user, body.type);
       await dispatcher.command(body.type, body.payload, user);
       return c.json({ ok: true }, 202);
     } catch (e) {
@@ -132,19 +120,6 @@ function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode =
 
 const toKumiko = toKumikoError;
 
-// PAT scope enforcement at the API boundary. No-op for cookie/JWT users
-// (user.pat undefined → unrestricted). For a PAT-authenticated request the
-// dispatch type must match one of the token's granted-scope QN globs, else
-// 403 — fail-closed, thrown so each route's existing catch shapes the body.
-function assertPatAllowed(user: SessionUser, type: string): void {
-  if (user.pat && !patAllows(user.pat.allowedQns, type)) {
-    throw new AccessDeniedError({
-      message: `personal access token scope does not permit ${type}`,
-      details: { handler: type, scopes: user.pat.scopes },
-    });
-  }
-}
-
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero

package/src/api/server.ts

@@ -46,7 +46,7 @@ import {
 import type { SearchAdapter } from "../search/types";
 import { assertUnreachable, generateId } from "../utils";
 import { PUBLIC_API_PATHS } from "./api-constants";
-import { type AnonymousAccessConfig, authMiddleware, getUser } from "./auth-middleware";
+import { type AnonymousAccessConfig, authMiddleware } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
 import { createJwtHelper, type JwtHelper } from "./jwt";
@@ -561,7 +561,6 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
-    ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {
@@ -569,33 +568,6 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return jwtGuard(c, next);
   });
 
-  // PAT rate limiting — runs AFTER the auth guard so the resolved principal is
-  // available. Only PAT-authenticated requests are counted (keyed by token id);
-  // cookie/JWT users pass through untouched. In-memory limiter is per-instance
-  // (see run-prod-app) — a multi-node deployment wanting a shared counter swaps
-  // in a Redis-backed LoginRateLimiter.
-  const patRateLimiter = options.auth?.patRateLimiter;
-  if (patRateLimiter) {
-    app.use("/api/*", async (c, next) => {
-      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
-      const pat = getUser(c)?.pat;
-      if (pat && !(await patRateLimiter.check(pat.tokenId))) {
-        return c.json(
-          {
-            error: {
-              code: "pat_rate_limited",
-              httpStatus: 429,
-              message: "personal access token rate limit exceeded",
-              i18nKey: "auth.errors.patRateLimited",
-            },
-          },
-          429,
-        );
-      }
-      return next();
-    });
-  }
-
   // Origin-allowlist guard — additional CSRF-hardening for deployments that
   // widen the auth cookie across subdomains (auth.cookieDomain). Registered
   // only when allowedOrigins is non-empty, with the same /api/* + public-skip

package/src/bun-db/__tests__/write-brand.test.ts

@@ -8,7 +8,6 @@
 import { expect, test } from "bun:test";
 import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { buildEntityTable } from "../../db/table-builder";
-import type { TenantDb } from "../../db/tenant-db";
 import { createEntity, createTextField } from "../../engine";
 import { type AnyDb, deleteMany, insertOne, selectMany, updateMany } from "../query";
 
@@ -42,28 +41,8 @@ async function _readAllowsManagedEntity(db: AnyDb): Promise<void> {
   await selectMany(db, brandedEntity, { id: "1" });
 }
 
-// Method-form (ctx.db.insertOne/updateMany/deleteMany) rejects the brand too — a
-// projection written past its event stream is wiped on rebuild whether the write
-// went through the free function or the TenantDb method.
-async function _methodFormRejectsManagedEntity(db: TenantDb): Promise<void> {
-  // @ts-expect-error — managed EntityTable is executor-only; method-form insert is a compile error.
-  await db.insertOne(brandedEntity, { title: "x" });
-  // @ts-expect-error — method-form update on a managed EntityTable is rejected.
-  await db.updateMany(brandedEntity, { title: "y" }, { id: "1" });
-  // @ts-expect-error — method-form delete on a managed EntityTable is rejected.
-  await db.deleteMany(brandedEntity, { id: "1" });
-}
-
-async function _methodFormReadAllowsManagedEntity(db: TenantDb): Promise<void> {
-  // Method-form reads on a managed EntityTable stay fine (reads keep the plain param).
-  await db.selectMany(brandedEntity, { id: "1" });
-  await db.fetchOne(brandedEntity, { id: "1" });
-}
-
 test("ES-write brand: compile-time contracts are wired", () => {
   expect(_writeRejectsManagedEntity).toBeDefined();
   expect(_writeAllowsUnmanagedTable).toBeDefined();
   expect(_readAllowsManagedEntity).toBeDefined();
-  expect(_methodFormRejectsManagedEntity).toBeDefined();
-  expect(_methodFormReadAllowsManagedEntity).toBeDefined();
 });

package/src/bun-db/query.ts

@@ -109,23 +109,6 @@ export function asRawClient(db: unknown): RawClient {
   );
 }
 
-// postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
-// it errored — even if the JS error was caught (the driver tracks per-block
-// query failures). Error confinement therefore must go through the driver's
-// own savepoint(), not manual SAVEPOINT statements. The callback receives
-// the savepoint-scoped tx; run every confined statement on THAT handle.
-export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T> {
-  const raw = asRawClient(tx) as unknown as {
-    savepoint?: <TR>(cb: (sp: unknown) => Promise<TR>) => Promise<TR>;
-  };
-  if (typeof raw.savepoint !== "function") {
-    throw new Error(
-      "runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql / Bun.SQL).",
-    );
-  }
-  return raw.savepoint(fn);
-}
-
 /**
  * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
  * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and

package/src/db/__tests__/config-seed.integration.test.ts

@@ -10,11 +10,10 @@ import {
   SYSTEM_TENANT_ID,
 } from "../../engine";
 import type { ConfigSeedDef, Registry } from "../../engine/types";
-import { createEnvMasterKeyProvider } from "../../secrets/env-master-key-provider";
-import { createEnvelopeCipher } from "../../secrets/envelope-cipher";
 import { unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { seedConfigValues } from "../config-seed";
+import { createEncryptionProvider } from "../encryption";
 import { buildEntityTable } from "../table-builder";
 
 // --- Test Entity ---
@@ -52,15 +51,8 @@ const mockRegistry = {
 } as unknown as Registry;
 
 // --- Helpers ---
-const encryption = createEnvelopeCipher(
-  createEnvMasterKeyProvider({
-    env: {
-      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
-      KUMIKO_SECRETS_MASTER_KEY_V1: Buffer.from("0123456789abcdef0123456789abcdef").toString(
-        "base64",
-      ),
-    },
-  }),
+const encryption = createEncryptionProvider(
+  Buffer.from("0123456789abcdef0123456789abcdef").toString("base64"),
 );
 
 let testDb: BunTestDb;
@@ -222,7 +214,7 @@ describe("seedConfigValues", () => {
 
     await expect(
       seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
-    ).rejects.toThrow(/encrypted but no EnvelopeCipher/);
+    ).rejects.toThrow(/encrypted but no EncryptionProvider/);
   });
 
   test("encrypted seed with provider stores ciphertext, not plaintext", async () => {
@@ -248,7 +240,7 @@ describe("seedConfigValues", () => {
     // resolver later runs `decrypt → JSON.parse` to get the primitive
     // back; we replay the same round-trip here.
     expect(row!.value).not.toContain("sk_live_secret_token");
-    expect(JSON.parse(await encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
+    expect(JSON.parse(encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
   });
 
   test("race-safe parallel boot — two concurrent calls result in 1 created + 1 skipped", async () => {

package/src/db/__tests__/entity-field-encryption.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
-import { createTestEnvelopeCipher } from "../../testing";
+import { createEncryptionProvider } from "../encryption";
 import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
@@ -18,25 +18,25 @@ describe("entity-field-encryption", () => {
     },
   });
   const encryptedFields = collectEncryptedFieldNames(entity);
-  const encryption = createTestEnvelopeCipher(TEST_KEY);
+  const encryption = createEncryptionProvider(TEST_KEY);
 
   test("collectEncryptedFieldNames finds encrypted text fields only", () => {
     expect([...encryptedFields]).toEqual(["secretNote"]);
   });
 
-  test("encrypt on write / decrypt on read round-trip", async () => {
+  test("encrypt on write / decrypt on read round-trip", () => {
     const plain = { email: "a@b.de", secretNote: "top secret" };
-    const stored = await encryptEntityFieldValues(plain, encryptedFields, encryption);
+    const stored = encryptEntityFieldValues(plain, encryptedFields, encryption);
     expect(stored["email"]).toBe(plain.email);
     expect(stored["secretNote"]).not.toBe("top secret");
 
-    const read = await decryptEntityFieldValues(stored, encryptedFields, encryption);
+    const read = decryptEntityFieldValues(stored, encryptedFields, encryption);
     expect(read).toEqual(plain);
   });
 
-  test("onlyKeys limits encryption to changed fields", async () => {
+  test("onlyKeys limits encryption to changed fields", () => {
     const row = { email: "a@b.de", secretNote: "note" };
-    const stored = await encryptEntityFieldValues(row, encryptedFields, encryption, {
+    const stored = encryptEntityFieldValues(row, encryptedFields, encryption, {
       onlyKeys: ["secretNote"],
     });
     expect(stored["email"]).toBe("a@b.de");

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -10,7 +10,7 @@ import {
   testTenantId,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { createTestEnvelopeCipher } from "../../testing";
+import { createEncryptionProvider } from "../encryption";
 import { resetEntityFieldEncryptionCacheForTests } from "../entity-field-encryption";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
@@ -324,7 +324,7 @@ const encryptedSoftDeleteEntity = createEntity({
 const encryptedSoftDeleteTable = buildEntityTable("esExecEncSoft", encryptedSoftDeleteEntity);
 
 describe("event-store-executor — encrypted fields", () => {
-  const encryption = createTestEnvelopeCipher(ENCRYPTION_TEST_KEY);
+  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
   const crud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
     entityName: "esExecEncrypted",
     encryption,
@@ -337,6 +337,7 @@ describe("event-store-executor — encrypted fields", () => {
   );
 
   beforeAll(async () => {
+    process.env["ENCRYPTION_KEY"] = ENCRYPTION_TEST_KEY;
     resetEntityFieldEncryptionCacheForTests();
     await unsafeCreateEntityTable(testDb.db, encryptedEntity, "esExecEncrypted");
     await unsafeCreateEntityTable(testDb.db, encryptedSoftDeleteEntity, "esExecEncSoft");
@@ -523,7 +524,7 @@ describe("event-store-executor — entity cache + encrypted fields", () => {
       store.delete(`${tenantId}:${name}:${id}`);
     },
   };
-  const encryption = createTestEnvelopeCipher(ENCRYPTION_TEST_KEY);
+  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
   const cachedEncryptedCrud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
     entityName: "esExecEncrypted",
     entityCache,

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
 import { testTenantId } from "../../stack";
-import type { TableColumns } from "../dialect";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -14,9 +13,7 @@ const entity = createEntity({
   table: "merge_items",
   fields: { name: createTextField({ required: true }) },
 });
-// Brand (#742) is compile-time-only; hold the handle at the unbranded TableColumns
-// view so the method-form scoping test still compiles (runtime shape is identical).
-const table: TableColumns = buildEntityTable("mergeItem", entity);
+const table = buildEntityTable("mergeItem", entity);
 
 const own = testTenantId(1);
 const foreign = testTenantId(2);