@cosmicdrift/kumiko-framework 0.102.2 → 0.105.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.102.2",
+  "version": "0.105.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.102.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.105.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-routes.ts

@@ -299,33 +299,17 @@ export type AuthRoutesConfig = {
 
 export type PasswordResetConfig = {
   // Qualified name of the request handler (the one that emits either
-  // { kind: "reset-requested", ... } or { kind: "no-op" }).
+  // { kind: "reset-requested", ... } or { kind: "no-op" }). The handler
+  // builds the magic-link and sends the mail via delivery (ctx.notify) — the
+  // route only dispatches and returns the silent-success envelope.
   requestHandler: string;
   // Qualified name of the confirm handler (token + newPassword → set).
   confirmHandler: string;
-  // Invoked only when the request handler returns kind=reset-requested.
-  // Given the signed token + target email, the callback builds the URL
-  // into the caller's app and hands it to whatever delivery channel the
-  // app wires up. Errors bubble as 5xx so silent drop-on-send can't hide
-  // an outgoing-mail outage behind a green response.
-  sendResetEmail: (args: { email: string; resetUrl: string; expiresAt: string }) => Promise<void>;
-  // Base URL of the app that hosts the reset form. The route appends
-  // `?token=…` so you should NOT include a trailing `?` or `#`. Example:
-  //   "https://app.example.com/reset-password"
-  appResetUrl: string;
 };
 
 export type EmailVerificationConfig = {
   requestHandler: string;
   confirmHandler: string;
-  sendVerificationEmail: (args: {
-    email: string;
-    verificationUrl: string;
-    expiresAt: string;
-  }) => Promise<void>;
-  // URL of the app page that receives the `?token=…` parameter and POSTs
-  // it to /auth/verify-email on submit.
-  appVerifyUrl: string;
 };
 
 // Tenant-Invite Magic-Link. Drei Accept-Branches für klare Separation:
@@ -334,28 +318,20 @@ export type EmailVerificationConfig = {
 //   - signupCompleteHandler: anon User mit neuer email (Branch 3)
 // Branch 2+3 minten JWT analog signup-confirm.
 export type InviteConfig = {
-  // Qualified handler names
+  // Qualified handler names. invite-create dispatches the invite mail itself
+  // via delivery (ctx.notify); the route layer only wires the accept branches.
   readonly acceptHandler: string;
   readonly acceptWithLoginHandler: string;
   readonly signupCompleteHandler: string;
-  // Mail-Callback. Token-URL wird von der App-Page (z.B. /invite/accept)
-  // an den User geschickt; der Frontend leitet je nach User-State (eingeloggt
-  // / anon mit existing-email / anon mit neuer email) auf den passenden
-  // Branch-Endpoint.
-  readonly sendInviteEmail: (args: {
-    email: string;
-    inviteUrl: string;
-    expiresAt: string;
-    role: string;
-  }) => Promise<void>;
-  readonly appAcceptUrl: string;
 };
 
 // Magic-Link Self-Signup. Anders als reset/verify NICHT HMAC-signed —
-// der Token ist opaque random, Redis ist Source of Truth. Confirm
-// returnt `{ kind: "auth-session", session, tenantKey }` analog zu
-// loginHandler, sodass die Route JWT minten + Cookies setzen kann
-// (Auto-Login direkt nach Activation, kein zweiter login-Roundtrip).
+// der Token ist opaque random, Redis ist Source of Truth. The request
+// handler dispatches the activation mail via delivery (ctx.notify); the
+// route only forwards the dispatch. Confirm returnt
+// `{ kind: "auth-session", session, tenantKey }` analog zu loginHandler,
+// sodass die Route JWT minten + Cookies setzen kann (Auto-Login direkt
+// nach Activation, kein zweiter login-Roundtrip).
 export type SignupConfig = {
   // Qualified name of the request handler (typisch
   // AuthHandlers.signupRequest).
@@ -364,16 +340,6 @@ export type SignupConfig = {
   // AuthHandlers.signupConfirm). Returnt SessionUser-Shape — die
   // Route wickelt das wie einen erfolgreichen login.
   confirmHandler: string;
-  // Mail-Callback. Token-URL wird als `${appActivationUrl}?token=…`
-  // an die App-Page geleitet.
-  sendActivationEmail: (args: {
-    email: string;
-    activationUrl: string;
-    expiresAt: string;
-  }) => Promise<void>;
-  // Base URL of the app page that receives the `?token=…` parameter
-  // (typisch /signup/complete). KEIN trailing `?` oder `#`.
-  appActivationUrl: string;
 };
 
 // Extract `ip` and `user-agent` for the sessionCreator.
@@ -560,10 +526,6 @@ export function createAuthRoutes(
       dispatcher,
       path: Routes.authRequestPasswordReset,
       requestHandler: pr.requestHandler,
-      successKind: "reset-requested",
-      appBaseUrl: pr.appResetUrl,
-      sendEmail: ({ email, url, expiresAt }) =>
-        pr.sendResetEmail({ email, resetUrl: url, expiresAt }), // @wrapper-known semantic-alias
     });
     registerTokenConfirmRoute({
       api,
@@ -582,10 +544,6 @@ export function createAuthRoutes(
       dispatcher,
       path: Routes.authRequestEmailVerification,
       requestHandler: ev.requestHandler,
-      successKind: "verification-requested",
-      appBaseUrl: ev.appVerifyUrl,
-      sendEmail: ({ email, url, expiresAt }) =>
-        ev.sendVerificationEmail({ email, verificationUrl: url, expiresAt }), // @wrapper-known semantic-alias
     });
     registerTokenConfirmRoute({
       api,
@@ -607,10 +565,6 @@ export function createAuthRoutes(
       dispatcher,
       path: Routes.authSignupRequest,
       requestHandler: sg.requestHandler,
-      successKind: "signup-requested",
-      appBaseUrl: sg.appActivationUrl,
-      sendEmail: ({ email, url, expiresAt }) =>
-        sg.sendActivationEmail({ email, activationUrl: url, expiresAt }), // @wrapper-known semantic-alias
     });
 
     api.post(Routes.authSignupConfirm, async (c) => {
@@ -955,37 +909,19 @@ export function createAuthRoutes(
 }
 
 // --- shared route builders for token flows ---------------------------------
-// Password-reset and email-verification share the exact same HTTP-shape:
-// request-route emits a token → optional sendEmail callback → silent-success,
-// confirm-route validates token + does the state change → typed failure or
-// 200. Before this extraction both flows carried ~45 LOC of nearly-identical
-// body-parse / dispatch / url-build / response plumbing. The helpers keep
-// the public-facing silent-success invariant in one place — changing how
-// the framework handles "invalid_body" on a public token endpoint is now
-// one edit, not two.
-
-type TokenRequestData = {
-  kind: string;
-  email: string;
-  token: string;
-  expiresAt: string;
-};
-
-type TokenNoOp = { kind: "no-op" };
+// Password-reset, email-verification and signup share the exact same request
+// HTTP-shape: parse body → dispatch the request handler → always-200 (no
+// enumeration). The handler mints the token AND dispatches the magic-link mail
+// via delivery (ctx.notify); the route never sees the token. confirm-route
+// validates the token + does the state change → typed failure or 200. Keeping
+// the silent-success invariant in one place means changing how the framework
+// handles "invalid_body" on a public token endpoint is one edit, not three.
 
 function registerTokenRequestRoute(opts: {
   api: Hono;
   dispatcher: Dispatcher;
   path: string;
   requestHandler: string;
-  // Discriminator the feature handler emits when it actually minted a token
-  // (vs. the silent no-op for unknown/already-handled users).
-  successKind: string;
-  // Base URL of the receiving app page. `?token=…` is appended with proper
-  // separator handling so the caller's URL may or may not carry existing
-  // query params.
-  appBaseUrl: string;
-  sendEmail: (args: { email: string; url: string; expiresAt: string }) => Promise<void>;
 }): void {
   const body = RequestTokenBody;
   opts.api.post(opts.path, async (c) => {
@@ -995,30 +931,11 @@ function registerTokenRequestRoute(opts: {
     // anything from the shape of their input.
     if (!parsed.success) return c.json({ isSuccess: true });
 
-    const result = await opts.dispatcher.write(
-      opts.requestHandler,
-      { email: parsed.data.email },
-      GUEST_USER,
-    );
-
+    // The handler dispatches the magic-link mail via delivery before returning.
     // Handler-level failures (only legitimate reason: misconfiguration) are
-    // silently swallowed — observability logs capture them for ops.
-    if (result.isSuccess) {
-      // @cast-boundary engine-payload — generic dispatcher.write result narrowed by handler-emitted kind
-      const data = result.data as TokenRequestData | TokenNoOp;
-      if (data.kind === opts.successKind) {
-        // TS narrowt nicht durch generic successKind (string, kein literal) —
-        // die kind-Gleichheit garantiert den TokenRequestData-Branch hier.
-        const requested = data as TokenRequestData; // @cast-boundary engine-payload
-        const sep = opts.appBaseUrl.includes("?") ? "&" : "?";
-        const url = `${opts.appBaseUrl}${sep}token=${encodeURIComponent(requested.token)}`;
-        await opts.sendEmail({
-          email: requested.email,
-          url,
-          expiresAt: requested.expiresAt,
-        });
-      }
-    }
+    // silently swallowed — observability logs capture them for ops — so the
+    // response shape stays uniform for unknown vs. known emails.
+    await opts.dispatcher.write(opts.requestHandler, { email: parsed.data.email }, GUEST_USER);
 
     return c.json({ isSuccess: true });
   });

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

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { createEncryptionProvider } from "../encryption";
+import {
+  collectEncryptedFieldNames,
+  decryptEntityFieldValues,
+  encryptEntityFieldValues,
+} from "../entity-field-encryption";
+
+const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
+
+describe("entity-field-encryption", () => {
+  const entity = createEntity({
+    table: "read_enc_test",
+    fields: {
+      email: createTextField({ required: true }),
+      secretNote: createTextField({ encrypted: true }),
+    },
+  });
+  const encryptedFields = collectEncryptedFieldNames(entity);
+  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", () => {
+    const plain = { email: "a@b.de", secretNote: "top secret" };
+    const stored = encryptEntityFieldValues(plain, encryptedFields, encryption);
+    expect(stored["email"]).toBe(plain.email);
+    expect(stored["secretNote"]).not.toBe("top secret");
+
+    const read = decryptEntityFieldValues(stored, encryptedFields, encryption);
+    expect(read).toEqual(plain);
+  });
+
+  test("onlyKeys limits encryption to changed fields", () => {
+    const row = { email: "a@b.de", secretNote: "note" };
+    const stored = encryptEntityFieldValues(row, encryptedFields, encryption, {
+      onlyKeys: ["secretNote"],
+    });
+    expect(stored["email"]).toBe("a@b.de");
+    expect(stored["secretNote"]).not.toBe("note");
+  });
+});

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

@@ -10,6 +10,8 @@ import {
   testTenantId,
   unsafeCreateEntityTable,
 } from "../../stack";
+import { createEncryptionProvider } from "../encryption";
+import { resetEntityFieldEncryptionCacheForTests } from "../entity-field-encryption";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb, type TenantDb } from "../tenant-db";
@@ -301,6 +303,77 @@ describe("event-store-executor — detail liefert die Stream-Version", () => {
   });
 });
 
+const ENCRYPTION_TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
+const encryptedEntity = createEntity({
+  table: "read_es_exec_encrypted",
+  fields: {
+    email: createTextField({ required: true }),
+    secretNote: createTextField({ encrypted: true }),
+  },
+});
+const encryptedTable = buildEntityTable("esExecEncrypted", encryptedEntity);
+
+describe("event-store-executor — encrypted fields", () => {
+  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
+  const crud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
+    entityName: "esExecEncrypted",
+    encryption,
+  });
+
+  beforeAll(async () => {
+    process.env["ENCRYPTION_KEY"] = ENCRYPTION_TEST_KEY;
+    resetEntityFieldEncryptionCacheForTests();
+    await unsafeCreateEntityTable(testDb.db, encryptedEntity, "esExecEncrypted");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_exec_encrypted RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("stores ciphertext in DB and returns plaintext on read", async () => {
+    const plaintext = "super-secret-note";
+    const result = await crud.create(
+      { email: "enc@test.de", secretNote: plaintext },
+      adminUser,
+      tdb,
+    );
+    if (!result.isSuccess) throw new Error("create failed");
+    expect(result.data.data["secretNote"]).toBe(plaintext);
+
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT secret_note FROM read_es_exec_encrypted WHERE email = 'enc@test.de' LIMIT 1`,
+    )) as Array<{ secret_note: string }>;
+    expect(rawRows[0]?.secret_note).toBeDefined();
+    expect(rawRows[0]!.secret_note).not.toBe(plaintext);
+
+    const detail = await crud.detail({ id: result.data.id }, adminUser, tdb);
+    expect(detail?.["secretNote"]).toBe(plaintext);
+  });
+
+  test("update encrypts changed encrypted field", async () => {
+    const created = await crud.create(
+      { email: "upd-enc@test.de", secretNote: "old-note" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const updated = await crud.update(
+      {
+        id: created.data.id,
+        version: 1,
+        changes: { secretNote: "new-note" },
+      },
+      adminUser,
+      tdb,
+    );
+    if (!updated.isSuccess) throw new Error("update failed");
+    expect(updated.data.data["secretNote"]).toBe("new-note");
+  });
+});
+
 describe("event-store-executor — entity cache read-through", () => {
   // In-memory stand-in for EntityCache — no Redis needed.
   const store = new Map<string, Record<string, unknown>>();

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

@@ -0,0 +1,81 @@
+import type { EntityDefinition } from "../engine/types";
+import type { EncryptionProvider } from "./encryption";
+import { createEncryptionProvider } from "./encryption";
+
+export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const [name, field] of Object.entries(entity.fields)) {
+    if ((field.type === "text" || field.type === "longText") && field.encrypted === true) {
+      names.add(name);
+    }
+  }
+  return names;
+}
+
+function encryptFieldValue(
+  fieldName: string,
+  value: unknown,
+  encryption: EncryptionProvider,
+): string {
+  if (value === null || value === undefined) {
+    throw new Error(`encrypted field "${fieldName}" cannot be null or undefined`);
+  }
+  if (typeof value !== "string") {
+    throw new Error(`encrypted field "${fieldName}" must be a string, got ${typeof value}`);
+  }
+  return encryption.encrypt(value);
+}
+
+export function encryptEntityFieldValues(
+  row: Record<string, unknown>,
+  encryptedFields: ReadonlySet<string>,
+  encryption: EncryptionProvider,
+  opts?: { onlyKeys?: Iterable<string> },
+): Record<string, unknown> {
+  if (encryptedFields.size === 0) return row;
+  const only = opts?.onlyKeys ? new Set(opts.onlyKeys) : null;
+  const out = { ...row };
+  for (const name of encryptedFields) {
+    if (only && !only.has(name)) continue;
+    if (!(name in out)) continue;
+    const value = out[name];
+    if (value === null || value === undefined) continue;
+    out[name] = encryptFieldValue(name, value, encryption);
+  }
+  return out;
+}
+
+export function decryptEntityFieldValues(
+  row: Record<string, unknown>,
+  encryptedFields: ReadonlySet<string>,
+  encryption: EncryptionProvider,
+): Record<string, unknown> {
+  if (encryptedFields.size === 0) return row;
+  const out = { ...row };
+  for (const name of encryptedFields) {
+    const value = out[name];
+    if (value === null || value === undefined) continue;
+    if (typeof value !== "string") continue;
+    out[name] = encryption.decrypt(value);
+  }
+  return out;
+}
+
+let cachedProvider: EncryptionProvider | undefined;
+
+export function resolveEntityFieldEncryption(): EncryptionProvider {
+  if (cachedProvider) return cachedProvider;
+  const key = process.env["ENCRYPTION_KEY"];
+  if (!key) {
+    throw new Error(
+      "ENCRYPTION_KEY environment variable is required (encrypted entity fields in use)",
+    );
+  }
+  cachedProvider = createEncryptionProvider(key);
+  return cachedProvider;
+}
+
+/** @internal test-only */
+export function resetEntityFieldEncryptionCacheForTests(): void {
+  cachedProvider = undefined;
+}

package/src/db/event-store-executor.ts

@@ -45,6 +45,13 @@ import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 import type { DbRow } from "./connection";
 import { decodeCursor, encodeCursor } from "./cursor";
 import type { TableColumns } from "./dialect";
+import type { EncryptionProvider } from "./encryption";
+import {
+  collectEncryptedFieldNames,
+  decryptEntityFieldValues,
+  encryptEntityFieldValues,
+  resolveEntityFieldEncryption,
+} from "./entity-field-encryption";
 import type { CursorResult } from "./index";
 import { constraintOf, isUniqueViolation } from "./pg-error";
 import { toSnakeCase } from "./table-builder";
@@ -112,6 +119,8 @@ export type EventStoreExecutorOptions = {
   searchAdapter?: SearchAdapter;
   entityName: string; // required — the aggregateType marker on every event
   entityCache?: EntityCache;
+  /** Override ENCRYPTION_KEY for entity fields marked `encrypted: true`. */
+  encryption?: EncryptionProvider;
 };
 
 // F8 helper: PG-23505 (unique-violation) catched aus applyEntityEvent
@@ -285,6 +294,29 @@ export function createEventStoreExecutor(
     }
   }
 
+  const encryptedFields = collectEncryptedFieldNames(entity);
+  const hasEncryptedFields = encryptedFields.size > 0;
+
+  function encryptionProvider(): EncryptionProvider {
+    if (options.encryption) return options.encryption;
+    return resolveEntityFieldEncryption();
+  }
+
+  function encryptForStorage(
+    row: Record<string, unknown>,
+    onlyKeys?: Iterable<string>,
+  ): Record<string, unknown> {
+    if (!hasEncryptedFields) return row;
+    return encryptEntityFieldValues(row, encryptedFields, encryptionProvider(), {
+      ...(onlyKeys !== undefined && { onlyKeys }),
+    });
+  }
+
+  function decryptForRead(row: Record<string, unknown>): Record<string, unknown> {
+    if (!hasEncryptedFields) return row;
+    return decryptEntityFieldValues(row, encryptedFields, encryptionProvider());
+  }
+
   function applyDefaults(payload: Record<string, unknown>): Record<string, unknown> {
     if (Object.keys(fieldDefaults).length === 0) return payload;
     const result: Record<string, unknown> = { ...payload };
@@ -314,7 +346,7 @@ export function createEventStoreExecutor(
   async function loadById(id: EntityId, db: TenantDb): Promise<Record<string, unknown> | null> {
     const row = await db.fetchOne(table, idFilter(id));
     if (!row) return null;
-    return rehydrateCompoundTypes(row as DbRow, entity);
+    return decryptForRead(rehydrateCompoundTypes(row as DbRow, entity));
   }
 
   // Archive guard for the CRUD write paths. Archived streams are read-only —
@@ -423,7 +455,7 @@ export function createEventStoreExecutor(
       // Alle Compound-Types (locatedTimestamp, money, ...) gehen durch
       // dieselbe Pipeline. Caller schickt combined API-Form, Framework
       // speichert flat DB-Form. Siehe db/compound-types.ts.
-      const flatData = flattenCompoundTypes(data, entity);
+      const flatData = encryptForStorage(flattenCompoundTypes(data, entity));
 
       // 1. Append event (same TX as the projection write — both must succeed
       //    or both roll back; the dispatcher wraps both in one transaction).
@@ -499,7 +531,7 @@ export function createEventStoreExecutor(
       const row = result.row;
       // Read-Side Auto-Convert: DB-Form → API-combined-Form für alle
       // Compound-Types in einem Pass.
-      const projection = rehydrateCompoundTypes(row as DbRow, entity) as DbRow;
+      const projection = decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
 
       if (entityCache && entityName) {
         await entityCache.del(user.tenantId, entityName, aggregateId);
@@ -602,7 +634,10 @@ export function createEventStoreExecutor(
 
       try {
         // Compound-Types Auto-Convert (alle in einem Pass).
-        const flatChanges = flattenCompoundTypes(payload.changes, entity);
+        const flatChanges = encryptForStorage(
+          flattenCompoundTypes(payload.changes, entity),
+          Object.keys(payload.changes),
+        );
 
         // The event payload carries BOTH `changes` (what the user asked for) AND
         // `previous` (the pre-update row). Cross-aggregate projections need the
@@ -647,7 +682,7 @@ export function createEventStoreExecutor(
           return writeFailure(new InternalError({ message: "projection update returned no row" }));
         }
         const row = result.row;
-        const data = rehydrateCompoundTypes(row as DbRow, entity) as DbRow;
+        const data = decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
 
         if (entityCache && entityName) {
           await entityCache.del(user.tenantId, entityName, payload.id);
@@ -967,7 +1002,9 @@ export function createEventStoreExecutor(
       const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
       // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen
       const tableInfo = extractTableInfo(table);
-      const rows = rawRows.map((r) => coerceRow(rehydrateCompoundTypes(r, entity), tableInfo));
+      const rows = rawRows.map((r) =>
+        coerceRow(decryptForRead(rehydrateCompoundTypes(r, entity)), tableInfo),
+      );
 
       // list rows carry the READ-ROW version (display-only), never an optimistic-lock
       // base — edit flows reload via detail(), which reconciles the stream version.
@@ -1043,7 +1080,7 @@ export function createEventStoreExecutor(
       const rows = await loadWithOwnership(db, idWhere, ownership);
       const raw = rows[0];
       if (!raw) return null;
-      const row = rehydrateCompoundTypes(raw, entity);
+      const row = decryptForRead(rehydrateCompoundTypes(raw, entity));
       const rowInfo = extractTableInfo(table);
       const coerced = coerceRow(row, rowInfo);
 

package/src/db/index.ts

@@ -36,6 +36,11 @@ export {
 } from "./eagerload";
 export type { EncryptionProvider } from "./encryption";
 export { createEncryptionProvider } from "./encryption";
+export {
+  collectEncryptedFieldNames,
+  decryptEntityFieldValues,
+  encryptEntityFieldValues,
+} from "./entity-field-encryption";
 export type {
   BuildEntityTableMetaOptions,
   ColumnMeta,

package/src/engine/__tests__/boot-validator-i18n-keys.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+describe("validateBoot — i18n surface keys", () => {
+  test("passes when screen-derived keys are in r.translations", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-list",
+        type: "entityList",
+        entity: "item",
+        columns: ["name"],
+      });
+      r.translations({
+        keys: {
+          "screen:item-list.title": { de: "Liste", en: "List" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("throws when screen title key is missing", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-list",
+        type: "entityList",
+        entity: "item",
+        columns: ["name"],
+      });
+      r.translations({
+        keys: {
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /required translation key missing: "screen:item-list.title"/,
+    );
+  });
+
+  test("skips features with no r.translations", () => {
+    const feature = defineFeature("legacy", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-list",
+        type: "entityList",
+        entity: "item",
+        columns: ["name"],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("throws when de/en locale is missing", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.nav({ id: "home", label: "demo:nav.home" });
+      r.translations({
+        keys: {
+          "demo:nav.home": { de: "Start", en: "" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/missing locale\(s\): en/);
+  });
+});

package/src/engine/__tests__/boot-validator.test.ts

@@ -1983,6 +1983,39 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- Tier 2.7e: rowAction rowClick (Row-Body-Klick) ---
+  describe("entityList rowAction rowClick", () => {
+    function makeFeature(rowClickCount: number) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({ id: "product-editor", type: "custom", renderer: { react: "stub" } });
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: Array.from({ length: rowClickCount }, (_, i) => ({
+            kind: "navigate" as const,
+            id: `open-${i}`,
+            label: "actions.edit",
+            screen: "product-editor",
+            rowClick: true,
+          })),
+        });
+      });
+    }
+
+    test("one rowClick navigate action passes boot", () => {
+      expect(() => validateBoot([makeFeature(1)])).not.toThrow();
+    });
+
+    test("more than one rowClick action per list is rejected", () => {
+      expect(() => validateBoot([makeFeature(2)])).toThrow(
+        /at most one may fire on a row-body click/i,
+      );
+    });
+  });
+
   // --- rowAction kind="writeHandler" handler-QN-Validierung (Tier 2.7e-1 erw.) ---
   describe("entityList rowAction kind=writeHandler handler-QN", () => {
     function makeFeature(handlerQn: string, register: boolean) {

package/src/engine/__tests__/build-app-schema.test.ts

@@ -205,6 +205,7 @@ describe("buildAppSchema", () => {
             id: "open",
             label: "Öffnen",
             screen: "detail",
+            rowClick: true,
             visible: { field: "status", ne: "archived" },
           },
           {
@@ -244,7 +245,11 @@ describe("buildAppSchema", () => {
     });
 
     // Explizit: FieldCondition-Varianten (eq, ne, boolean) landen unverändert an
-    const actions = screen?.rowActions as Array<{ id: string; visible?: unknown }>;
+    const actions = screen?.rowActions as Array<{
+      id: string;
+      visible?: unknown;
+      rowClick?: unknown;
+    }>;
     expect(actions?.find((a) => a.id === "open")?.visible).toEqual({
       field: "status",
       ne: "archived",
@@ -254,6 +259,9 @@ describe("buildAppSchema", () => {
       eq: "open",
     });
     expect(actions?.find((a) => a.id === "always")?.visible).toBe(true);
+
+    // rowClick (skalares Flag) überlebt die JSON-Projektion — nicht gedroppt.
+    expect(actions?.find((a) => a.id === "open")?.rowClick).toBe(true);
   });
 
   test("derivedFields werden ins Client-Schema projiziert (valueType, ohne derive-fn)", () => {

package/src/engine/__tests__/required-surface-keys.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ACTION_FORM_ENTITY,
+  fieldLabelKey,
+  requiredKeysFromScreen,
+  screenTitleKey,
+} from "../../i18n/required-surface-keys";
+import type { EntityListScreenDefinition } from "../types";
+
+describe("requiredKeysFromScreen", () => {
+  test("entityList emits screen title + column field labels", () => {
+    const screen: EntityListScreenDefinition = {
+      id: "component-list",
+      type: "entityList",
+      entity: "component",
+      columns: ["name", { field: "status" }],
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain(screenTitleKey("component-list"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "name"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "status"));
+  });
+
+  test("actionForm uses ACTION_FORM_ENTITY namespace", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-open-form",
+      type: "actionForm",
+      handler: "publicstatus:write:incident:open",
+      fields: {
+        title: { type: "text" },
+      },
+      layout: {
+        sections: [{ fields: ["title"] }],
+      },
+    });
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "title"));
+  });
+});

package/src/engine/boot-validator/i18n-keys.ts

@@ -0,0 +1,30 @@
+import {
+  buildEffectiveTranslationKeys,
+  findTranslationLocaleGaps,
+  requiredKeysFromFeature,
+} from "../../i18n/required-surface-keys";
+import type { FeatureDefinition } from "../types";
+
+export function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void {
+  const defined = buildEffectiveTranslationKeys(features);
+
+  for (const feature of features) {
+    // ponytail: features without r.translations are legacy — once they register
+    // keys, surface + locale checks apply (apps, new bundled work).
+    if (Object.keys(feature.translations ?? {}).length === 0) continue;
+
+    for (const key of requiredKeysFromFeature(feature)) {
+      if (!defined.has(key)) {
+        throw new Error(
+          `[i18n] Feature "${feature.name}": required translation key missing: "${key}"`,
+        );
+      }
+    }
+  }
+
+  for (const gap of findTranslationLocaleGaps(features)) {
+    throw new Error(
+      `[i18n] Feature "${gap.featureName}": key "${gap.key}" missing locale(s): ${gap.missingLocales.join(", ")}`,
+    );
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -26,6 +26,7 @@ import {
   validateTransitions,
 } from "./entity-handler";
 import { validateGdprHookCompleteness, validateGdprStoragePersistence } from "./gdpr-storage";
+import { validateI18nSurfaceKeys } from "./i18n-keys";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
 import {
@@ -160,6 +161,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   validateNavCycles(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
+  validateI18nSurfaceKeys(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);

package/src/engine/boot-validator/screens-nav.ts

@@ -465,6 +465,15 @@ export function validateScreens(
             rowMeta,
           );
         }
+        const rowClickActions = screen.rowActions.filter(
+          (a) => a.kind === "navigate" && a.rowClick === true,
+        );
+        if (rowClickActions.length > 1) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityList) has ${rowClickActions.length} ` +
+              "rowActions marked rowClick:true — at most one may fire on a row-body click.",
+          );
+        }
       }
       // Tier 2.7e-2: toolbarActions — analog zu rowActions, aber bisher
       // ohne Validator. Typo'd navigate-targets und unregistrierte

package/src/engine/types/screen.ts

@@ -219,6 +219,11 @@ export type RowActionNavigate = {
   /** Conditional Visibility pro Row. */
   readonly visible?: FieldCondition;
   readonly style?: "primary" | "secondary";
+  /** Wenn true, löst ein Klick auf die ganze Zeile (nicht nur das Aktionsmenü)
+   *  diese navigate-Action aus. Max. eine pro Liste (Boot-Validator prüft). Nur
+   *  auf navigate — ein Row-Klick darf keinen (evtl. destruktiven, unbestätigten)
+   *  Write auslösen, daher nicht auf writeHandler-Actions. */
+  readonly rowClick?: boolean;
 };
 
 // ToolbarAction — Button im List-Header. Zwei Varianten: navigate auf

package/src/i18n/required-surface-keys.ts

@@ -0,0 +1,214 @@
+import type {
+  ActionFormScreenDefinition,
+  ConfigEditScreenDefinition,
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+  FeatureDefinition,
+  NavDefinition,
+  RowAction,
+  ScreenDefinition,
+  ToolbarAction,
+  WorkspaceDefinition,
+} from "../engine/types";
+import { isExtensionEditSection, normalizeListColumn } from "../engine/types/screen";
+
+/** Pseudo-entity for actionForm field labels (renderer action-form-shim). */
+export const ACTION_FORM_ENTITY = "__action-form__";
+
+/** Pseudo-entity for configEdit field labels (renderer config-edit-shim). */
+export const CONFIG_EDIT_ENTITY = "__config-edit__";
+
+export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}`;
+}
+
+export function screenTitleKey(screenId: string): string {
+  return `screen:${screenId}.title`;
+}
+
+function isI18nKey(value: string): boolean {
+  return value.includes(":");
+}
+
+function pushKey(out: Set<string>, value: string | undefined): void {
+  if (value !== undefined && isI18nKey(value)) out.add(value);
+}
+
+function editFieldName(f: string | { readonly field: string }): string {
+  return typeof f === "string" ? f : f.field;
+}
+
+function pushRowActionKeys(out: Set<string>, action: RowAction): void {
+  pushKey(out, action.label);
+  if (action.kind === "writeHandler" || action.kind === undefined) {
+    pushKey(out, action.confirm);
+    pushKey(out, action.confirmLabel);
+  }
+}
+
+function pushToolbarActionKeys(out: Set<string>, action: ToolbarAction): void {
+  pushKey(out, action.label);
+  if (action.kind === "writeHandler") {
+    pushKey(out, action.confirm);
+    pushKey(out, action.confirmLabel);
+  }
+}
+
+export function requiredKeysFromScreen(
+  featureName: string,
+  screen: ScreenDefinition,
+): readonly string[] {
+  const out = new Set<string>();
+  pushKey(out, screenTitleKey(screen.id));
+
+  switch (screen.type) {
+    case "entityList": {
+      const list = screen as EntityListScreenDefinition;
+      for (const col of list.columns) {
+        const normalized = normalizeListColumn(col);
+        if (normalized.label !== undefined) {
+          pushKey(out, normalized.label);
+        } else {
+          out.add(fieldLabelKey(featureName, list.entity, normalized.field));
+        }
+      }
+      for (const action of list.rowActions ?? []) pushRowActionKeys(out, action);
+      for (const action of list.toolbarActions ?? []) pushToolbarActionKeys(out, action);
+      break;
+    }
+    case "entityEdit": {
+      const edit = screen as EntityEditScreenDefinition;
+      pushKey(out, edit.submitLabel);
+      for (const section of edit.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          pushKey(out, section.title);
+          continue;
+        }
+        pushKey(out, section.title);
+        for (const f of section.fields) {
+          const fieldName = editFieldName(f);
+          const override = edit.fieldLabels?.[fieldName];
+          if (override !== undefined) pushKey(out, override);
+          else out.add(fieldLabelKey(featureName, edit.entity, fieldName));
+        }
+      }
+      break;
+    }
+    case "actionForm": {
+      const form = screen as ActionFormScreenDefinition;
+      pushKey(out, form.submitLabel);
+      for (const fieldName of Object.keys(form.fields)) {
+        out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
+      }
+      for (const section of form.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          pushKey(out, section.title);
+          continue;
+        }
+        pushKey(out, section.title);
+        for (const f of section.fields) {
+          const fieldName = editFieldName(f);
+          out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
+        }
+      }
+      break;
+    }
+    case "configEdit": {
+      const config = screen as ConfigEditScreenDefinition;
+      pushKey(out, config.submitLabel);
+      for (const fieldName of Object.keys(config.fields)) {
+        const override = config.fieldLabels?.[fieldName];
+        if (override !== undefined) pushKey(out, override);
+        else out.add(fieldLabelKey(featureName, CONFIG_EDIT_ENTITY, fieldName));
+      }
+      for (const section of config.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          pushKey(out, section.title);
+          continue;
+        }
+        pushKey(out, section.title);
+        for (const f of section.fields) {
+          const fieldName = editFieldName(f);
+          const override = config.fieldLabels?.[fieldName];
+          if (override !== undefined) pushKey(out, override);
+          else out.add(fieldLabelKey(featureName, CONFIG_EDIT_ENTITY, fieldName));
+        }
+      }
+      break;
+    }
+    case "custom":
+      break;
+  }
+
+  return [...out];
+}
+
+export function requiredKeysFromNav(nav: NavDefinition): readonly string[] {
+  const out = new Set<string>();
+  pushKey(out, nav.label);
+  return [...out];
+}
+
+export function requiredKeysFromWorkspace(ws: WorkspaceDefinition): readonly string[] {
+  const out = new Set<string>();
+  pushKey(out, ws.label);
+  return [...out];
+}
+
+export function requiredKeysFromFeature(feature: FeatureDefinition): readonly string[] {
+  const out = new Set<string>();
+
+  for (const screen of Object.values(feature.screens)) {
+    for (const key of requiredKeysFromScreen(feature.name, screen)) out.add(key);
+  }
+  for (const nav of Object.values(feature.navs)) {
+    for (const key of requiredKeysFromNav(nav)) out.add(key);
+  }
+  for (const ws of Object.values(feature.workspaces)) {
+    for (const key of requiredKeysFromWorkspace(ws)) out.add(key);
+  }
+  for (const def of Object.values(feature.configKeys)) {
+    pushKey(out, def.mask?.title);
+  }
+
+  return [...out];
+}
+
+/** Effective lookup keys — mirrors registry merge (`feature:localKey` + raw full keys). */
+export function buildEffectiveTranslationKeys(features: readonly FeatureDefinition[]): Set<string> {
+  const out = new Set<string>();
+  for (const feature of features) {
+    for (const key of Object.keys(feature.translations ?? {})) {
+      out.add(`${feature.name}:${key}`);
+      if (key.includes(":")) out.add(key);
+    }
+  }
+  return out;
+}
+
+export type TranslationLocaleGap = {
+  readonly featureName: string;
+  readonly key: string;
+  readonly missingLocales: readonly string[];
+};
+
+const REQUIRED_LOCALES = ["de", "en"] as const;
+
+export function findTranslationLocaleGaps(
+  features: readonly FeatureDefinition[],
+): readonly TranslationLocaleGap[] {
+  const gaps: TranslationLocaleGap[] = [];
+  for (const feature of features) {
+    for (const [localKey, entry] of Object.entries(feature.translations ?? {})) {
+      const missing = REQUIRED_LOCALES.filter((locale) => (entry[locale] ?? "").length === 0);
+      if (missing.length > 0) {
+        gaps.push({
+          featureName: feature.name,
+          key: localKey,
+          missingLocales: missing,
+        });
+      }
+    }
+  }
+  return gaps;
+}