@cosmicdrift/kumiko-dev-server 0.105.1 → 0.108.0

package/src/__tests__/scaffold-app.test.ts

@@ -1,4 +1,4 @@
-// scaffoldApp unit-tests (DX-1.0).
+// scaffoldApp unit-tests (DX-1.0 + #352 deploy/schema scaffold).
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -6,6 +6,29 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { scaffoldApp } from "../scaffold-app";
 
+const SCAFFOLD_FILES = [
+  "package.json",
+  "tsconfig.json",
+  "biome.json",
+  "bunfig.toml",
+  "bunfig.ci.toml",
+  "src/run-config.ts",
+  "kumiko/schema.ts",
+  "bin/main.ts",
+  "bin/dev.ts",
+  "bin/kumiko.ts",
+  "src/client.tsx",
+  "src/styles.css",
+  ".env.example",
+  "docker-compose.yml",
+  "kumiko/migrations/0001_init.sql",
+  "kumiko/migrations/.snapshot.json",
+  "deploy/Dockerfile",
+  "deploy/Dockerfile.dockerignore",
+  "deploy/migrate-step.sh",
+  "README.md",
+] as const;
+
 describe("scaffoldApp", () => {
   let tmp: string;
   beforeEach(() => {
@@ -15,31 +38,21 @@ describe("scaffoldApp", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("scaffolds the expected files into <cwd>/<name>", () => {
+  test("scaffolds the expected files into <cwd>/<name>", async () => {
     const dest = join(tmp, "my-shop");
-    const result = scaffoldApp({ name: "my-shop", destination: dest });
+    const result = await scaffoldApp({ name: "my-shop", destination: dest });
 
     expect(result.appName).toBe("my-shop");
     expect(result.destination).toBe(dest);
-    expect(result.files).toEqual([
-      "package.json",
-      "tsconfig.json",
-      "src/run-config.ts",
-      "bin/main.ts",
-      "bin/dev.ts",
-      "src/client.tsx",
-      ".env.example",
-      "docker-compose.yml",
-      "README.md",
-    ]);
-    for (const f of result.files) {
+    for (const f of SCAFFOLD_FILES) {
+      expect(result.files).toContain(f);
       expect(existsSync(join(dest, f))).toBe(true);
     }
   });
 
-  test("package.json has @cosmicdrift/* deps with version pin", () => {
+  test("package.json has @cosmicdrift/* deps with version pin", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest, frameworkVersion: "^0.13.0" });
+    await scaffoldApp({ name: "my-shop", destination: dest, frameworkVersion: "^0.13.0" });
 
     const pkg = JSON.parse(readFileSync(join(dest, "package.json"), "utf-8")) as {
       name: string;
@@ -53,70 +66,82 @@ describe("scaffoldApp", () => {
     expect(pkg.dependencies["@cosmicdrift/kumiko-renderer-web"]).toBe("^0.13.0");
     expect(pkg.scripts["boot"]).toContain("KUMIKO_DRY_RUN_ENV=boot");
     expect(pkg.scripts["dev"]).toBe("bun --watch bin/dev.ts");
+    expect(pkg.scripts["build"]).toBe("bun kumiko-build");
+    expect(pkg.scripts["start"]).toBe("bun run bin/main.ts");
+    expect(pkg.scripts["lint"]).toBe("biome check .");
+  });
+
+  test("init migration includes auth-mode tables (read_users)", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const sql = readFileSync(join(dest, "kumiko/migrations/0001_init.sql"), "utf-8");
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "read_users"');
   });
 
-  test("bin/dev.ts contains runDevApp + welcomeBanner + admin login + clientEntry", () => {
+  test("kumiko/schema.ts + bin/kumiko.ts wire HAS_AUTH single-source", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const schema = readFileSync(join(dest, "kumiko/schema.ts"), "utf-8");
+    expect(schema).toContain("APP_FEATURES, HAS_AUTH");
+    expect(schema).toContain("collectTableMetas");
+
+    const kumikoBin = readFileSync(join(dest, "bin/kumiko.ts"), "utf-8");
+    expect(kumikoBin).toContain("runSchemaCli");
+    expect(kumikoBin).toContain("includeBundled: HAS_AUTH");
+  });
+
+  test("bin/dev.ts contains runDevApp + welcomeBanner + admin login + clientEntry", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const dev = readFileSync(join(dest, "bin/dev.ts"), "utf-8");
     expect(dev).toContain("runDevApp");
     expect(dev).toContain("welcomeBanner: true");
     expect(dev).toContain("admin@my-shop.local");
     expect(dev).toContain(`password: "changeme"`);
-    // Without clientEntry the default HTML still <script src="/client.js">'s,
-    // and the dev-server 404s on it — every fresh scaffold rendered blank.
     expect(dev).toContain(`clientEntry: "./src/client.tsx"`);
   });
 
-  test("src/client.tsx bundles createKumikoApp + emailPasswordClient + DefaultAppShell", () => {
+  test("src/client.tsx bundles createKumikoApp + emailPasswordClient + DefaultAppShell", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const client = readFileSync(join(dest, "src/client.tsx"), "utf-8");
     expect(client).toContain("createKumikoApp");
     expect(client).toContain("emailPasswordClient");
-    // Without shell:DefaultAppShell post-login renders only the active
-    // screen (no sidebar / topbar) — the e2e hero-demo proved this dead-
-    // ends on "Screen not found" because routing has no layout chrome.
     expect(client).toContain("DefaultAppShell");
     expect(client).toContain("shell: DefaultAppShell");
     expect(client).toContain('from "@cosmicdrift/kumiko-renderer-web"');
     expect(client).toContain('from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web"');
   });
 
-  test(".env.example carries KUMIKO_DEV_DB_NAME default so reboots are persistent", () => {
+  test(".env.example carries KUMIKO_DEV_DB_NAME default so reboots are persistent", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const env = readFileSync(join(dest, ".env.example"), "utf-8");
     expect(env).toContain("KUMIKO_DEV_DB_NAME=my_shop_dev");
   });
 
-  test(".env.example lists both TEST_DATABASE_URL (bun dev) + DATABASE_URL (prod)", () => {
+  test(".env.example lists both TEST_DATABASE_URL (bun dev) + DATABASE_URL (prod)", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const env = readFileSync(join(dest, ".env.example"), "utf-8");
-    // runDevApp → setupTestStack needs TEST_DATABASE_URL; previously the
-    // template only listed DATABASE_URL, so every fresh `bun dev` crashed
-    // with "Missing required env var: TEST_DATABASE_URL".
     expect(env).toContain("TEST_DATABASE_URL=");
     expect(env).toContain("DATABASE_URL=");
   });
 
-  test("docker-compose.yml ports + credentials match the .env.example *_URL defaults", () => {
+  test("docker-compose.yml ports + credentials match the .env.example *_URL defaults", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const compose = readFileSync(join(dest, "docker-compose.yml"), "utf-8");
     const env = readFileSync(join(dest, ".env.example"), "utf-8");
-    // README tells the user to run `docker compose up -d`; that only works if
-    // the compose service matches what the generated .env points its *_URLs at.
     expect(env).toContain("127.0.0.1:5432");
     expect(env).toContain("127.0.0.1:6379");
-    // Ports bind to loopback only — weak dev creds / auth-less Redis must not
-    // be reachable from the LAN (security review of the scaffold).
     expect(compose).toContain('"127.0.0.1:5432:5432"');
     expect(compose).toContain('"127.0.0.1:6379:6379"');
     expect(compose).not.toContain('"5432:5432"');
@@ -126,9 +151,9 @@ describe("scaffoldApp", () => {
     expect(compose).toContain("image: redis:");
   });
 
-  test("README lists the mounted features dynamically", () => {
+  test("README lists the mounted features dynamically", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({
+    await scaffoldApp({
       name: "my-shop",
       destination: dest,
       features: [
@@ -153,78 +178,75 @@ describe("scaffoldApp", () => {
     expect(readme).toContain("- `delivery`");
   });
 
-  test("bin/main.ts contains runProdApp + auth.admin stub", () => {
+  test("bin/main.ts contains runProdApp + auth.admin stub + staticDir", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
     expect(main).toContain("runProdApp");
+    expect(main).toContain('staticDir: "./dist"');
     expect(main).toContain("auth: {");
     expect(main).toContain("admin@my-shop.local");
     expect(main).toContain('tenantKey: "my-shop"');
-    // Tenant-ID is a valid UUID-v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx).
     expect(main).toMatch(/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/);
   });
 
-  test("bin/main.ts composes the auth-mode feature set into envSchema (JWT_SECRET boot-gate)", () => {
+  test("bin/main.ts composes the auth-mode feature set into envSchema (JWT_SECRET boot-gate)", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
-    // envSchema must cover the same features runProdApp auto-mixes via
-    // auth-mode — otherwise auth-email-password's JWT_SECRET (min-32) is
-    // absent from the boot-gate and a too-short secret slips through.
-    expect(main).toContain("composeFeatures(APP_FEATURES, { includeBundled: true })");
+    expect(main).toContain("composeFeatures(APP_FEATURES, { includeBundled: HAS_AUTH })");
     expect(main).toContain(
       "composeEnvSchema({ core: frameworkCoreEnvSchema, features: bootFeatures })",
     );
-    expect(main).toContain("composeFeatures");
   });
 
-  test("src/run-config.ts mounts secrets + sessions as foundation", () => {
+  test("src/run-config.ts mounts secrets + sessions + HAS_AUTH", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const runConfig = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
     expect(runConfig).toContain("createSecretsFeature()");
     expect(runConfig).toContain("createSessionsFeature()");
     expect(runConfig).toContain("export const APP_FEATURES");
+    expect(runConfig).toContain("export const HAS_AUTH");
   });
 
-  test("rejects non-kebab-case names", () => {
-    expect(() => scaffoldApp({ name: "MyShop", destination: tmp })).toThrow(/kebab-case/);
-    expect(() => scaffoldApp({ name: "my_shop", destination: tmp })).toThrow(/kebab-case/);
-    expect(() => scaffoldApp({ name: "0shop", destination: tmp })).toThrow(/kebab-case/);
+  test("rejects non-kebab-case names", async () => {
+    await expect(scaffoldApp({ name: "MyShop", destination: tmp })).rejects.toThrow(/kebab-case/);
+    await expect(scaffoldApp({ name: "my_shop", destination: tmp })).rejects.toThrow(/kebab-case/);
+    await expect(scaffoldApp({ name: "0shop", destination: tmp })).rejects.toThrow(/kebab-case/);
   });
 
-  test("rejects trailing- and double-hyphen names (invalid package segment)", () => {
-    expect(() => scaffoldApp({ name: "my-shop-", destination: tmp })).toThrow(/kebab-case/);
-    expect(() => scaffoldApp({ name: "my--shop", destination: tmp })).toThrow(/kebab-case/);
+  test("rejects trailing- and double-hyphen names (invalid package segment)", async () => {
+    await expect(scaffoldApp({ name: "my-shop-", destination: tmp })).rejects.toThrow(/kebab-case/);
+    await expect(scaffoldApp({ name: "my--shop", destination: tmp })).rejects.toThrow(/kebab-case/);
   });
 
-  test("resolves a relative destination against the supplied cwd, not process.cwd()", () => {
-    // The CLI passes ctx.cwd; the scaffold must land under it so the
-    // displayed path matches the actual write location.
-    const result = scaffoldApp({ name: "shop", destination: "apps/shop", cwd: tmp });
+  test("resolves a relative destination against the supplied cwd, not process.cwd()", async () => {
+    const result = await scaffoldApp({ name: "shop", destination: "apps/shop", cwd: tmp });
     expect(result.destination).toBe(join(tmp, "apps/shop"));
     expect(existsSync(join(tmp, "apps/shop", "package.json"))).toBe(true);
   });
 
-  test("resolves the name-default destination against the supplied cwd", () => {
-    const result = scaffoldApp({ name: "shop", cwd: tmp });
+  test("resolves the name-default destination against the supplied cwd", async () => {
+    const result = await scaffoldApp({ name: "shop", cwd: tmp });
     expect(result.destination).toBe(join(tmp, "shop"));
     expect(existsSync(join(tmp, "shop", "package.json"))).toBe(true);
   });
 
-  test("refuses to overwrite existing destination", () => {
+  test("refuses to overwrite existing destination", async () => {
     const dest = join(tmp, "existing");
-    scaffoldApp({ name: "existing", destination: dest });
-    expect(() => scaffoldApp({ name: "existing", destination: dest })).toThrow(/already exists/);
+    await scaffoldApp({ name: "existing", destination: dest });
+    await expect(scaffoldApp({ name: "existing", destination: dest })).rejects.toThrow(
+      /already exists/,
+    );
   });
 
-  test("features-param: custom selection lands in run-config.ts imports + APP_FEATURES", () => {
+  test("features-param: custom selection lands in run-config.ts imports + APP_FEATURES", async () => {
     const dest = join(tmp, "custom-features");
-    scaffoldApp({
+    await scaffoldApp({
       name: "custom-features",
       destination: dest,
       features: [
@@ -251,23 +273,20 @@ describe("scaffoldApp", () => {
     expect(cfg).not.toContain("createSessionsFeature");
   });
 
-  test("features-param: empty array falls back to foundation (backwards-compat)", () => {
+  test("features-param: empty array falls back to foundation (backwards-compat)", async () => {
     const dest = join(tmp, "empty-features");
-    scaffoldApp({ name: "empty-features", destination: dest, features: [] });
+    await scaffoldApp({ name: "empty-features", destination: dest, features: [] });
     const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
     expect(cfg).toContain("createSecretsFeature()");
     expect(cfg).toContain("createSessionsFeature()");
   });
 
-  test("features-param: composeFeatures auto-mounted (config/user/tenant/auth-email-password) are filtered out — no boot-time dedupe-warn spam", () => {
+  test("features-param: composeFeatures auto-mounted names are filtered out", async () => {
     const dest = join(tmp, "filtered");
-    scaffoldApp({
+    await scaffoldApp({
       name: "filtered",
       destination: dest,
       features: [
-        // Picker's recommended set includes the 4 auto-mounted bundled
-        // features; without the filter they'd land in APP_FEATURES and
-        // composeFeatures would log 4 dedupe warnings on every boot.
         {
           name: "config",
           importPath: "@cosmicdrift/kumiko-bundled-features/config",
@@ -308,11 +327,48 @@ describe("scaffoldApp", () => {
     expect(cfg).toContain("createDeliveryFeature()");
   });
 
-  test("deterministic tenantId for same name (reproducible boots)", () => {
+  test("features-param: ONLY auto-mounted names → empty effective set, no foundation fallback", async () => {
+    const dest = join(tmp, "only-auto-mounted");
+    await scaffoldApp({
+      name: "only-auto-mounted",
+      destination: dest,
+      features: [
+        {
+          name: "config",
+          importPath: "@cosmicdrift/kumiko-bundled-features/config",
+          exportName: "createConfigFeature",
+          callExpression: "createConfigFeature()",
+        },
+        {
+          name: "user",
+          importPath: "@cosmicdrift/kumiko-bundled-features/user",
+          exportName: "createUserFeature",
+          callExpression: "createUserFeature()",
+        },
+        {
+          name: "tenant",
+          importPath: "@cosmicdrift/kumiko-bundled-features/tenant",
+          exportName: "createTenantFeature",
+          callExpression: "createTenantFeature()",
+        },
+        {
+          name: "auth-email-password",
+          importPath: "@cosmicdrift/kumiko-bundled-features/auth-email-password",
+          exportName: "createAuthEmailPasswordFeature",
+          callExpression: "createAuthEmailPasswordFeature()",
+        },
+      ],
+    });
+    const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
+    expect(cfg).not.toContain("createSecretsFeature");
+    expect(cfg).not.toContain("createSessionsFeature");
+  });
+
+  test("deterministic tenantId for same name (reproducible boots)", async () => {
     const a = join(tmp, "a");
     const b = join(tmp, "b");
-    scaffoldApp({ name: "stable", destination: a });
-    scaffoldApp({ name: "stable", destination: b });
+    await scaffoldApp({ name: "stable", destination: a });
+    await scaffoldApp({ name: "stable", destination: b });
     const mainA = readFileSync(join(a, "bin/main.ts"), "utf-8");
     const mainB = readFileSync(join(b, "bin/main.ts"), "utf-8");
     const uuidA = mainA.match(

package/src/__tests__/session-wiring.test.ts

@@ -1,4 +1,8 @@
 import { describe, expect, it } from "bun:test";
+import {
+  createSessionsFeature,
+  SESSIONS_FEATURE,
+} from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { resolveProdSessionsConfig, shouldWireProdSessions } from "../session-wiring";
 
 describe("shouldWireProdSessions — secure-by-default with opt-out (KF-1)", () => {
@@ -25,6 +29,16 @@ describe("shouldWireProdSessions — secure-by-default with opt-out (KF-1)", ()
   });
 });
 
+describe("SESSIONS_FEATURE constant matches the real feature name", () => {
+  it("createSessionsFeature()'s name equals SESSIONS_FEATURE", () => {
+    // shouldWireProdSessions's own arm only tests the pure boolean helper —
+    // the actual run-prod-app.ts integration seam
+    // (`features.some((f) => f.name === SESSIONS_FEATURE)`) drifts silently
+    // if the feature is ever renamed without updating this constant.
+    expect(createSessionsFeature().name).toBe(SESSIONS_FEATURE);
+  });
+});
+
 describe("resolveProdSessionsConfig", () => {
   it("passes a config object through", () => {
     expect(resolveProdSessionsConfig({ expiresInMs: 5000 })).toEqual({ expiresInMs: 5000 });

package/src/__tests__/walkthrough.integration.test.ts

@@ -32,23 +32,17 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("Step 1 (kumiko new app) — produces walkthrough's scaffold files", () => {
-    const result = scaffoldApp({ name: "my-notes", destination: appRoot });
-    expect(result.files).toEqual([
-      "package.json",
-      "tsconfig.json",
-      "src/run-config.ts",
-      "bin/main.ts",
-      "bin/dev.ts",
-      "src/client.tsx",
-      ".env.example",
-      "docker-compose.yml",
-      "README.md",
-    ]);
+  test("Step 1 (kumiko new app) — produces walkthrough's scaffold files", async () => {
+    const result = await scaffoldApp({ name: "my-notes", destination: appRoot });
+    expect(result.files).toContain("package.json");
+    expect(result.files).toContain("kumiko/schema.ts");
+    expect(result.files).toContain("bin/kumiko.ts");
+    expect(result.files).toContain("deploy/Dockerfile");
+    expect(result.files).toContain("kumiko/migrations/0001_init.sql");
   });
 
-  test("Step 2 (kumiko add feature) — auto-mounts + walkthrough diff matches", () => {
-    scaffoldApp({ name: "my-notes", destination: appRoot });
+  test("Step 2 (kumiko add feature) — auto-mounts + walkthrough diff matches", async () => {
+    await scaffoldApp({ name: "my-notes", destination: appRoot });
     const result = scaffoldAppFeature({ name: "notes", appRoot });
     expect(result.autoMounted).toBe(true);
 
@@ -63,8 +57,8 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     expect(runConfig).toContain("createSessionsFeature()");
   });
 
-  test("Step 3 (boot validation) — scaffolded run-config matches walkthrough's APP_FEATURES claim", () => {
-    scaffoldApp({ name: "my-notes", destination: appRoot });
+  test("Step 3 (boot validation) — scaffolded run-config matches walkthrough's APP_FEATURES claim", async () => {
+    await scaffoldApp({ name: "my-notes", destination: appRoot });
     scaffoldAppFeature({ name: "notes", appRoot });
 
     // Text-assert: scaffolded run-config.ts contains exactly the 3 features
@@ -108,8 +102,8 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     expect(registry.features.size).toBe(7);
   });
 
-  test("bin/main.ts contains the auth.admin stub the walkthrough relies on", () => {
-    scaffoldApp({ name: "my-notes", destination: appRoot });
+  test("bin/main.ts contains the auth.admin stub the walkthrough relies on", async () => {
+    await scaffoldApp({ name: "my-notes", destination: appRoot });
     const main = readFileSync(join(appRoot, "bin/main.ts"), "utf-8");
     // composeFeatures(includeBundled:true)-trigger is `auth: { admin: { … } }`.
     // Walkthrough explicitly says this is what auto-mounts the 4 bundled features.

package/src/run-dev-app.ts

@@ -22,12 +22,19 @@ import {
   buildEnvConfigOverrides,
   createConfigResolver,
 } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createPatResolver,
+  PAT_FEATURE,
+  patRateLimitFromFeature,
+  patScopesFromFeature,
+} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import {
   createSessionCallbacks,
   type SessionCallbacks,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
+import type { PatResolver, SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
+import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
 import {
   collectWriteHandlerQns,
   createRegistry,
@@ -226,9 +233,8 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
-  // Ein explizit gewireter File-Provider (options.files) erfüllt das
-  // FILE_STORAGE_PROVIDER-Boot-Gate — der Provider IST konfiguriert, nur
-  // nicht über die env-Bridge. Setzen bevor validateBoot greift.
+  // An explicitly wired file provider (options.files) satisfies the
+  // FILE_STORAGE_PROVIDER boot gate — set it before validateBoot runs.
   if (options.files !== undefined && process.env["FILE_STORAGE_PROVIDER"] === undefined) {
     process.env["FILE_STORAGE_PROVIDER"] = "configured";
   }
@@ -339,6 +345,26 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     }
     return sessionCallbacks;
   };
+  // PAT opt-in: same late-bound holder pattern — the resolver needs the real
+  // db (only concrete after setupTestStack). Wired when the feature is mounted;
+  // scopes come from the feature's exports (single source with its handlers).
+  let patResolver: PatResolver | undefined;
+  const patFeature = features.find((f) => f.name === PAT_FEATURE);
+  const patAuthFragment = patFeature
+    ? {
+        patResolver: (rawToken: string) => {
+          if (!patResolver) {
+            throw new Error("[runDevApp] pat-resolver accessed before onAfterSetup");
+          }
+          return patResolver(rawToken);
+        },
+        patRateLimiter: (() => {
+          const rl = patRateLimitFromFeature(patFeature);
+          return createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs);
+        })(),
+      }
+    : {};
+
   const sessionAuthFragment =
     effectiveAuth?.sessions !== undefined
       ? {
@@ -392,6 +418,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
         ...sessionAuthFragment,
+        ...patAuthFragment,
         ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,
@@ -437,6 +464,9 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           ...(expiresInMs !== undefined && { expiresInMs }),
         });
       }
+      if (patFeature) {
+        patResolver = createPatResolver({ db: stack.db, scopes: patScopesFromFeature(patFeature) });
+      }
       if (effectiveAuth) {
         await seedAdmin(stack.db, effectiveAuth.admin);
       }

package/src/run-prod-app.ts

@@ -50,6 +50,12 @@ import {
   createDeliveryService,
   DELIVERY_FEATURE,
 } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import {
+  createPatResolver,
+  PAT_FEATURE,
+  patRateLimitFromFeature,
+  patScopesFromFeature,
+} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import {
   createSecretsContext,
   SECRETS_FEATURE_NAME,
@@ -66,6 +72,7 @@ import {
   cachedResponse,
   computeStrongEtag,
   computeWeakEtag,
+  createInMemoryLoginRateLimiter,
   createSseBroker,
   type SseBroker,
 } from "@cosmicdrift/kumiko-framework/api";
@@ -84,7 +91,6 @@ import {
   findTierResolverUsage,
   type NotifyFactory,
   type Registry,
-  type TenantId,
   type TierResolverPlugin,
   validateAppCustomScreenWriteQns,
   validateBoot,
@@ -170,10 +176,11 @@ export function requireEnv(
 ): string {
   const value = src[name];
   if (value === undefined || value === "") {
-    throw new Error(
-      `${context}: required env var "${name}" is missing or empty. ` +
-        `Set it in your container env / .env.production / Coolify secrets.`,
-    );
+    const advice =
+      context === "runProdApp"
+        ? "Set it in your container env / .env.production / Coolify secrets."
+        : "Set it in your .env / shell before running the dev server.";
+    throw new Error(`${context}: required env var "${name}" is missing or empty. ${advice}`);
   }
   return value;
 }
@@ -523,7 +530,7 @@ export type RunProdAppOptions = {
    *  liche features aktiv via globalFeatureToggleRuntime. Pattern:
    *  createLateBoundHolder + post-boot runtime.initialize in einem
    *  seed-fn (db ist erst nach migrations + features ready). */
-  readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+  readonly effectiveFeatures?: EffectiveFeaturesResolver;
   /** Composed Zod-schema for env-validation (from `composeEnvSchema({
    *  features, extend })` in @cosmicdrift/kumiko-framework/env). When set:
    *  - `process.env` is parsed against it BEFORE any boot work; missing
@@ -570,14 +577,7 @@ export type ProdAppHandle = {
   readonly stop: () => Promise<void>;
 };
 
-// Mint `ctx.config` per request: the dispatcher only builds a per-user
-// ConfigAccessor when `_configAccessorFactory` is on the AppContext
-// (pipeline/dispatcher.ts). Without it `ctx.config` stays undefined and any
-// handler reading it — e.g. createFileProviderForTenant for the GDPR export
-// download — throws "ctx.config is missing". Built from the EFFECTIVE resolver
-// so an app-supplied configResolver override (its appOverrides) is the one
-// ctx.config reads. Shared with runDevApp (mergeConfigResolverDefault) for
-// dev/prod parity.
+// Shared with runDevApp (mergeConfigResolverDefault) for dev/prod parity.
 export function addConfigAccessorFactory<T extends { readonly configResolver?: ConfigResolver }>(
   resolved: T,
   registry: Registry,
@@ -957,6 +957,24 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     ? buildProdSessionAuth(db, resolveProdSessionsConfig(effectiveAuth?.sessions))
     : undefined;
 
+  // PAT opt-in: if the personal-access-tokens feature is mounted, wire its
+  // resolver (bearer PATs → SessionUser, before jwt.verify). Scopes come from
+  // the feature's exports — the same declaration its handlers use.
+  const patFeature = features.find((f) => f.name === PAT_FEATURE);
+  let patAuthFragment:
+    | {
+        patResolver: ReturnType<typeof createPatResolver>;
+        patRateLimiter: ReturnType<typeof createInMemoryLoginRateLimiter>;
+      }
+    | undefined;
+  if (effectiveAuth && patFeature) {
+    const rl = patRateLimitFromFeature(patFeature);
+    patAuthFragment = {
+      patResolver: createPatResolver({ db, scopes: patScopesFromFeature(patFeature) }),
+      patRateLimiter: createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs),
+    };
+  }
+
   const baseEntrypointOptions = {
     registry,
     context: {
@@ -994,6 +1012,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
         ...sessionAuthFragment,
+        ...patAuthFragment,
         ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,