@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/auth-email-password/identity-v3-hash.ts

@@ -0,0 +1,97 @@
+// ASP.NET Core Identity V3 password-hash verifier.
+//
+// Why this lives in Kumiko: legacy migrations from .NET stacks (BMC: 22k
+// users with Identity-V3 passwordHash) need login to keep working without
+// forcing every user through a password-reset flow. New hashes are still
+// argon2 — Identity-V3 is verify-only.
+//
+// Format specification (from ASP.NET Core Identity source —
+// `Microsoft.AspNetCore.Identity.PasswordHasher`, `IdentityV3` mode):
+//
+//   Byte 0:        format marker (0x01 = V3)
+//   Bytes 1..4:    PRF as uint32 big-endian
+//                    1 = HMACSHA256
+//                    2 = HMACSHA512
+//                    (BMC uses 1; we accept both since the format does)
+//   Bytes 5..8:    iteration count as uint32 big-endian
+//   Bytes 9..12:   salt length in bytes as uint32 big-endian
+//   Bytes 13..:    salt + derived subkey, concatenated
+//
+//   The whole blob is base64-encoded. Typical BMC hash starts with
+//   "AQAAAAEAACcQ..." which decodes to:
+//     0x01 (V3) | 0x00000001 (HMACSHA256) | 0x00002710 (10000 iter) | …
+//
+// We never produce these — `hashPassword()` (argon2id) is the canonical
+// path. After a successful Identity-V3 login the application can re-hash
+// the password into argon2 on the next change-password event; that's
+// out-of-scope here.
+
+import { pbkdf2Sync, timingSafeEqual } from "node:crypto";
+
+const FORMAT_MARKER_V3 = 0x01;
+const HEADER_LENGTH = 13; // 1 (format) + 4 (PRF) + 4 (iter) + 4 (saltLen)
+
+const PRF_HMAC_SHA256 = 1;
+const PRF_HMAC_SHA512 = 2;
+
+// Quick sniff so the caller can route between argon2 and Identity-V3 without
+// throwing parse errors on every login. Only checks the format marker; the
+// full structural validation happens in `verifyIdentityV3Hash`.
+export function isIdentityV3Hash(hashB64: string): boolean {
+  const bytes = decodeBase64(hashB64);
+  if (bytes === null) return false;
+  return bytes.length >= HEADER_LENGTH && bytes[0] === FORMAT_MARKER_V3;
+}
+
+// Returns true on match. False on any mismatch — wrong password, malformed
+// hash, unsupported PRF, garbled length fields. Never throws (mirrors
+// `verifyPassword`'s contract — auth handlers don't want exceptions on
+// pathological stored data, just a clean "no").
+export function verifyIdentityV3Hash(password: string, hashB64: string): boolean {
+  const bytes = decodeBase64(hashB64);
+  if (bytes === null) return false;
+  if (bytes.length < HEADER_LENGTH) return false;
+  if (bytes[0] !== FORMAT_MARKER_V3) return false;
+
+  const prf = bytes.readUInt32BE(1);
+  const iterations = bytes.readUInt32BE(5);
+  const saltLength = bytes.readUInt32BE(9);
+
+  // Defensive: ASP.NET writes 16-byte salts, but the format technically
+  // allows any length. We accept what's encoded but bail if the blob is
+  // truncated mid-salt.
+  if (saltLength === 0) return false;
+  if (bytes.length <= HEADER_LENGTH + saltLength) return false; // need ≥1 subkey byte
+
+  const salt = bytes.subarray(HEADER_LENGTH, HEADER_LENGTH + saltLength);
+  const subkey = bytes.subarray(HEADER_LENGTH + saltLength);
+
+  const algorithm = prfToNodeAlgorithm(prf);
+  if (algorithm === null) return false;
+
+  let derived: Buffer;
+  try {
+    derived = pbkdf2Sync(password, salt, iterations, subkey.length, algorithm);
+  } catch {
+    return false;
+  }
+
+  if (derived.length !== subkey.length) return false;
+  return timingSafeEqual(derived, subkey);
+}
+
+function prfToNodeAlgorithm(prf: number): "sha256" | "sha512" | null {
+  if (prf === PRF_HMAC_SHA256) return "sha256";
+  if (prf === PRF_HMAC_SHA512) return "sha512";
+  return null;
+}
+
+function decodeBase64(b64: string): Buffer | null {
+  // Lenient decode: Buffer.from strips whitespace and ignores trailing garbage,
+  // which is what we want for hashes pulled out of CSV exports / legacy DBs
+  // that might carry stray CR/LF.
+  if (typeof b64 !== "string" || b64.length === 0) return null;
+  const buf = Buffer.from(b64, "base64");
+  if (buf.length === 0) return null;
+  return buf;
+}

