@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/user/__tests__/seed-testing.integration.ts

@@ -0,0 +1,127 @@
+// Tests für seedUser. Vier Invarianten:
+//   1. Projection-Row landet mit email/displayName/passwordHash
+//   2. Event `user.created` landet auf dem Aggregate-Stream
+//   3. Idempotenz über `email` — zweiter Call liefert dieselbe userId
+//      ohne neuen Insert/Event
+//   4. `passwordHash`-Field ist optional (User ohne Passwort, z.B. SSO-
+//      Federation, soll auch funktionieren)
+
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEntityTable,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createConfigFeature } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createUserFeature } from "../feature";
+import { userEntity, userTable } from "../schema/user";
+import { seedUser } from "../seeding";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const resolver = createConfigResolver();
+  stack = await setupTestStack({
+    features: [createConfigFeature(), createUserFeature()],
+    extraContext: { configResolver: resolver },
+  });
+  await createEntityTable(stack.db, userEntity);
+  await pushTables(stack.db, { configValuesTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.db.delete(userTable);
+  await stack.db.delete(eventsTable);
+});
+
+describe("seedUser", () => {
+  test("schreibt Projection-Row mit email/displayName/passwordHash", async () => {
+    const userId = await seedUser(stack.db, {
+      email: "alice@example.com",
+      displayName: "Alice",
+      passwordHash: "$argon2id$test-hash",
+    });
+    expect(userId).toMatch(/^[0-9a-f-]{36}$/);
+
+    const rows = await stack.db
+      .select()
+      .from(userTable)
+      .where(eq(userTable["email"], "alice@example.com"));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["email"]).toBe("alice@example.com");
+    expect(rows[0]?.["displayName"]).toBe("Alice");
+    expect(rows[0]?.["passwordHash"]).toBe("$argon2id$test-hash");
+  });
+
+  test("emittiert user.created-Event auf den Aggregate-Stream", async () => {
+    const userId = await seedUser(stack.db, {
+      email: "bob@example.com",
+      displayName: "Bob",
+    });
+    const events = await stack.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.aggregateType, "user"));
+    const created = events.filter((e) => e.type === "user.created");
+    expect(created).toHaveLength(1);
+    expect(created[0]?.aggregateId).toBe(userId);
+    const payload = created[0]?.payload as { email: string; displayName: string };
+    expect(payload.email).toBe("bob@example.com");
+    expect(payload.displayName).toBe("Bob");
+  });
+
+  test("idempotent über email — zweiter Call liefert dieselbe userId, kein zweites Event", async () => {
+    const first = await seedUser(stack.db, {
+      email: "carol@example.com",
+      displayName: "Carol",
+    });
+    const second = await seedUser(stack.db, {
+      email: "carol@example.com",
+      displayName: "Carol Updated",
+    });
+    expect(second).toBe(first);
+
+    const rows = await stack.db
+      .select()
+      .from(userTable)
+      .where(eq(userTable["email"], "carol@example.com"));
+    expect(rows).toHaveLength(1);
+    // Original-displayName bleibt — zweiter Call wurde geskippt, kein update.
+    expect(rows[0]?.["displayName"]).toBe("Carol");
+
+    const created = await stack.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.aggregateType, "user"));
+    expect(created.filter((e) => e.type === "user.created")).toHaveLength(1);
+  });
+
+  test("passwordHash optional — User ohne Hash anlegbar (z.B. SSO-Federation)", async () => {
+    const userId = await seedUser(stack.db, {
+      email: "dave@example.com",
+      displayName: "Dave",
+    });
+    const [row] = await stack.db.select().from(userTable).where(eq(userTable["id"], userId));
+    expect(row?.["passwordHash"]).toBeNull();
+  });
+
+  test("default `by` ist TestUsers.systemAdmin (für audit-trail)", async () => {
+    const userId = await seedUser(stack.db, {
+      email: "eve@example.com",
+      displayName: "Eve",
+    });
+    const [row] = await stack.db.select().from(userTable).where(eq(userTable["id"], userId));
+    expect(row?.["insertedById"]).toBe(TestUsers.systemAdmin.id);
+  });
+});

