@cosmicdrift/kumiko-dev-server 0.155.0 → 0.156.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.155.0",
+  "version": "0.156.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Not shipped into production node_modules — see @cosmicdrift/kumiko-server-runtime for the prod boot path.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -54,9 +54,9 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.155.0",
-    "@cosmicdrift/kumiko-framework": "0.155.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.155.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.156.0",
+    "@cosmicdrift/kumiko-framework": "0.156.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.156.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/compose-stacks.test.ts

@@ -4,6 +4,7 @@ import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-feat
 import {
   composeFileStack,
   composeGdprStack,
+  composeIdentityStack,
   composeMailStack,
   composeOpsStack,
   composePagesStack,
@@ -12,6 +13,12 @@ import {
   stackFeatureNames,
 } from "../compose-stacks";
 
+const TEST_MFA = {
+  setupTokenSecret: "compose-stacks-mfa-setup-secret-at-least-32b!!",
+  challengeTokenSecret: "compose-stacks-mfa-challenge-secret-32b!!",
+  issuer: "Kumiko ComposeStacks",
+} as const;
+
 describe("composeStacks", () => {
   test("composeRendererStack → template-resolver, renderer-foundation, renderer-simple", () => {
     expect(stackFeatureNames(composeRendererStack())).toEqual([
@@ -77,6 +84,38 @@ describe("composeStacks", () => {
       "rate-limiting",
     ]);
   });
+
+  test("composeIdentityStack defaults sessions only", () => {
+    expect(stackFeatureNames(composeIdentityStack())).toEqual(["sessions"]);
+  });
+
+  test("composeIdentityStack mounts auth-mfa when mfa options given", () => {
+    expect(stackFeatureNames(composeIdentityStack({ mfa: TEST_MFA }))).toEqual([
+      "sessions",
+      "auth-mfa",
+    ]);
+  });
+
+  test("composeIdentityStack sessions:false + mfa → auth-mfa only", () => {
+    expect(stackFeatureNames(composeIdentityStack({ sessions: false, mfa: TEST_MFA }))).toEqual([
+      "auth-mfa",
+    ]);
+  });
+
+  test("composeIdentityStack + composeGdprStack(sessions) → duplicate feature rejected at boot", () => {
+    const names = stackFeatureNames([
+      ...composeIdentityStack(),
+      ...composeGdprStack({ sessions: true }),
+    ]);
+    expect(names.filter((n) => n === "sessions")).toHaveLength(2);
+    expect(() =>
+      validateBoot(
+        composeFeatures([...composeIdentityStack(), ...composeGdprStack({ sessions: true })], {
+          includeBundled: true,
+        }),
+      ),
+    ).toThrow(/duplicate feature/i);
+  });
 });
 
 /** Snapshot, not a live parity check: intended block combinations, mirrored by hand from studio/money-horse/publicstatus run-configs. A drifted run-config stays green here. */
@@ -95,6 +134,25 @@ describe("composeStacks boots for real", () => {
     );
     expect(() => validateBoot(features)).not.toThrow();
   });
+
+  // auth-mfa's encrypted fields need a runtime KEK (env or configureEntityFieldEncryption
+  // + secrets). Name-list + saas-identity-wire.integration.test.ts cover identity boot.
+  test("identity stack names compose with ops + renderer under includeBundled", () => {
+    const features = composeFeatures(
+      [
+        ...composeIdentityStack({ mfa: TEST_MFA }),
+        ...composeOpsStack(),
+        ...composeRendererStack(),
+        ...composeMailStack({ transports: ["inmemory"] }),
+      ],
+      { includeBundled: true },
+    );
+    const names = stackFeatureNames(features);
+    expect(names).toContain("auth-email-password");
+    expect(names).toContain("sessions");
+    expect(names).toContain("auth-mfa");
+    expect(names).toContain("delivery");
+  });
 });
 
 describe("composeStacks intended block names (snapshot, not live parity)", () => {
@@ -172,4 +230,10 @@ describe("composeStacks intended block names (snapshot, not live parity)", () =>
       expect(names).toContain(expected);
     }
   });
+
+  test("identity stack covers sessions + auth-mfa", () => {
+    const names = stackFeatureNames(composeIdentityStack({ mfa: TEST_MFA }));
+    expect(names).toContain("sessions");
+    expect(names).toContain("auth-mfa");
+  });
 });

package/src/__tests__/few-shot-corpus.test.ts