package/src/auth-email-password/index.ts

@@ -0,0 +1,35 @@
+export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers } from "./constants";
+// Default-HTML-Renderer für die Reset-Password + Verify-Email Mails.
+// Apps wiren die `sendResetEmail` / `sendVerificationEmail` callbacks
+// im framework-config — diese Renderer können als one-liner genutzt
+// werden, oder die App schreibt einen eigenen Renderer für Branding.
+export type {
+  AuthMailLocale,
+  RenderActivationEmailArgs,
+  RenderedEmail,
+  RenderInviteEmailArgs,
+  RenderResetPasswordEmailArgs,
+  RenderVerifyEmailArgs,
+} from "./email-templates";
+export {
+  renderActivationEmail,
+  renderInviteEmail,
+  renderResetPasswordEmail,
+  renderVerifyEmail,
+} from "./email-templates";
+export type {
+  AccountLockoutOptions,
+  AuthEmailPasswordOptions,
+  EmailVerificationOptions,
+  InviteOptions,
+  PasswordResetOptions,
+  SignupOptions,
+} from "./feature";
+export { createAuthEmailPasswordFeature } from "./feature";
+export { hashPassword, verifyPassword } from "./password-hashing";
+// Generic HMAC-signed single-purpose token helpers. Re-exported damit
+// app-spezifische out-of-band-Flows (subscriber-confirm, magic-links,
+// invite-tokens) denselben battle-tested signer/verifier nutzen können
+// statt eigene HMAC-Logik zu duplizieren. Purpose-string diskriminiert
+// Cross-Replay zwischen Flows.
+export { signToken, TokenPurpose, type VerifyResult, verifyToken } from "./signed-token";

package/src/auth-email-password/invite-token-store.ts