package/src/user/__tests__/user.integration.ts

@@ -0,0 +1,198 @@
+import {
+  createEntityTable,
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { UserErrors, UserHandlers, UserQueries } from "../constants";
+import { createUserFeature } from "../feature";
+import { userEntity, userTable } from "../schema/user";
+
+let stack: TestStack;
+
+const systemAdmin = TestUsers.systemAdmin;
+const userFeature = createUserFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [userFeature] });
+  await createEntityTable(stack.db, userEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.db.delete(userTable);
+});
+
+// Helper: create a user as SystemAdmin and return its id.
+async function seedUser(overrides: {
+  email: string;
+  displayName: string;
+  passwordHash?: string;
+}): Promise<{ id: number }> {
+  const res = await stack.http.writeOk<{ id: number }>(
+    UserHandlers.create,
+    {
+      passwordHash: "seeded-hash",
+      ...overrides,
+    },
+    systemAdmin,
+  );
+  return { id: res.id };
+}
+
+// --- Scenario 1: SystemAdmin creates user, me query returns correct data ---
+
+describe("scenario 1: create + me", () => {
+  test("SystemAdmin creates a user, user sees their own profile via me", async () => {
+    const created = await seedUser({
+      email: "marc@example.com",
+      displayName: "Marc",
+      passwordHash: "secret-hash",
+    });
+
+    const signedIn = createTestUser({ id: created.id, roles: ["User"] });
+    const me = await stack.http.queryOk<Record<string, unknown>>(UserQueries.me, {}, signedIn);
+
+    expect(me).toMatchObject({
+      id: created.id,
+      email: "marc@example.com",
+      displayName: "Marc",
+      locale: "de", // comes from the entity's default — client didn't send it
+    });
+  });
+
+  test("normal user cannot create another user", async () => {
+    const normal = createTestUser({ id: 42, roles: ["User"] });
+    const error = await stack.http.writeErr(
+      UserHandlers.create,
+      { email: "evil@example.com", displayName: "Evil" },
+      normal,
+    );
+    expectErrorIncludes(error, "access_denied");
+  });
+
+  test("duplicate email is rejected", async () => {
+    await seedUser({ email: "dup@example.com", displayName: "First" });
+    const error = await stack.http.writeErr(
+      UserHandlers.create,
+      { email: "dup@example.com", displayName: "Second" },
+      systemAdmin,
+    );
+    expectErrorIncludes(error, UserErrors.emailAlreadyExists);
+  });
+});
+
+// --- Scenario 2: field-level read access hides passwordHash ---
+
+describe("scenario 2: field-level read access", () => {
+  test("user profile does not expose passwordHash via me", async () => {
+    const created = await seedUser({
+      email: "secret@example.com",
+      displayName: "Secret",
+      passwordHash: "must-stay-hidden",
+    });
+
+    const signedIn = createTestUser({ id: created.id, roles: ["User"] });
+    const me = await stack.http.queryOk<Record<string, unknown>>(UserQueries.me, {}, signedIn);
+
+    expect(me).not.toHaveProperty("passwordHash");
+    // Sanity: the value is actually stored, just hidden from this role
+    const [row] = await stack.db.select().from(userTable);
+    expect((row as { passwordHash: string }).passwordHash).toBe("must-stay-hidden");
+  });
+});
+
+// --- Scenario 3: user edits own profile, email/passwordHash are system-locked ---
+
+describe("scenario 3: self-update + field-level write access", () => {
+  test("user can change their own displayName + locale", async () => {
+    const created = await seedUser({ email: "editor@example.com", displayName: "Before" });
+    const signedIn = createTestUser({ id: created.id, roles: ["User"] });
+
+    await stack.http.writeOk(
+      UserHandlers.update,
+      { id: created.id, changes: { displayName: "After", locale: "en" }, version: 1 },
+      signedIn,
+    );
+
+    const me = await stack.http.queryOk<Record<string, unknown>>(UserQueries.me, {}, signedIn);
+    expect(me).toMatchObject({ displayName: "After", locale: "en" });
+  });
+
+  test("user cannot change their own email (field-level write-locked to system)", async () => {
+    const created = await seedUser({ email: "locked@example.com", displayName: "Locked" });
+    const signedIn = createTestUser({ id: created.id, roles: ["User"] });
+
+    const error = await stack.http.writeErr(
+      UserHandlers.update,
+      { id: created.id, changes: { email: "changed@example.com" }, version: 1 },
+      signedIn,
+    );
+    expectErrorIncludes(error, "field_access_denied");
+
+    // Email is unchanged in the DB
+    const [row] = await stack.db.select().from(userTable);
+    expect((row as { email: string }).email).toBe("locked@example.com");
+  });
+
+  test("user cannot update someone else's profile", async () => {
+    const victim = await seedUser({ email: "victim@example.com", displayName: "Victim" });
+    const attacker = createTestUser({ id: victim.id + 1000, roles: ["User"] });
+
+    const error = await stack.http.writeErr(
+      UserHandlers.update,
+      { id: victim.id, changes: { displayName: "Pwned" }, version: 1 },
+      attacker,
+    );
+    expectErrorIncludes(error, UserErrors.cannotEditOtherUser);
+  });
+});
+
+// --- Scenario 4: detail + list are SystemAdmin-only ---
+
+describe("scenario 4: detail + list access", () => {
+  test("SystemAdmin can fetch any user via detail", async () => {
+    const target = await seedUser({ email: "target@example.com", displayName: "Target" });
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      UserQueries.detail,
+      { id: target.id },
+      systemAdmin,
+    );
+
+    expect(detail).toMatchObject({ id: target.id, email: "target@example.com" });
+  });
+
+  test("tenant Admin cannot fetch arbitrary users (role leak guard)", async () => {
+    const target = await seedUser({ email: "other@example.com", displayName: "Other" });
+    const tenantAdmin = createTestUser({ id: 9999, roles: ["Admin"] });
+
+    const res = await stack.http.query(UserQueries.detail, { id: target.id }, tenantAdmin);
+    expect(res.status).toBe(403);
+  });
+
+  test("list returns users (SystemAdmin only)", async () => {
+    await seedUser({ email: "a@example.com", displayName: "A" });
+    await seedUser({ email: "b@example.com", displayName: "B" });
+
+    const result = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      UserQueries.list,
+      {},
+      systemAdmin,
+    );
+
+    expect(result.rows.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("normal user cannot list", async () => {
+    const signedIn = createTestUser({ id: 2000, roles: ["User"] });
+    const res = await stack.http.query(UserQueries.list, {}, signedIn);
+    expect(res.status).toBe(403);
+  });
+});

package/src/user/command-schemas.ts

@@ -0,0 +1,15 @@
+// Command-input schemas for the user write handlers, re-exposed for external
+// consumers — primarily migration mappers that need to write events directly
+// into the core `user` stream via `eventStore.appendRaw` (Marten-bypass) and
+// must validate their payloads against the exact handler contract.
+//
+// See `tenant/command-schemas.ts` for the same pattern + the schema-vs-event-
+// payload caveat (strip-id, defaults, sensitive, compound-type flattening).
+
+import { createWrite } from "./handlers/create.write";
+import { updateWrite } from "./handlers/update.write";
+
+export const UserCommandSchemas = {
+  create: createWrite.schema,
+  update: updateWrite.schema,
+} as const;

package/src/user/constants.ts

@@ -0,0 +1,23 @@
+// Feature name
+export const USER_FEATURE = "user" as const;
+
+// Qualified write handler names. Handlers carry the "user:" entity prefix so
+// field-level access rules (passwordHash system-only etc.) are wired up.
+export const UserHandlers = {
+  create: "user:write:user:create",
+  update: "user:write:user:update",
+} as const;
+
+// Qualified query handler names
+export const UserQueries = {
+  me: "user:query:user:me",
+  detail: "user:query:user:detail",
+  list: "user:query:user:list",
+  findForAuth: "user:query:user:find-for-auth",
+} as const;
+
+// Error codes
+export const UserErrors = {
+  emailAlreadyExists: "email_already_exists",
+  cannotEditOtherUser: "cannot_edit_other_user",
+} as const;

package/src/user/feature.ts

@@ -0,0 +1,32 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createWrite } from "./handlers/create.write";
+import { detailQuery } from "./handlers/detail.query";
+import { findForAuthQuery } from "./handlers/find-for-auth.query";
+import { listQuery } from "./handlers/list.query";
+import { meQuery } from "./handlers/me.query";
+import { updateWrite } from "./handlers/update.write";
+import { userEntity } from "./schema/user";
+
+// The user feature holds the cross-tenant user identity. `systemScope()` means
+// queries and writes bypass the tenant filter — a user exists above any tenant.
+// Membership + tenant-specific roles live in the tenant feature.
+export function createUserFeature(): FeatureDefinition {
+  return defineFeature("user", (r) => {
+    r.systemScope();
+    r.entity("user", userEntity);
+
+    const handlers = {
+      create: r.writeHandler(createWrite),
+      update: r.writeHandler(updateWrite),
+    };
+
+    const queries = {
+      me: r.queryHandler(meQuery),
+      detail: r.queryHandler(detailQuery),
+      list: r.queryHandler(listQuery),
+      findForAuth: r.queryHandler(findForAuthQuery),
+    };
+
+    return { handlers, queries };
+  });
+}