@@ -169,7 +169,7 @@ describe("buildFewShotCorpus — warnings", () => {
 
     expect(corpus.entries).toHaveLength(1);
     expect(corpus.warnings).toHaveLength(1);
-    expect(corpus.warnings[0]?.reason).toMatch(/^duplicate-id:/);
+    expect(corpus.warnings[0]?.message).toMatch(/^duplicate-id:/);
   });
 
   test("parser-throw surfaces as a warning instead of silent skip", () => {

package/src/__tests__/saas-identity-wire.integration.test.ts

@@ -0,0 +1,423 @@
+// Cross-feature SaaS identity wire suite — one mount that mirrors a real app
+// stack (composeIdentityStack + delivery + renderer + channel-email) and drives
+// the happy paths apps always need. Proves auth ↔ delivery mail ↔ sessions
+// (login jti + mine) ↔ MFA challenge/verify. Renderer stack is mounted for
+// delivery deps; channel-email uses an injected in-memory transport (not a
+// template-resolver round-trip). Edge cases stay in per-feature suites.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { AuthErrors, AuthHandlers } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import {
+  seedAdmin,
+  seedUserWithPassword,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import {
+  AuthMfaHandlers,
+  base32Decode,
+  bindMfaRevokeAllOtherSessionsFromFeature,
+  userMfaEntity,
+  userMfaTable,
+} from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { currentTotpCode } from "@cosmicdrift/kumiko-bundled-features/auth-mfa/testing";
+import {
+  createChannelEmailFeature,
+  createInMemoryTransport,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import {
+  configValuesTable,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { createDeliveryTestContext } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { notificationPreferencesTable } from "@cosmicdrift/kumiko-bundled-features/delivery/tables";
+import { simpleRenderer } from "@cosmicdrift/kumiko-bundled-features/renderer-simple";
+import {
+  createSessionCallbacks,
+  type SessionCallbacks,
+  SessionQueries,
+  userSessionEntity,
+  userSessionTable,
+} from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { sessionCallbacksFromLateBound } from "@cosmicdrift/kumiko-bundled-features/sessions/testing";
+import {
+  tenantEntity,
+  tenantInvitationEntity,
+  tenantInvitationsTable,
+  tenantMembershipsTable,
+  tenantTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
+import {
+  seedTenant,
+  seedTenantMembership,
+} from "@cosmicdrift/kumiko-bundled-features/tenant/seeding";
+import { userEntity, userTable } from "@cosmicdrift/kumiko-bundled-features/user";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createLateBoundHolder,
+  createTestEnvelopeCipher,
+  deleteRows,
+  updateRows,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
+import * as jose from "jose";
+import { composeIdentityStack, composeOpsStack, composeRendererStack } from "../compose-stacks";
+
+const SETUP_TOKEN_SECRET = "wire-mfa-setup-secret-at-least-32-bytes-long!!";
+const CHALLENGE_TOKEN_SECRET = "wire-mfa-challenge-secret-at-least-32-bytes!!";
+const RESET_SECRET = randomBytes(32).toString("base64");
+const VERIFY_SECRET = randomBytes(32).toString("base64");
+const APP_SIGNUP_URL = "https://app.example.com/signup/complete";
+const APP_RESET_URL = "https://app.example.com/reset";
+const APP_VERIFY_URL = "https://app.example.com/verify";
+const APP_INVITE_URL = "https://app.example.com/invite/accept";
+
+const emailTransport = createInMemoryTransport();
+const callbacks = createLateBoundHolder<SessionCallbacks>("session-callbacks");
+
+let stack: TestStack;
+
+function extractTokenFromMail(html: string): string {
+  const match = html.match(/[?&]token=([^&"'<\s]+)/);
+  if (!match?.[1]) throw new Error(`No token in mail html: ${html.slice(0, 200)}`);
+  return decodeURIComponent(match[1]);
+}
+
+async function markVerified(userId: string): Promise<void> {
+  await updateRows(stack.db, userTable, { emailVerified: true }, { id: userId });
+}
+
+beforeAll(async () => {
+  configureEntityFieldEncryption(createTestEnvelopeCipher());
+  const bound = sessionCallbacksFromLateBound(callbacks);
+
+  const identity = composeIdentityStack({
+    mfa: {
+      setupTokenSecret: SETUP_TOKEN_SECRET,
+      challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+      issuer: "Kumiko Wire",
+    },
+  });
+  const mfaFeature = identity.find((f) => f.name === "auth-mfa");
+  if (!mfaFeature) throw new Error("composeIdentityStack did not mount auth-mfa");
+
+  const features = composeFeatures(
+    [
+      ...identity,
+      ...composeOpsStack({ delivery: true, audit: false, jobs: false }),
+      ...composeRendererStack(),
+      createChannelEmailFeature({
+        transport: emailTransport,
+        renderer: simpleRenderer,
+        resolveEmail: async () => "unused@test.local",
+      }),
+    ],
+    {
+      includeBundled: true,
+      authOptions: {
+        signup: { tokenTtlMinutes: 60, appUrl: APP_SIGNUP_URL },
+        invite: { tokenTtlMinutes: 60, appUrl: APP_INVITE_URL },
+        passwordReset: {
+          hmacSecret: RESET_SECRET,
+          tokenTtlMinutes: 15,
+          appUrl: APP_RESET_URL,
+        },
+        emailVerification: {
+          hmacSecret: VERIFY_SECRET,
+          tokenTtlMinutes: 60,
+          mode: "strict",
+          appUrl: APP_VERIFY_URL,
+        },
+      },
+    },
+  );
+
+  stack = await setupTestStack({
+    features,
+    extraContext: (deps) => ({
+      ...createDeliveryTestContext(deps),
+      configResolver: createConfigResolver(),
+    }),
+    authConfig: {
+      ...bound.asAuthConfig(),
+      // No sessionStrictMode: seed/writeOk uses TestUsers JWTs without sid.
+      // Login still gets jti via sessionCreator (asserted below).
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      mfaVerifyHandler: AuthMfaHandlers.verify,
+      loginErrorStatusMap: {
+        [AuthErrors.invalidCredentials]: 401,
+        [AuthErrors.noMembership]: 403,
+        [AuthErrors.emailNotVerified]: 403,
+      },
+      signup: {
+        requestHandler: AuthHandlers.signupRequest,
+        confirmHandler: AuthHandlers.signupConfirm,
+      },
+      passwordReset: {
+        requestHandler: AuthHandlers.requestPasswordReset,
+        confirmHandler: AuthHandlers.resetPassword,
+      },
+      emailVerification: {
+        requestHandler: AuthHandlers.requestEmailVerification,
+        confirmHandler: AuthHandlers.verifyEmail,
+      },
+      invite: {
+        acceptHandler: AuthHandlers.inviteAccept,
+        acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
+        signupCompleteHandler: AuthHandlers.inviteSignupComplete,
+      },
+    },
+  });
+
+  const sessionCallbacks = createSessionCallbacks({ db: stack.db });
+  callbacks.set(sessionCallbacks);
+  bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(sessionCallbacks.sessionRevokeAllOthers);
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, tenantInvitationEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafeCreateEntityTable(stack.db, userSessionEntity);
+  await unsafePushTables(stack.db, {
+    configValuesTable,
+    tenantMembershipsTable,
+    notificationPreferencesTable,
+    userSessionTable,
+  });
+});
+
+afterAll(async () => {
+  await stack?.cleanup();
+  configureEntityFieldEncryption(undefined);
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantInvitationsTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantTable.tableName}"`);
+  await deleteRows(stack.db, userSessionTable, {});
+  await deleteRows(stack.db, userMfaTable, {});
+  emailTransport.sent.length = 0;
+  for (const pattern of ["signup:*", "invite:*"] as const) {
+    const keys = await stack.redis.redis.keys(pattern);
+    if (keys.length > 0) await stack.redis.redis.del(...keys);
+  }
+});
+
+describe("saas-identity-wire", () => {
+  test("signup → delivery mail → confirm → login JWT with sid", async () => {
+    const email = "signup-wire@example.com";
+    const password = "fresh-secure-pw-1234";
+
+    const req = await stack.http.raw("POST", "/api/auth/signup-request", { email });
+    expect(req.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const token = extractTokenFromMail(emailTransport.sent[0]?.html ?? "");
+
+    const confirm = await stack.http.raw("POST", "/api/auth/signup-confirm", { token, password });
+    expect(confirm.status).toBe(200);
+
+    const login = await stack.http.raw("POST", "/api/auth/login", { email, password });
+    expect(login.status).toBe(200);
+    const body = (await login.json()) as { token?: string };
+    expect(body.token).toBeTypeOf("string");
+    expect(typeof jose.decodeJwt(body.token!).jti).toBe("string");
+  });
+
+  test("password reset → delivery mail → reset → login with new password", async () => {
+    const email = "reset-wire@example.com";
+    const oldPassword = "old-password-1234";
+    const newPassword = "new-password-5678";
+    const tenantId = "00000000-0000-4000-8000-000000000001" as TenantId;
+    const { id } = await seedAdmin(stack.db, {
+      email,
+      password: oldPassword,
+      displayName: "Reset",
+      memberships: [
+        {
+          tenantId,
+          tenantKey: "reset-wire",
+          tenantName: "Reset Wire",
+          roles: ["User"],
+        },
+      ],
+    });
+    await markVerified(id);
+
+    const req = await stack.http.raw("POST", "/api/auth/request-password-reset", { email });
+    expect(req.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const token = extractTokenFromMail(emailTransport.sent[0]?.html ?? "");
+
+    const reset = await stack.http.raw("POST", "/api/auth/reset-password", {
+      token,
+      newPassword,
+    });
+    expect(reset.status).toBe(200);
+
+    const oldLogin = await stack.http.raw("POST", "/api/auth/login", {
+      email,
+      password: oldPassword,
+    });
+    expect(oldLogin.status).toBe(401);
+
+    const login = await stack.http.raw("POST", "/api/auth/login", { email, password: newPassword });
+    expect(login.status).toBe(200);
+    const body = (await login.json()) as { token?: string };
+    expect(body.token).toBeTypeOf("string");
+  });
+
+  test("invite Branch3 → signup-complete → login", async () => {
+    const tenantId = crypto.randomUUID() as TenantId;
+    const { id: adminId } = await seedAdmin(stack.db, {
+      email: "admin-wire@example.com",
+      password: "admin-password-1234",
+      displayName: "Admin",
+      memberships: [
+        {
+          tenantId,
+          tenantKey: `invite-${tenantId.slice(0, 8)}`,
+          tenantName: "Invite Wire",
+          roles: ["Admin"],
+        },
+      ],
+    });
+    await markVerified(adminId);
+
+    const admin: SessionUser = { id: adminId, tenantId, roles: ["Admin"] };
+    const invitee = "carol-wire@example.com";
+    await stack.http.writeOk(AuthHandlers.inviteCreate, { email: invitee, role: "User" }, admin);
+    expect(emailTransport.sent.length).toBeGreaterThanOrEqual(1);
+    const token = extractTokenFromMail(emailTransport.sent.at(-1)?.html ?? "");
+
+    const complete = await stack.http.raw("POST", "/api/auth/invite-signup-complete", {
+      token,
+      password: "carol-new-pw-1234",
+    });
+    expect(complete.status).toBe(200);
+
+    const login = await stack.http.raw("POST", "/api/auth/login", {
+      email: invitee,
+      password: "carol-new-pw-1234",
+    });
+    expect(login.status).toBe(200);
+  });
+
+  test("email verify gate: unverified blocked → verify → login ok", async () => {
+    const email = "verify-wire@example.com";
+    const password = "verify-password-1234";
+    const tenantId = "00000000-0000-4000-8000-000000000002" as TenantId;
+    await seedTenant(stack.db, {
+      id: tenantId,
+      key: "verify-wire",
+      name: "Verify Wire",
+    });
+    const { id } = await seedUserWithPassword(stack.db, {
+      email,
+      password,
+      displayName: "Verify",
+      emailVerified: false,
+    });
+    await seedTenantMembership(stack.db, {
+      userId: id,
+      tenantId,
+      roles: ["User"],
+    });
+
+    const blocked = await stack.http.raw("POST", "/api/auth/login", { email, password });
+    expect(blocked.status).toBe(403);
+    const blockedBody = (await blocked.json()) as { error?: { details?: { reason?: string } } };
+    expect(blockedBody.error?.details?.reason).toBe(AuthErrors.emailNotVerified);
+
+    const req = await stack.http.raw("POST", "/api/auth/request-email-verification", { email });
+    expect(req.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const token = extractTokenFromMail(emailTransport.sent[0]?.html ?? "");
+
+    const verify = await stack.http.raw("POST", "/api/auth/verify-email", { token });
+    expect(verify.status).toBe(200);
+
+    const login = await stack.http.raw("POST", "/api/auth/login", { email, password });
+    expect(login.status).toBe(200);
+  });
+
+  test("MFA enable → login challenges → verify JWT; sessions:mine lists sid", async () => {
+    const email = "mfa-wire@example.com";
+    const password = "mfa-password-1234";
+    const tenantId = "00000000-0000-4000-8000-000000000003" as TenantId;
+    const { id: userId } = await seedAdmin(stack.db, {
+      email,
+      password,
+      displayName: "Mfa",
+      memberships: [
+        {
+          tenantId,
+          tenantKey: "mfa-wire",
+          tenantName: "MFA Wire",
+          roles: ["User"],
+        },
+      ],
+    });
+    await markVerified(userId);
+    const user: SessionUser = { id: userId, tenantId, roles: ["User"] };
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: email },
+      user,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const secret = base32Decode(secretParam);
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(secret) },
+      user,
+    );
+
+    const login = await stack.http.raw("POST", "/api/auth/login", { email, password });
+    expect(login.status).toBe(200);
+    const challenge = (await login.json()) as {
+      mfaRequired?: boolean;
+      challengeToken?: string;
+      token?: string;
+    };
+    expect(challenge.mfaRequired).toBe(true);
+    expect(challenge.token).toBeUndefined();
+    expect(challenge.challengeToken).toBeTypeOf("string");
+
+    const verify = await stack.http.raw("POST", "/api/auth/mfa/verify", {
+      challengeToken: challenge.challengeToken,
+      code: currentTotpCode(secret),
+    });
+    expect(verify.status).toBe(200);
+    const { token } = (await verify.json()) as { token: string };
+    expect(token).toBeTypeOf("string");
+    const sid = jose.decodeJwt(token).jti;
+    expect(typeof sid).toBe("string");
+
+    const mineRes = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: SessionQueries.mine, payload: {} },
+      { Authorization: `Bearer ${token}` },
+    );
+    expect(mineRes.status).toBe(200);
+    const mineBody = (await mineRes.json()) as {
+      data?: Array<{ id: string }> | { items?: Array<{ id: string }> };
+    };
+    const items = Array.isArray(mineBody.data) ? mineBody.data : (mineBody.data?.items ?? []);
+    expect(items.some((s) => s.id === sid)).toBe(true);
+
+    const rows = await selectMany(stack.db, userSessionTable, { userId });
+    expect(rows.length).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/build-server-bundle.ts

@@ -38,6 +38,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { parseJsonOrThrow, parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 
 const hasBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
 
@@ -239,7 +240,7 @@ async function resolveRuntimeDepsVersions(
   for (const path of pinSources) {
     if (!existsSync(path)) continue;
     const raw = await readFile(path, "utf-8");
-    const parsed = JSON.parse(raw) as { dependencies?: Record<string, string> };
+    const parsed = parseJsonOrThrow<{ dependencies?: Record<string, string> }>(raw, path);
     Object.assign(allDeps, parsed.dependencies ?? {});
   }
   for (const pkg of packages) {
@@ -251,12 +252,17 @@ async function resolveRuntimeDepsVersions(
 function derivePkgName(cwd: string): string {
   const pkgJson = join(cwd, "package.json");
   if (!existsSync(pkgJson)) return "kumiko-app-runtime";
+  // existsSync/readFileSync race (deleted between the two calls) or a
+  // permission error must fall back like a missing file, not crash the
+  // build — read here too, not just the JSON.parse below.
+  let raw: string;
   try {
-    const parsed = JSON.parse(readFileSync(pkgJson, "utf-8")) as { name?: string };
-    return parsed.name ? `${parsed.name}-runtime` : "kumiko-app-runtime";
+    raw = readFileSync(pkgJson, "utf-8");
   } catch {
     return "kumiko-app-runtime";
   }
+  const parsed = parseJsonSafe<{ name?: string }>(raw, {});
+  return parsed.name ? `${parsed.name}-runtime` : "kumiko-app-runtime";
 }
 
 export function formatServerBuildResult(

package/src/codegen/__tests__/run-codegen.test.ts

@@ -283,7 +283,7 @@ export default defineFeature("dup", (r) => {
     const result = runCodegen({ appRoot });
     expect(result.eventCount).toBe(1);
     expect(result.warnings.length).toBeGreaterThanOrEqual(1);
-    const w = result.warnings.find((w) => w.reason.includes("duplicate"));
+    const w = result.warnings.find((w) => w.message.includes("duplicate"));
     expect(w).toBeDefined();
   });
 
@@ -368,7 +368,7 @@ export default defineFeature("inline", (r) => {
     const result = runCodegen({ appRoot });
     expect(result.eventCount).toBe(0);
     expect(result.warnings.length).toBe(1);
-    expect(result.warnings[0]?.reason).toMatch(/not a named import nor an inline z\.\* call/);
+    expect(result.warnings[0]?.message).toMatch(/not a named import nor an inline z\.\* call/);
   });
 
   test("skips test files, node_modules, .kumiko, dist", () => {

package/src/codegen/__tests__/watch.test.ts

@@ -138,8 +138,7 @@ export default defineFeature("orders", (r) => {
     writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("nope", "evt"));
     const handle = watchAndRegenerate({ appRoot, onResult: () => {} });
     handle.close();
-    handle.close(); // must not throw
-    expect(true).toBe(true);
+    expect(() => handle.close()).not.toThrow();
   });
 
   test("non-ts file changes do not trigger codegen", async () => {

package/src/codegen/scan-events.ts

@@ -93,7 +93,7 @@ export type SchemaSource =
 export type ScanWarning = {
   readonly file: string;
   readonly line: number;
-  readonly reason: string;
+  readonly message: string;
 };
 
 export type ScanResult = {
@@ -152,7 +152,7 @@ function collectTsFiles(dir: string, out: string[]): void {
   try {
     entries = readdirSync(dir);
   } catch {
-    // Directory missing — fine, just no files to scan there.
+    // skip: directory unreadable, nothing to scan there
     return;
   }
   for (const entry of entries) {
@@ -224,8 +224,9 @@ function collectFromDefineEvent(
     warnings.push({
       file: filePath,
       line: call.getStartLineNumber(),
-      reason: "r.defineEvent: cannot read event-name + schema statically",
+      message: "r.defineEvent: cannot read event-name + schema statically",
     });
+    // skip: defineEvent call shape not statically parseable, already recorded as warning
     return;
   }
 
@@ -241,8 +242,9 @@ function collectFromDefineEvent(
     warnings.push({
       file: filePath,
       line: call.getStartLineNumber(),
-      reason: `r.defineEvent("${parsed.eventName}"): schema "${parsed.schemaNode.getText()}" — not a named import nor an inline z.* call, skipped`,
+      message: `r.defineEvent("${parsed.eventName}"): schema "${parsed.schemaNode.getText()}" — not a named import nor an inline z.* call, skipped`,
     });
+    // skip: schema source not resolvable, already recorded as warning
     return;
   }
 
@@ -544,7 +546,7 @@ function dedupe(events: ScannedEvent[], warnings: ScanWarning[]): ScannedEvent[]
       warnings.push({
         file: ev.source.file,
         line: ev.source.line,
-        reason: `duplicate r.defineEvent("${ev.qualifiedName}") — first declared at ${existing.source.file}:${existing.source.line}, ignored here`,
+        message: `duplicate r.defineEvent("${ev.qualifiedName}") — first declared at ${existing.source.file}:${existing.source.line}, ignored here`,
       });
       continue;
     }

package/src/codegen/watch.ts

@@ -74,7 +74,7 @@ export function watchAndRegenerate(opts: WatchOptions): WatchHandle {
         if (result.warnings.length > 0) {
           for (const w of result.warnings) {
             // biome-ignore lint/suspicious/noConsole: codegen-watcher logs to terminal
-            console.warn(`[codegen] ${w.file}:${w.line} — ${w.reason}`);
+            console.warn(`[codegen] ${w.file}:${w.line} — ${w.message}`);
           }
         }
       }
@@ -95,17 +95,19 @@ export function watchAndRegenerate(opts: WatchOptions): WatchHandle {
 
   try {
     watcher = watch(srcDir, { recursive: true }, (_eventType, filename) => {
+      // skip: watcher closed or no filename reported, nothing to act on
       if (closed || !filename) return;
       // node liefert filename relativ zu srcDir, kann aber posix oder
       // windows-style separators haben. Wir prüfen substring-tolerant.
       const normalised = `/${filename.toString().replace(/\\/g, "/")}`;
+      // skip: path matches an excluded segment (node_modules/dist/etc.)
       if (SKIP_SUBSTRINGS.some((seg) => normalised.includes(seg))) return;
-      // Nur .ts/.tsx interessieren — alles andere (CSS, MD, JSON) hat
+      // skip: Nur .ts/.tsx interessieren — alles andere (CSS, MD, JSON) hat
       // keinen Einfluss auf r.defineEvent-Calls.
       if (!normalised.endsWith(".ts") && !normalised.endsWith(".tsx")) return;
-      // .d.ts ausgenommen — die kommen meistens vom codegen selbst.
+      // skip: .d.ts ausgenommen — die kommen meistens vom codegen selbst.
       if (normalised.endsWith(".d.ts")) return;
-      // .test.ts/.test.tsx ausgenommen — Tests definieren keine
+      // skip: .test.ts/.test.tsx ausgenommen — Tests definieren keine
       // Production-Features.
       if (normalised.endsWith(".test.ts") || normalised.endsWith(".test.tsx")) return;
 
@@ -127,6 +129,7 @@ export function watchAndRegenerate(opts: WatchOptions): WatchHandle {
 
   return {
     close: () => {
+      // skip: already closed, avoid double-close
       if (closed) return;
       closed = true;
       if (timer) clearTimeout(timer);

package/src/compose-stacks.ts

@@ -3,6 +3,10 @@
 // or tier maps (those stay in bin/server.ts / app run-config).
 
 import { createAuditFeature } from "@cosmicdrift/kumiko-bundled-features/audit";
+import {
+  type AuthMfaFeatureOptions,
+  createAuthMfaFeature,
+} from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
 import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
 import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
@@ -61,10 +65,9 @@ export type UserDataRightsStackOptions = {
   readonly includeDefaults?: boolean;
 };
 
-// `sessions` lives ONLY on GdprStackOptions — composeOpsStack used to accept
-// it too, and combining both presets with sessions:true double-pushed the
-// "sessions" feature name into the registry, which createRegistry rejects
-// with "duplicate feature" (a boot-time crash, not a warning).
+// `sessions` may live on composeIdentityStack OR composeGdprStack — never both
+// with sessions:true. composeOpsStack used to accept it too; combining presets
+// that each push "sessions" crashes createRegistry with "duplicate feature".
 export type OpsStackOptions = {
   readonly delivery?: boolean;
   readonly audit?: boolean;
@@ -72,6 +75,13 @@ export type OpsStackOptions = {
   readonly rateLimiting?: boolean;
 };
 
+/** sessions (+ optional auth-mfa). config/user/tenant/auth-email-password stay
+ *  on composeFeatures(includeBundled). Pass `mfa` options to mount TOTP. */
+export type IdentityStackOptions = {
+  readonly sessions?: boolean;
+  readonly mfa?: AuthMfaFeatureOptions;
+};
+
 export function stackFeatureNames(features: readonly FeatureDefinition[]): string[] {
   return features.map((f) => f.name);
 }
@@ -146,3 +156,13 @@ export function composeOpsStack(options: OpsStackOptions = {}): FeatureDefinitio
   if (rateLimiting) out.push(createRateLimitingFeature());
   return out;
 }
+
+/** Identity opt-ins: sessions by default; auth-mfa when `mfa` options given.
+ *  Do not also pass `sessions: true` to composeGdprStack — duplicate feature. */
+export function composeIdentityStack(options: IdentityStackOptions = {}): FeatureDefinition[] {
+  const sessions = options.sessions ?? true;
+  const out: FeatureDefinition[] = [];
+  if (sessions) out.push(createSessionsFeature());
+  if (options.mfa !== undefined) out.push(createAuthMfaFeature(options.mfa));
+  return out;
+}

package/src/create-kumiko-server.ts

@@ -342,6 +342,7 @@ async function watchDir(
   } catch (err) {
     // signal.abort() wirft AbortError aus dem async-iterator; das ist
     // gewollt und kein Fehler. Andere Errors weiterreichen.
+    // skip: AbortSignal fired the abort, this is expected teardown not a real error
     if ((err as { name?: string }).name === "AbortError") return;
     throw err;
   }
@@ -954,6 +955,7 @@ export async function createKumikoServer(
         dir,
         async (filename) => {
           const action = classifyChange(filename);
+          // skip: file change classified as ignore (test/css/json), nothing to rebuild
           if (action === "ignore") return;
           if (action === "restart") {
             logInfo(

package/src/few-shot-corpus.ts

@@ -52,7 +52,7 @@ export type CorpusWarning = {
   /** Human-readable explanation. Currently only "parser-throw" but
    *  kept open-ended so future builders can add more (e.g.
    *  "duplicate-id", "no-feature-name"). */
-  readonly reason: string;
+  readonly message: string;
 };
 
 export type FewShotEntry = {
@@ -161,7 +161,7 @@ export function buildFewShotCorpus(options: BuildFewShotCorpusOptions): FewShotC
       // warning, drop the second occurrence.
       warnings.push({
         sourcePath: entry.sourcePath,
-        reason: `duplicate-id: collides with ${previousPath}`,
+        message: `duplicate-id: collides with ${previousPath}`,
       });
       continue;
     }
@@ -198,7 +198,7 @@ function buildEntry(filePath: string, repoRoot: string): BuildEntryResult {
     // hide newly broken feature-files until L2 hit them.
     const detail = err instanceof Error ? err.message : String(err);
     return {
-      warning: { sourcePath, reason: `parser-throw: ${detail}` },
+      warning: { sourcePath, message: `parser-throw: ${detail}` },
     };
   }
 
@@ -295,6 +295,7 @@ function walkDir(dir: string, acc: string[]): void {
   try {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch {
+    // skip: directory missing/unreadable, nothing to walk
     return;
   }
   for (const entry of entries) {

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 export {
   composeFileStack,
   composeGdprStack,
+  composeIdentityStack,
   composeMailStack,
   composeOpsStack,
   composePagesStack,
@@ -41,6 +42,7 @@ export {
   type FileStackOptions,
   type GdprStackOptions,
   type GdprStackOrder,
+  type IdentityStackOptions,
   type MailStackOptions,
   type MailTransportKind,
   type OpsStackOptions,

package/src/scaffold-app.ts

@@ -500,7 +500,7 @@ function renderMain(appName: string): string {
     [
       "// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after",
       "// composeFeatures + validateBoot + createRegistry without DB/Redis-connect",
-      "// (see @cosmicdrift/kumiko-dev-server runProdApp). The real dev boot",
+      "// (see @cosmicdrift/kumiko-server-runtime runProdApp). The real dev boot",
       "// runs via `bunx kumiko dev` (in-repo dev-tool) with a Docker stack — DX-1.0",
       "// only covers the boot-mode path; `kumiko dev` lands in a later DX phase.",
       "",

package/src/scaffold-demo-tasks.ts

@@ -35,6 +35,7 @@ const listScreen: EntityListScreenDefinition = {
   entity: "task",
   columns: ["title", "status", "isUrgent", "priority"],
   defaultSort: { field: "title", dir: "asc" },
+  rowActions: [{ kind: "navigate", id: "edit", label: "Edit", screen: "task-edit" }],
 };
 
 const editScreen: EntityEditScreenDefinition = {
@@ -48,9 +49,19 @@ const editScreen: EntityEditScreenDefinition = {
 
 const open = { access: { openToAll: true } } as const;
 
+const TASKS_I18N = {
+  "screen:task-list.title": { de: "Aufgaben", en: "Tasks" },
+  "screen:task-edit.title": { de: "Aufgabe", en: "Task" },
+  "tasks:entity:task:field:title": { de: "Titel", en: "Title" },
+  "tasks:entity:task:field:status": { de: "Status", en: "Status" },
+  "tasks:entity:task:field:priority": { de: "Priorität", en: "Priority" },
+  "tasks:entity:task:field:isUrgent": { de: "Dringend", en: "Urgent" },
+} as const;
+
 /** Canonical demo feature — keep in sync with `renderDemoTasksFeatureFile()`. */
 export function createDemoTasksFeature(): FeatureDefinition {
   return defineFeature("tasks", (r) => {
+    r.translations({ keys: TASKS_I18N });
     r.entity("task", taskEntity);
     r.writeHandler(defineEntityCreateHandler("task", taskEntity, open));
     r.writeHandler(defineEntityUpdateHandler("task", taskEntity, open));
@@ -106,6 +117,7 @@ const listScreen: EntityListScreenDefinition = {
   entity: "task",
   columns: ["title", "status", "isUrgent", "priority"],
   defaultSort: { field: "title", dir: "asc" },
+  rowActions: [{ kind: "navigate", id: "edit", label: "Edit", screen: "task-edit" }],
 };
 
 const editScreen: EntityEditScreenDefinition = {
@@ -119,7 +131,17 @@ const editScreen: EntityEditScreenDefinition = {
 
 const open = { access: { openToAll: true } } as const;
 
+const TASKS_I18N = {
+  "screen:task-list.title": { de: "Aufgaben", en: "Tasks" },
+  "screen:task-edit.title": { de: "Aufgabe", en: "Task" },
+  "tasks:entity:task:field:title": { de: "Titel", en: "Title" },
+  "tasks:entity:task:field:status": { de: "Status", en: "Status" },
+  "tasks:entity:task:field:priority": { de: "Priorität", en: "Priority" },
+  "tasks:entity:task:field:isUrgent": { de: "Dringend", en: "Urgent" },
+} as const;
+
 export const tasksFeature = defineFeature("tasks", (r) => {
+  r.translations({ keys: TASKS_I18N });
   r.entity("task", taskEntity);
   r.writeHandler(defineEntityCreateHandler("task", taskEntity, open));
   r.writeHandler(defineEntityUpdateHandler("task", taskEntity, open));

package/src/schema-apply.ts

@@ -114,6 +114,7 @@ async function rebuildAffectedProjections(
       );
     }
   }
+  // skip: no projections matched the changed tables, nothing to rebuild
   if (projections.size === 0) return;
 
   console.log(`  Rebuild ${projections.size} Projection(s)…`);