@@ -0,0 +1,92 @@
+// Redis-backed Token-Store für Tenant-Invite-Magic-Link-Flow.
+//
+// Subject ist die Invitation-Row-ID (DB-row owner: tenant-feature). Wir
+// mappen Token → invitationId in Redis und nutzen den Token als opaque
+// random string aus generateToken (256 bit base64url, randomBytes).
+//
+// Anders als signup-token-store mappen wir hier NICHT bidirektional
+// — Resend-Idempotenz lebt auf der Invitation-Row-Ebene (Admin invitet
+// dieselbe email zweimal → existing row + token wird re-genutzt; das
+// invite-create-handler holt den existing token aus Redis via
+// invitationId-Lookup auf einem zweiten Key).
+//
+// Bidirektional ist trotzdem nützlich für Cancel: Admin cancelt → row.id
+// bekannt, ich brauche den token um Redis-Key zu löschen. Daher: zweiter
+// Key invite:by-id:<invitationId> → token. Cancel löscht beide.
+//
+// Bug-Pattern: TTL liegt nur in Redis. DB-row.expiresAt ist UI-Anzeige.
+// Bei expired-token: invite-accept findet den Token nicht → invalid-
+// invite-token. DB-row bleibt mit status="pending" — Cleanup-Job
+// markiert sie zu "expired" (separater Concern, kommt im U.3-Cleanup).
+//
+// Keine Kollision mit signup/reset/verify-Tokens: alle Invite-Keys haben
+// `invite:`-Prefix.
+
+import type Redis from "ioredis";
+
+const TOKEN_KEY_PREFIX = "invite:by-token:";
+const ID_KEY_PREFIX = "invite:by-id:";
+const BURN_KEY_PREFIX = "invite:burn:";
+
+function tokenKey(token: string): string {
+  return `${TOKEN_KEY_PREFIX}${token}`;
+}
+function idKey(invitationId: string): string {
+  return `${ID_KEY_PREFIX}${invitationId}`;
+}
+function burnKey(token: string): string {
+  return `${BURN_KEY_PREFIX}${token}`;
+}
+
+/** Speichert das Pair bidirektional und setzt TTL auf beiden Keys.
+ *  Idempotent — re-write derselben Token-Invitation-Kombi ist OK
+ *  (refresh TTL für Resend). */
+export async function storeInviteToken(
+  redis: Redis,
+  args: { invitationId: string; token: string; ttlSeconds: number },
+): Promise<void> {
+  await Promise.all([
+    redis.set(tokenKey(args.token), args.invitationId, "EX", args.ttlSeconds),
+    redis.set(idKey(args.invitationId), args.token, "EX", args.ttlSeconds),
+  ]);
+}
+
+/** Lookup: invitationId für Token. Null wenn Token nicht (mehr) existiert
+ *  (abgelaufen, schon konsumiert, oder ungültig). */
+export async function getInvitationIdForToken(redis: Redis, token: string): Promise<string | null> {
+  return redis.get(tokenKey(token));
+}
+
+/** Lookup: Existierender Token für eine invitationId — für Resend-
+ *  Idempotenz (Admin invitet dieselbe email zweimal → re-use token). */
+export async function getTokenForInvitation(
+  redis: Redis,
+  invitationId: string,
+): Promise<string | null> {
+  return redis.get(idKey(invitationId));
+}
+
+/** Single-Use-Burn. Wenn zwei Tabs gleichzeitig den Accept-Link klicken,
+ *  gewinnt der erste, der zweite kriegt "already-used". TTL = 1h. */
+export async function burnInviteToken(
+  redis: Redis,
+  token: string,
+): Promise<"burned" | "already-used"> {
+  const result = await redis.set(burnKey(token), "1", "EX", 3600, "NX");
+  return result === "OK" ? "burned" : "already-used";
+}
+
+/** Cleanup nach erfolgreichem Accept ODER Cancel — beide Lookup-Keys
+ *  löschen. Burn-Key bleibt für die restliche Burn-TTL als Replay-Schutz. */
+export async function deleteInviteToken(
+  redis: Redis,
+  args: { invitationId: string; token: string },
+): Promise<void> {
+  await Promise.all([redis.del(tokenKey(args.token)), redis.del(idKey(args.invitationId))]);
+}
+
+/** Burn-Release für Failed-Accept-Pfade (DB-Error etc.) damit ein
+ *  legitimer Retry nicht durch einen stale Burn-Marker geblockt wird. */
+export async function unburnInviteToken(redis: Redis, token: string): Promise<void> {
+  await redis.del(burnKey(token));
+}

package/src/auth-email-password/lockout-store.ts