package/src/user/handlers/create.write.ts

@@ -0,0 +1,54 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { UserErrors } from "../constants";
+import { userEntity, userTable } from "../schema/user";
+
+const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+
+// Only the Auth features (running as SYSTEM) or a SystemAdmin may create users.
+//
+// Email uniqueness is checked via a pre-flight query — the framework has no
+// `unique:` field flag yet. This check is race-prone: two concurrent requests
+// can both see "no duplicate" and both insert. Acceptable MVP behavior since
+// user creation is low-frequency and gated by privileged roles; the DB will
+// still surface a pg unique violation once we add the constraint.
+// TODO: replace with a real `unique:` field flag + DB constraint.
+export const createWrite = defineWriteHandler({
+  name: "user:create",
+  schema: z.object({
+    email: z.email(),
+    passwordHash: z.string().optional(),
+    displayName: z.string().min(1).max(100),
+    locale: z.string().min(2).max(10).optional(),
+    // Globale Rollen — JSON-encoded string[]. Optional weil der Default
+    // im Entity-Schema "[]" ist; setzen wenn man einen SystemAdmin (oder
+    // andere globale Rollen) anlegt. Field-Access (write: privileged) auf
+    // der Entity ist die letzte Hand: wer auch immer create dispatcht ist
+    // schon privileged (system/SystemAdmin), aber das Field-Guard läuft
+    // trotzdem als defense-in-depth.
+    roles: z.string().optional(),
+  }),
+  access: { roles: ["system", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const existing = await ctx.db
+      .select({ id: userTable["id"] })
+      .from(userTable)
+      .where(eq(userTable["email"], event.payload.email))
+      .limit(1);
+
+    if (existing.length > 0) {
+      return writeFailure(
+        new ConflictError({
+          message: "email already exists",
+          i18nKey: "user.errors.emailAlreadyExists",
+          details: { reason: UserErrors.emailAlreadyExists, field: "email" },
+        }),
+      );
+    }
+
+    return crud.create(event.payload, event.user, ctx.db);
+  },
+});

package/src/user/handlers/detail.query.ts

@@ -0,0 +1,9 @@
+import { access, defineEntityDetailHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { userEntity } from "../schema/user";
+
+// Only SystemAdmins can read arbitrary users. Tenant-level "Admin" does NOT
+// grant this — the user feature is tenant-agnostic, and an Admin's scope is
+// bound to their own tenant's memberships (served by the tenant feature).
+export const detailQuery = defineEntityDetailHandler("user", userEntity, {
+  access: { roles: access.systemAdmin },
+});

package/src/user/handlers/find-for-auth.query.ts

@@ -0,0 +1,38 @@
+import type { DbRow } from "@cosmicdrift/kumiko-framework/db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { userTable } from "../schema/user";
+
+// Privileged auth lookup: returns the full user row — including passwordHash —
+// by email OR id (exactly one, enforced by the schema). Used by the auth
+// features via ctx.queryAs(systemUser, ...).
+//
+// Field-level read rules allow passwordHash for the "privileged" role set,
+// so system callers see everything; any other caller is filtered even if
+// they somehow reach this handler. Access is also restricted to privileged
+// — regular users or tenant admins cannot call this at all.
+export const findForAuthQuery = defineQueryHandler({
+  name: "user:find-for-auth",
+  schema: z
+    .object({
+      email: z.email().optional(),
+      id: z.uuid().optional(),
+    })
+    .refine(
+      // XOR: exactly one must be set. Neither or both is a caller bug, not an
+      // ambiguous lookup.
+      (v) => (v.email !== undefined) !== (v.id !== undefined),
+      { message: "exactly one of email or id must be set" },
+    ),
+  access: { roles: access.privileged },
+  handler: async (query, ctx) => {
+    const condition =
+      query.payload.email !== undefined
+        ? eq(userTable["email"], query.payload.email)
+        : eq(userTable["id"], query.payload.id as string);
+
+    const [row] = await ctx.db.select().from(userTable).where(condition).limit(1);
+    return (row as DbRow) ?? null;
+  },
+});

package/src/user/handlers/list.query.ts

@@ -0,0 +1,8 @@
+import { access, defineEntityListHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { userEntity } from "../schema/user";
+
+// System-wide user listing is SystemAdmin-only. Tenant admins list their
+// members via the tenant feature (which scopes by membership, not globally).
+export const listQuery = defineEntityListHandler("user", userEntity, {
+  access: { roles: access.systemAdmin },
+});

package/src/user/handlers/me.query.ts

@@ -0,0 +1,15 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { userEntity, userTable } from "../schema/user";
+
+const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+
+// Returns the currently signed-in user's profile. Field-level read access
+// strips out the passwordHash automatically (configured on the entity).
+export const meQuery = defineQueryHandler({
+  name: "user:me",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => crud.detail({ id: query.user.id }, query.user, ctx.db),
+});

package/src/user/handlers/update.write.ts

@@ -0,0 +1,54 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { access, defineWriteHandler, hasAccess } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { UserErrors } from "../constants";
+import { userEntity, userTable } from "../schema/user";
+
+const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+
+// Users can update their OWN profile; SystemAdmin/system can update anyone.
+// Handler-level access is openToAll — the row guard below is the actual gate,
+// and field-level access (passwordHash/email write-locked to "privileged")
+// stops any write that shouldn't touch an identity column.
+export const updateWrite = defineWriteHandler({
+  name: "user:update",
+  schema: z.object({
+    id: z.uuid(),
+    // Clients must send the version they read. The CrudExecutor rejects
+    // missing versions with version_conflict — see optimistic-locking in
+    // crud-executor.ts.
+    version: z.number(),
+    changes: z.object({
+      displayName: z.string().min(1).max(100).optional(),
+      locale: z.string().min(2).max(10).optional(),
+      email: z.email().optional(),
+      passwordHash: z.string().optional(),
+      lastActiveTenantId: z.string().optional(),
+      emailVerified: z.boolean().optional(),
+      // Globale Rollen — JSON-encoded string[]. Field-level write-access
+      // ist privileged (siehe userEntity.roles), d.h. ein non-privileged
+      // Caller sieht hier zwar einen 200, aber das Field-Guard im
+      // executor blockt die Spalte vorm Schreiben (silent strip). Schema
+      // akzeptiert das field damit der SystemAdmin-Pfad explizit
+      // existiert; der Privilege-Escalation-Schutz greift im
+      // FieldAccessFilter, nicht im Schema.
+      roles: z.string().optional(),
+    }),
+  }),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const isSelf = event.payload.id === event.user.id;
+    const isPrivileged = hasAccess(event.user, { roles: access.privileged });
+    if (!isSelf && !isPrivileged) {
+      return writeFailure(
+        new AccessDeniedError({
+          message: "cannot edit other user",
+          i18nKey: "user.errors.cannotEditOtherUser",
+          details: { reason: UserErrors.cannotEditOtherUser, targetUserId: event.payload.id },
+        }),
+      );
+    }
+    return crud.update(event.payload, event.user, ctx.db);
+  },
+});

package/src/user/index.ts

@@ -0,0 +1,4 @@
+export { UserCommandSchemas } from "./command-schemas";
+export { USER_FEATURE, UserErrors, UserHandlers, UserQueries } from "./constants";
+export { createUserFeature } from "./feature";
+export { userEntity, userTable } from "./schema/user";

package/src/user/schema/index.ts

@@ -0,0 +1,5 @@
+// Re-exports aus den schema/<entity>.ts Files. Eine Datei pro Entity
+// — wenn das Feature später weitere Entities hinzubekommt, kommen sie
+// als zusätzliche Datei rein und werden hier exportiert.
+
+export * from "./user";

package/src/user/schema/user.ts

@@ -0,0 +1,69 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createBooleanField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// User entity — tenant-agnostic. A single user can belong to multiple tenants
+// via tenantMemberships. No tenantId column on this table.
+export const userEntity = createEntity({
+  table: "read_users",
+  softDelete: true,
+  fields: {
+    // Identity — anyone who can see the user can read the email, but only
+    // privileged roles (SYSTEM auth code, SystemAdmin) may change it.
+    email: createTextField({
+      required: true,
+      format: "email",
+      maxLength: 320,
+      access: { write: access.privileged },
+    }),
+
+    // Password material: only SYSTEM/SystemAdmin can read or write it.
+    // auth-email-password reads it during login, writes it during registration
+    // and password changes. Stripped from ordinary responses via read-access.
+    passwordHash: createTextField({
+      maxLength: 255,
+      access: { read: access.privileged, write: access.privileged },
+    }),
+
+    // Profile — user-editable
+    displayName: createTextField({ required: true, maxLength: 100, searchable: true }),
+    locale: createTextField({ maxLength: 10, default: "de" }),
+
+    // Which tenant should this user land in on next login. Set by the login
+    // handler (SYSTEM), read by the login flow + UI for deep-linking.
+    // UUID string matching tenants.id; createTextField stores it as text.
+    lastActiveTenantId: createTextField({
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+
+    // Email-verification flag — flipped to true by the verify-email handler
+    // after an HMAC-signed token roundtrip. Readable by anyone who can see
+    // the user row; writable only by privileged (system) callers so a user
+    // can't self-mark themselves verified. Login can be config-gated to
+    // refuse a session while this is false (strict mode).
+    emailVerified: createBooleanField({
+      default: false,
+      access: { write: access.privileged },
+    }),
+
+    // Globale Rollen — parallel zu tenantMemberships.roles. JSON-encoded
+    // string[]; parseRoles() deserialisiert beim Read. Login-Handler mergt
+    // diese Rollen mit den tenant-membership-roles in die Session — so
+    // sind sie tenant-unabhängig (z.B. SystemAdmin, BillingAdmin). Default
+    // "[]" damit die Session-Roles-Merge keinen NULL-Branch braucht.
+    // Schreibrecht privileged: ein User darf sich nicht selbst zum
+    // SystemAdmin machen.
+    roles: createTextField({
+      required: true,
+      default: "[]",
+      access: { write: access.privileged },
+    }),
+  },
+});
+
+export const userTable = buildDrizzleTable("user", userEntity);