@@ -0,0 +1,118 @@
+// Redis-backed account-lockout state for the login handler.
+//
+// Why Redis, not DB? The login handler returns WriteFailure on bad
+// credentials — the dispatcher rolls back the whole transaction, which
+// would wipe a DB-based counter-update alongside the "invalid credentials"
+// response. Redis operations run outside the DB tx and survive the rollback.
+// Consistent with token-burn-store.ts, which uses Redis for the same reason
+// (state that must persist regardless of the handler's WriteResult).
+//
+// Persistence note: in prod, configure Redis with AOF or RDB so lockout
+// state survives Redis restart. Without persistence, a restart resets every
+// active counter — an attacker could exploit the gap, though the IP-level
+// rate-limiter (framework rate-limit) is the parallel defense for that
+// case anyway.
+
+import type Redis from "ioredis";
+
+export type LockoutState = {
+  readonly failureCount: number;
+  // Epoch milliseconds when the account auto-unlocks. null while the
+  // counter is still below threshold.
+  readonly lockedUntil: number | null;
+};
+
+// Two keys per user so each can carry its own TTL:
+//   - count-key: 24h, carries the streak. Monotonic — once threshold is
+//     crossed it STAYS crossed until a successful login clears it.
+//   - until-key: exactly the lockout duration, auto-expires when the lock
+//     ends (Redis TTL replaces a "timer" that would otherwise need a job).
+//
+// Consequence of the monotonic counter: once a user has been locked, the
+// NEXT wrong password after the lock expires re-locks immediately — the
+// INCR still returns a value ≥ threshold, so the SET NX re-arms the lock.
+// A successful login is the only way to reset the streak. Intentional:
+// brute-force resistance favours strictness over UX, and a legitimate user
+// who hit the lock once can just log in correctly to clear it.
+const COUNT_KEY_PREFIX = "kumiko:auth:lockout:count:";
+const UNTIL_KEY_PREFIX = "kumiko:auth:lockout:until:";
+
+function countKey(userId: string): string {
+  return `${COUNT_KEY_PREFIX}${userId}`;
+}
+function untilKey(userId: string): string {
+  return `${UNTIL_KEY_PREFIX}${userId}`;
+}
+
+export async function getLockoutState(redis: Redis, userId: string): Promise<LockoutState | null> {
+  const [countRaw, untilRaw] = await redis.mget(countKey(userId), untilKey(userId));
+  if (countRaw === null) return null;
+  const failureCount = Number(countRaw);
+  if (!Number.isFinite(failureCount)) return null;
+  const lockedUntil = untilRaw !== null ? Number(untilRaw) : null;
+  return {
+    failureCount,
+    lockedUntil: lockedUntil !== null && Number.isFinite(lockedUntil) ? lockedUntil : null,
+  };
+}
+
+// Race-free: INCR is atomic at the Redis level, so N concurrent wrong-
+// password attempts produce exactly N increments — no GET-SET window to
+// lose an increment through. The NX on the until-key likewise guarantees
+// only one attempt out of a concurrent batch sets the lock timestamp;
+// subsequent concurrent attempts find the key already set and leave it
+// alone, so the lock window stays anchored to the first-to-cross, not
+// the last.
+export async function recordFailedAttempt(
+  redis: Redis,
+  userId: string,
+  maxFailedAttempts: number,
+  lockoutDurationMinutes: number,
+): Promise<LockoutState> {
+  const lockDurationMs = lockoutDurationMinutes * 60 * 1000;
+  // TTL on the count-key: 24h covers "I fat-fingered yesterday". The
+  // lockout duration is on the until-key; the count-key outlives it so an
+  // expired lock leaves a counter ≥ threshold — that's what makes the next
+  // miss immediately re-lock (strict-semantic; see the type-comment above).
+  const ttlSec = Math.max(lockoutDurationMinutes * 60, 24 * 3600);
+
+  const count = await redis.incr(countKey(userId));
+  if (count === 1) {
+    // First failure → set the TTL. INCR doesn't set one; a counter without
+    // TTL would leak forever for users that never return.
+    await redis.expire(countKey(userId), ttlSec);
+  }
+
+  let lockedUntil: number | null = null;
+  if (count >= maxFailedAttempts) {
+    const computedUntil = Date.now() + lockDurationMs;
+    // NX: only set if no lock is currently armed. A second concurrent attempt
+    // arriving after the first crossed the threshold must NOT reset the
+    // timer — the lock window should align with the attempt that crossed,
+    // not the one that happened a millisecond later.
+    const setOk = await redis.set(
+      untilKey(userId),
+      String(computedUntil),
+      "PX",
+      lockDurationMs,
+      "NX",
+    );
+    if (setOk === "OK") {
+      lockedUntil = computedUntil;
+    } else {
+      // Another concurrent attempt already locked — read the authoritative
+      // timestamp so the returned state matches what a follow-up
+      // getLockoutState would see.
+      const existing = await redis.get(untilKey(userId));
+      lockedUntil = existing !== null ? Number(existing) : null;
+    }
+  }
+
+  return { failureCount: count, lockedUntil };
+}
+
+// Called on successful login. Idempotent — deleting missing keys is a no-op.
+// The ONLY path that resets the counter; intentional.
+export async function clearLockoutState(redis: Redis, userId: string): Promise<void> {
+  await redis.del(countKey(userId), untilKey(userId));
+}

package/src/auth-email-password/password-hashing.ts

@@ -0,0 +1,43 @@
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+import { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+
+// OWASP-recommended argon2id parameters (2024 guidance):
+//   memoryCost: 19 MiB, timeCost: 2, parallelism: 1
+// These strike a balance between login latency (~20ms on typical hardware)
+// and brute-force resistance. If hashing becomes a bottleneck, tune memoryCost
+// before parallelism — memory hardness is what defeats GPU attacks.
+//
+// algorithm: 2 = Argon2id (best of argon2i + argon2d).
+// We inline the numeric value instead of importing Algorithm because the
+// @node-rs/argon2 enum is const and breaks verbatimModuleSyntax imports.
+const HASH_OPTIONS = {
+  algorithm: 2,
+  memoryCost: 19456,
+  timeCost: 2,
+  parallelism: 1,
+} as const;
+
+export async function hashPassword(password: string): Promise<string> {
+  return argonHash(password, HASH_OPTIONS);
+}
+
+// Returns true if the password matches. Never throws on wrong passwords —
+// only on malformed hash strings (which would be a bug, not a login attempt).
+//
+// Two verifier paths:
+//   - argon2id (default, what `hashPassword` produces)
+//   - ASP.NET Core Identity V3 (verify-only, for legacy migrations from .NET
+//     stacks). Sniffed via the format marker; on a successful match the
+//     application can rehash to argon2 at the next password-change event.
+export async function verifyPassword(hashString: string, password: string): Promise<boolean> {
+  if (isIdentityV3Hash(hashString)) {
+    return verifyIdentityV3Hash(password, hashString);
+  }
+  try {
+    return await argonVerify(hashString, password);
+  } catch {
+    // argon2 throws on unparseable hash — treat as mismatch rather than 500
+    // to avoid revealing which accounts have corrupted stored hashes.
+    return false;
+  }
+}

package/src/auth-email-password/reset-token.ts

@@ -0,0 +1,28 @@
+// Thin wrapper around signed-token.ts pinning the purpose to "reset".
+// Handlers keep their terse API (signResetToken / verifyResetToken) while
+// the shared HMAC logic lives in one place. verification-token.ts mirrors
+// this pattern with purpose="verify".
+
+import type { Temporal } from "temporal-polyfill";
+import { signToken, TokenPurpose, verifyToken } from "./signed-token";
+
+export type VerifyResult =
+  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+export function signResetToken(
+  userId: string,
+  ttlMinutes: number,
+  secret: string,
+  now?: Temporal.Instant,
+): { token: string; expiresAt: Temporal.Instant } {
+  return signToken(userId, TokenPurpose.passwordReset, ttlMinutes, secret, now);
+}
+
+export function verifyResetToken(
+  token: string,
+  secret: string,
+  now?: Temporal.Instant,
+): VerifyResult {
+  return verifyToken(token, TokenPurpose.passwordReset, secret, now);
+}

package/src/auth-email-password/seeding.ts

@@ -0,0 +1,183 @@
+// Stable seeding helpers fürs auth-email-password-Feature. Liegen unter
+// `/seeding` (nicht `/testing`) damit der Vertrag klar ist: hier ist
+// non-test code der bei jedem Dev-Boot + jedem Integration-Test läuft.
+// Test-spezifische Variationen (account-locked-Setup, expired-token,
+// race-conditions) werden NICHT als Knöpfe an diesen Helpers angebaut —
+// sie kommen als neue Funktionen daneben oder inline ins Test-File.
+//
+// Bündelt drei Schritte in einem Aufruf:
+//   1. argon2-Hash des Plain-Passworts
+//   2. seedUser() aus user/seeding
+//   3. seedTenant + seedTenantMembership aus tenant/seeding
+// Damit Sample-Server und Tests keine drei sub-paths zusammensammeln
+// müssen.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+// kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
+import { seedTenant, seedTenantMembership } from "../tenant/seeding";
+// kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
+import { seedUser } from "../user/seeding";
+import { hashPassword } from "./password-hashing";
+
+// Re-export für ergonomische Single-Import-Site in tests/seed-scripts.
+// Das Auth-Feature ist der natürliche Aufrufer für "seed admin user mit
+// password + tenant + membership" — wer das nutzt soll nicht aus drei
+// verschiedenen sub-paths zusammensammeln müssen.
+// kumiko-lint-ignore cross-feature-import re-export of test-helpers
+export { seedTenant, seedTenantMembership } from "../tenant/seeding";
+// kumiko-lint-ignore cross-feature-import re-export of test-helpers
+export { seedUser } from "../user/seeding";
+
+export type SeedUserWithPasswordOptions = {
+  readonly email: string;
+  readonly password: string;
+  readonly displayName: string;
+  readonly locale?: string;
+  /** Globale Rollen — siehe SeedUserOptions.roles. */
+  readonly roles?: readonly string[];
+  /** Initial-emailVerified-Flag. Default false (Verify-Flow läuft).
+   *  Magic-Link-Signup setzt true weil der Mail-Klick die Email-
+   *  Ownership beweist. Siehe SeedUserOptions.emailVerified. */
+  readonly emailVerified?: boolean;
+  readonly by?: SessionUser;
+};
+
+/**
+ * Seed a user mit Plain-Password (wird vor dem Insert mit argon2
+ * gehasht). Liefert userId, idempotent über email.
+ */
+export async function seedUserWithPassword(
+  db: DbConnection,
+  options: SeedUserWithPasswordOptions,
+): Promise<string> {
+  const passwordHash = await hashPassword(options.password);
+  return seedUser(db, {
+    email: options.email,
+    displayName: options.displayName,
+    passwordHash,
+    ...(options.locale !== undefined && { locale: options.locale }),
+    ...(options.roles !== undefined && { roles: options.roles }),
+    ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
+    ...(options.by !== undefined && { by: options.by }),
+  });
+}
+
+/** Provisioning-Helper für Self-Signup-Confirm. Legt einen frischen
+ *  Tenant + Admin-User + Membership in einem Rutsch an — verwendet die
+ *  bestehende Event-Store-Pipeline (wie seedAdmin) und ist daher
+ *  konsistent mit dem regulären create-Pfad: events werden geschrieben,
+ *  Projections sind populated, MSPs/Audit sehen die neuen Rows.
+ *
+ *  Naming-Hinweis: nutzt intern `seedTenant` / `seedUser*` —
+ *  diese Helpers sind production-grade (event-store-pipeline), das "seed"
+ *  im Namen ist historisch (zuerst für Tests + Bootstrap gebaut, dann
+ *  als General-Purpose-Helper exportiert). Rename `seed*` → `provision*`
+ *  ist als dedizierter Cleanup-PR geplant — disproportional zum Wert
+ *  innerhalb dieses Sprints, weil alle existing tests berührt würden.
+ *
+ *  Atomicity: läuft inside einer Drizzle-Tx wenn der Caller das angibt
+ *  (db.transaction(tx => provisionSignupAccount(tx, ...)) — die seed-
+ *  helpers nehmen DbConnection|DbTx strukturell. Bei pure DbConnection
+ *  sind die 3 writes nicht atomic; bei Failure zwischen Schritten kann
+ *  ein orphan-Tenant zurückbleiben (Tenant ohne User → unused row;
+ *  User ohne Membership → "no_membership" beim ersten Login).
+ *
+ *  Nicht idempotent: ein zweiter Aufruf für dieselbe Email wirft (über
+ *  seedTenant + seedUser deren idempotenz-Check sich an key/email
+ *  orientiert; bei collidierenden tenantKey ist der Caller
+ *  verantwortlich, einen freien zu finden — siehe generateUniqueName). */
+/** Default-Roles für den Self-Signup-Admin. Geteilt zwischen
+ *  provisionSignupAccount (DB-write) und signup-confirm-handler
+ *  (SessionUser-Konstruktion für JWT-Mint) — sonst hätten zwei
+ *  Stellen unabhängig "Admin" hardcoded und würden bei einem
+ *  Refactor zu role-mismatch zwischen DB und Session leiden. */
+export const INITIAL_SIGNUP_ROLES = ["Admin"] as const;
+
+export type ProvisionSignupAccountOptions = {
+  readonly email: string;
+  readonly password: string;
+  readonly displayName: string;
+  readonly tenantKey: string;
+  readonly tenantName: string;
+  readonly tenantId: TenantId;
+  readonly memberRoles?: readonly string[];
+};
+
+export async function provisionSignupAccount(
+  db: DbConnection,
+  options: ProvisionSignupAccountOptions,
+): Promise<{ readonly userId: string; readonly tenantId: TenantId }> {
+  await seedTenant(db, {
+    id: options.tenantId,
+    key: options.tenantKey,
+    name: options.tenantName,
+  });
+  const userId = await seedUserWithPassword(db, {
+    email: options.email,
+    password: options.password,
+    displayName: options.displayName,
+    emailVerified: true,
+  });
+  await seedTenantMembership(db, {
+    userId,
+    tenantId: options.tenantId,
+    roles: options.memberRoles ?? INITIAL_SIGNUP_ROLES,
+  });
+  return { userId, tenantId: options.tenantId };
+}
+
+export type SeedAdminOptions = {
+  readonly email: string;
+  readonly password: string;
+  readonly displayName: string;
+  /** Tenants, in die der Admin als Mitglied eingetragen wird. Pro
+   *  Tenant kann eine eigene Rollenliste gesetzt werden — hilft beim
+   *  Sample-TenantSwitcher der pro Tenant unterschiedliche
+   *  Rollen-Listen zeigt. */
+  readonly memberships: ReadonlyArray<{
+    readonly tenantId: TenantId;
+    readonly tenantKey: string;
+    readonly tenantName: string;
+    readonly roles: readonly string[];
+  }>;
+  /** Globale Rollen die in users.roles landen — tenant-unabhängig.
+   *  Login-Handler mergt sie in jede Session parallel zu den tenant-
+   *  membership-Rollen. Typischer use-case: `["SystemAdmin"]` für
+   *  einen Plattform-Operator. Default: leer. */
+  readonly globalRoles?: readonly string[];
+  readonly by?: SessionUser;
+};
+
+/**
+ * Seed-Convenience für Sample-Server: Admin-User mit gehashtem
+ * Password + N Tenants + N Memberships. Alles idempotent (Re-Run im
+ * persistent-DB-Modus läuft durch). Liefert die userId zurück.
+ */
+export async function seedAdmin(db: DbConnection, options: SeedAdminOptions): Promise<string> {
+  const by = options.by ?? TestUsers.systemAdmin;
+
+  for (const m of options.memberships) {
+    await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
+  }
+
+  const userId = await seedUserWithPassword(db, {
+    email: options.email,
+    password: options.password,
+    displayName: options.displayName,
+    ...(options.globalRoles !== undefined && { roles: options.globalRoles }),
+    by,
+  });
+
+  for (const m of options.memberships) {
+    await seedTenantMembership(db, {
+      userId,
+      tenantId: m.tenantId,
+      roles: m.roles,
+      by,
+    });
+  }
+
+  return userId;
+}