@cosmicdrift/kumiko-samples 0.340.0 → 0.341.0

package/packages/bundled-features/src/waitlist/feature.ts

@@ -0,0 +1,50 @@
+import {
+  defineFeature,
+  EXT_USER_DATA,
+  type FeatureDefinition,
+  i18nKey,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { WAITLIST_FEATURE } from "./constants.js";
+import { waitlistEntryEntity } from "./entity.js";
+import { createInviteHandler } from "./handlers/invite.write.js";
+import { listQuery } from "./handlers/list.query.js";
+import { rejectHandler } from "./handlers/reject.write.js";
+import { createSubmitHandler } from "./handlers/submit.write.js";
+import { WAITLIST_I18N } from "./i18n.js";
+import { adminAccess } from "./lib.js";
+import type { WaitlistOptions } from "./options.js";
+import { waitlistListScreen } from "./screens.js";
+import { waitlistEntryDeleteHook, waitlistEntryExportHook } from "./user-data-hooks.js";
+
+export function createWaitlistFeature(opts: WaitlistOptions = {}): FeatureDefinition {
+  return defineFeature(WAITLIST_FEATURE, (r) => {
+    r.describe(
+      "Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response never reveals whether an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.",
+    );
+    r.uiHints({ displayLabel: "Waitlist", category: "data", recommended: false });
+    r.systemScope();
+    r.requires("tenant", "auth-email-password", "user-data-rights");
+    r.translations({ keys: WAITLIST_I18N });
+
+    r.entity("waitlistEntry", waitlistEntryEntity);
+    r.writeHandler(createSubmitHandler(opts));
+    r.writeHandler(createInviteHandler(opts.invite));
+    r.writeHandler(rejectHandler);
+    r.queryHandler(listQuery);
+
+    r.screen(waitlistListScreen);
+    r.nav({
+      id: "waitlist",
+      label: i18nKey("waitlist.nav.waitlist"),
+      screen: "waitlist:screen:waitlist-list",
+      icon: "users",
+      order: 15,
+      access: adminAccess,
+    });
+
+    r.useExtension(EXT_USER_DATA, "waitlistEntry", {
+      export: waitlistEntryExportHook,
+      delete: waitlistEntryDeleteHook,
+    });
+  });
+}

package/packages/bundled-features/src/waitlist/handlers/invite.write.ts

@@ -0,0 +1,175 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type HandlerContext,
+  parseTenantId,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  NotFoundError,
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "temporal-polyfill";
+import { AuthErrors, AuthHandlers } from "../../auth-email-password/index.js";
+import { TenantHandlers, tenantTable } from "../../tenant/index.js";
+import { DEFAULT_OWN_TENANT_INVITE_ROLE, WAITLIST_STATUS, WaitlistErrors } from "../constants.js";
+import { isOpenWaitlistStatus } from "../entity.js";
+import { adminAccess, platformActor, waitlistDb, waitlistExecutor } from "../lib.js";
+import type { WaitlistInviteOptions } from "../options.js";
+import { WaitlistIdSchema } from "../payloads.js";
+
+export type WaitlistInviteData = {
+  readonly kind: "invited";
+  readonly id: string;
+  readonly tenantId: string;
+};
+
+type InviteTarget = { readonly tenantId: TenantId; readonly role: string };
+
+const DEFAULT_INVITE: WaitlistInviteOptions = {
+  mode: "own-tenant",
+  role: DEFAULT_OWN_TENANT_INVITE_ROLE,
+};
+
+// Derived from the entry id so a retry finds the tenant a half-failed run created.
+function tenantKeyForEntry(entryId: string): string {
+  return `waitlist-${entryId}`;
+}
+
+type EntryRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly status: unknown;
+  readonly email: string;
+  readonly name: string;
+  readonly company: string | null;
+  readonly linkedTenantId: string | null;
+};
+
+function readEntryRow(row: Record<string, unknown>): EntryRow {
+  const { id, version, email, name, company, linkedTenantId } = row;
+  if (
+    typeof id !== "string" ||
+    typeof version !== "number" ||
+    typeof email !== "string" ||
+    typeof name !== "string"
+  ) {
+    throw new InternalError({ message: "waitlist:invite: malformed waitlist row" });
+  }
+  return {
+    id,
+    version,
+    status: row["status"],
+    email,
+    name,
+    company: typeof company === "string" && company !== "" ? company : null,
+    linkedTenantId: typeof linkedTenantId === "string" ? linkedTenantId : null,
+  };
+}
+
+function isInviteAlreadyAccepted(details: unknown): boolean {
+  return (
+    typeof details === "object" &&
+    details !== null &&
+    "reason" in details &&
+    details.reason === AuthErrors.inviteAlreadyAccepted
+  );
+}
+
+async function ensureOwnTenant(
+  entry: EntryRow,
+  ctx: HandlerContext,
+): Promise<TenantId | WriteFailure> {
+  const linked = entry.linkedTenantId === null ? null : parseTenantId(entry.linkedTenantId);
+  if (linked) return linked;
+
+  const key = tenantKeyForEntry(entry.id);
+  const existing = await fetchOne<{ id: string }>(waitlistDb(ctx), tenantTable, { key });
+  const existingId = existing ? parseTenantId(existing.id) : null;
+  if (existingId) return existingId;
+
+  const newTenantId = parseTenantId(crypto.randomUUID());
+  if (!newTenantId) throw new InternalError({ message: "waitlist:invite: tenant id mint failed" });
+  const created = await ctx.writeAs(createSystemUser(newTenantId), TenantHandlers.create, {
+    id: newTenantId,
+    key,
+    name: entry.company ?? entry.name,
+  });
+  return created.isSuccess ? newTenantId : created;
+}
+
+async function resolveInviteTarget(
+  invite: WaitlistInviteOptions,
+  entry: EntryRow,
+  ctx: HandlerContext,
+): Promise<InviteTarget | WriteFailure> {
+  if (invite.mode === "shared-tenant") return { tenantId: invite.tenantId, role: invite.role };
+  const tenantId = await ensureOwnTenant(entry, ctx);
+  if (typeof tenantId !== "string") return tenantId;
+  return { tenantId, role: invite.role ?? DEFAULT_OWN_TENANT_INVITE_ROLE };
+}
+
+export function createInviteHandler(invite: WaitlistInviteOptions = DEFAULT_INVITE) {
+  return defineWriteHandler<"invite", typeof WaitlistIdSchema, WaitlistInviteData>({
+    name: "invite",
+    schema: WaitlistIdSchema,
+    access: adminAccess,
+    description:
+      "Invites a pending or already-invited waitlist entry: creates its tenant (or uses the configured shared tenant), mails the entrant a fresh accept link with the configured role and marks the entry invited; rejected entries cannot be invited. The invitee never receives a global role.",
+    // Sends an invite link by email, which cannot be recalled.
+    agent: { risk: "high" },
+    handler: async (event, ctx) => {
+      const db = waitlistDb(ctx);
+      const row = await waitlistExecutor.detail({ id: event.payload.id }, platformActor(), db);
+      if (!row) return writeFailure(new NotFoundError("waitlistEntry", event.payload.id));
+      const entry = readEntryRow(row);
+      if (!isOpenWaitlistStatus(entry.status)) {
+        return writeFailure(new UnprocessableError(WaitlistErrors.notInvitable));
+      }
+
+      const target = await resolveInviteTarget(invite, entry, ctx);
+      if ("isSuccess" in target) return target;
+
+      // inviteCreate is admin-only (no system role); the system variant with an
+      // empty globalRoles list is the only in-process path, and a waitlist
+      // invite must never grant a global role.
+      const invited = await ctx.writeAs(
+        createSystemUser(target.tenantId),
+        AuthHandlers.systemInviteCreate,
+        { email: entry.email.toLowerCase(), role: target.role, globalRoles: [] },
+      );
+      if (!invited.isSuccess) {
+        // Re-inviting a person who already accepted would reset their live invitation.
+        if (isInviteAlreadyAccepted(invited.error.details)) {
+          return writeFailure(new UnprocessableError(WaitlistErrors.notInvitable));
+        }
+        return invited;
+      }
+
+      const updated = await waitlistExecutor.update(
+        {
+          id: entry.id,
+          version: entry.version,
+          changes: {
+            status: WAITLIST_STATUS.Invited,
+            invitedAt: Temporal.Now.instant(),
+            invitedBy: event.user.id,
+            linkedTenantId: target.tenantId,
+          },
+        },
+        platformActor(),
+        db,
+      );
+      if (!updated.isSuccess) return updated;
+
+      return {
+        isSuccess: true,
+        data: { kind: "invited", id: entry.id, tenantId: target.tenantId },
+      };
+    },
+  });
+}

package/packages/bundled-features/src/waitlist/handlers/list.query.ts

@@ -0,0 +1,12 @@
+import { defineEntityListHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { waitlistEntryEntity } from "../entity.js";
+import { adminAccess } from "../lib.js";
+
+// Entity-convention list: the QN waitlist:query:waitlist-entry:list is what the
+// entityList screen resolves; paging, search and sort come from the entity flags.
+export const listQuery = defineEntityListHandler("waitlistEntry", waitlistEntryEntity, {
+  access: adminAccess,
+  agent: { risk: "high" },
+  description:
+    "Lists waitlist entries for the admin screen with paging, search over name, email and company, and sorting; carries the entrants' personal data.",
+});

package/packages/bundled-features/src/waitlist/handlers/reject.write.ts

@@ -0,0 +1,120 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type HandlerContext,
+  parseTenantId,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  NotFoundError,
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import {
+  cancelPendingInvitation,
+  INVITATION_STATUS,
+  tenantInvitationsTable,
+  tenantMembershipsTable,
+} from "../../tenant/index.js";
+import { userTable } from "../../user/index.js";
+import { WAITLIST_STATUS, WaitlistErrors } from "../constants.js";
+import { isOpenWaitlistStatus } from "../entity.js";
+import {
+  adminAccess,
+  normalizeEmail,
+  platformActor,
+  waitlistDb,
+  waitlistExecutor,
+} from "../lib.js";
+import { WaitlistIdSchema } from "../payloads.js";
+
+export type WaitlistRejectData = { readonly kind: "rejected"; readonly id: string };
+
+// An admin re-invite can flip an accepted invitation back to pending, so the
+// invitation status alone cannot prove the person holds no access.
+async function isTenantMember(db: TenantDb, email: string, tenantId: TenantId): Promise<boolean> {
+  const user = await fetchOne<{ id: string }>(db, userTable, {
+    email: normalizeEmail(email),
+    isDeleted: false,
+  });
+  if (!user) return false;
+  const membership = await fetchOne(db, tenantMembershipsTable, { userId: user.id, tenantId });
+  return membership !== undefined && membership !== null;
+}
+
+// An invited entry already has a live invitation link; rejecting must kill it,
+// otherwise the rejected person can still sign up. Once accepted they hold
+// access, which only tenant member removal may revoke.
+async function revokeInvitation(
+  row: Record<string, unknown>,
+  ctx: HandlerContext,
+): Promise<WriteFailure | undefined> {
+  const { status, linkedTenantId, email } = row;
+  if (status !== WAITLIST_STATUS.Invited) return undefined;
+  const tenantId = typeof linkedTenantId === "string" ? parseTenantId(linkedTenantId) : null;
+  if (!tenantId || typeof email !== "string") return undefined;
+  const db = waitlistDb(ctx);
+  const invitations = await selectMany(db, tenantInvitationsTable, {
+    tenantId,
+    email: normalizeEmail(email),
+  });
+  if (
+    invitations.some((invitation) => invitation["status"] === INVITATION_STATUS.accepted) ||
+    (await isTenantMember(db, email, tenantId))
+  ) {
+    return writeFailure(new UnprocessableError(WaitlistErrors.notRejectable));
+  }
+  for (const invitation of invitations) {
+    if (invitation["status"] !== INVITATION_STATUS.pending) continue;
+    const id = invitation["id"];
+    const version = invitation["version"];
+    if (typeof id !== "string" || typeof version !== "number") {
+      throw new InternalError({ message: "waitlist:reject: malformed invitation row" });
+    }
+    const cancelled = await cancelPendingInvitation(
+      db,
+      { id, version },
+      createSystemUser(tenantId),
+      ctx.redis,
+    );
+    if (cancelled) return cancelled;
+  }
+  return undefined;
+}
+
+export const rejectHandler = defineWriteHandler<
+  "reject",
+  typeof WaitlistIdSchema,
+  WaitlistRejectData
+>({
+  name: "reject",
+  schema: WaitlistIdSchema,
+  access: adminAccess,
+  description:
+    "Marks a pending or invited waitlist entry as rejected, used by admins to dismiss spam or noise; the row and its personal data stay until erased.",
+  handler: async (event, ctx) => {
+    const db = waitlistDb(ctx);
+    const row = await waitlistExecutor.detail({ id: event.payload.id }, platformActor(), db);
+    if (!row) return writeFailure(new NotFoundError("waitlistEntry", event.payload.id));
+    const version = row["version"];
+    if (typeof version !== "number") {
+      throw new InternalError({ message: "waitlist:reject: malformed waitlist row" });
+    }
+    if (!isOpenWaitlistStatus(row["status"])) {
+      return writeFailure(new UnprocessableError(WaitlistErrors.notRejectable));
+    }
+    const revoked = await revokeInvitation(row, ctx);
+    if (revoked) return revoked;
+    const updated = await waitlistExecutor.update(
+      { id: event.payload.id, version, changes: { status: WAITLIST_STATUS.Rejected } },
+      platformActor(),
+      db,
+    );
+    if (!updated.isSuccess) return updated;
+    return { isSuccess: true, data: { kind: "rejected", id: event.payload.id } };
+  },
+});

package/packages/bundled-features/src/waitlist/handlers/submit.write.ts

@@ -0,0 +1,163 @@
+import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  defineWriteHandler,
+  type HandlerContext,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "temporal-polyfill";
+import { WAITLIST_NOTIFICATION_TYPES, WAITLIST_STATUS } from "../constants.js";
+import { normalizeEmail, platformActor, waitlistDb, waitlistExecutor } from "../lib.js";
+import {
+  renderWaitlistAdminNoticeEmail,
+  renderWaitlistConfirmationEmail,
+  resolveWaitlistAdminMailLocale,
+  resolveWaitlistMailLocale,
+} from "../mail.js";
+import {
+  DEFAULT_SUBMIT_EMAIL_RATE_LIMITS,
+  DEFAULT_SUBMIT_RATE_LIMIT,
+  type WaitlistOptions,
+} from "../options.js";
+import { type WaitlistSubmitInput, WaitlistSubmitSchema } from "../payloads.js";
+
+// pg_advisory_xact_lock namespace (int4): 'wlst' as ASCII, disjoint from the
+// framework's other fixed advisory-lock keys.
+const SUBMIT_LOCK_NAMESPACE = 0x776c7374;
+const SUBMIT_LOCK_REASON =
+  "takes the per-email advisory lock so parallel submits cannot both pass the duplicate check; TenantDb has no lock API";
+
+// Logged-in callers carry no anonymous role, so every signed-in role must be listed.
+const SUBMIT_ROLES = access.roles(
+  ...access.anonymous,
+  ...access.authenticated,
+  "Member",
+  "TenantAdmin",
+);
+
+export type WaitlistSubmitData = { readonly kind: "submitted" };
+
+// Identical for new, duplicate and honeypot submits: the response must not
+// reveal whether the email is already on the list.
+const SUBMITTED: WriteResult<WaitlistSubmitData> = {
+  isSuccess: true,
+  data: { kind: "submitted" },
+};
+
+// An explicitly bound `undefined` is an error for the postgres driver; a missing key is not.
+function presentOptionalFields(payload: WaitlistSubmitInput) {
+  return {
+    ...(payload.company !== undefined && { company: payload.company }),
+    ...(payload.portfolio !== undefined && { portfolio: payload.portfolio }),
+    ...(payload.message !== undefined && { message: payload.message }),
+  };
+}
+
+function isHoneypotFilled(payload: WaitlistSubmitInput): boolean {
+  return payload.website !== undefined && payload.website.trim() !== "";
+}
+
+async function hasOpenEntryForEmail(email: string, ctx: HandlerContext): Promise<boolean> {
+  const found = await waitlistExecutor.list(
+    { filter: { field: "email", op: "eq", value: email }, limit: 50 },
+    platformActor(),
+    waitlistDb(ctx),
+  );
+  return found.rows.some(
+    (row) => row["status"] === WAITLIST_STATUS.Pending || row["status"] === WAITLIST_STATUS.Invited,
+  );
+}
+
+async function sendBestEffort(
+  ctx: HandlerContext,
+  label: string,
+  send: (notify: NonNullable<HandlerContext["notify"]>) => Promise<unknown>,
+): Promise<void> {
+  try {
+    if (!ctx.notify) {
+      throw new InternalError({ message: "ctx.notify unavailable — mount the delivery feature" });
+    }
+    await send(ctx.notify);
+  } catch (err) {
+    ctx.log?.warn(`[waitlist:submit] ${label} mail failed`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+export function createSubmitHandler(opts: WaitlistOptions) {
+  return defineWriteHandler<"submit", typeof WaitlistSubmitSchema, WaitlistSubmitData>({
+    name: "submit",
+    schema: WaitlistSubmitSchema,
+    access: { roles: SUBMIT_ROLES, personalData: "public-intake" },
+    rateLimit: opts.rateLimit ?? DEFAULT_SUBMIT_RATE_LIMIT,
+    additionalRateLimits: opts.emailRateLimits ?? DEFAULT_SUBMIT_EMAIL_RATE_LIMITS,
+    description:
+      "Public waitlist sign-up: registers an interest entry and sends the submitter a confirmation mail. Always reports success, whether the address is new or already on the list.",
+    escapeHatch: { grants: ["unsafeRaw"], reason: SUBMIT_LOCK_REASON },
+    handler: async (event, ctx) => {
+      const payload = event.payload;
+      if (isHoneypotFilled(payload)) return SUBMITTED;
+
+      const email = normalizeEmail(payload.email);
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message: "waitlist:submit requires ctx.systemDb — is r.systemScope() set?",
+        });
+      }
+      await acquireNamespacedAdvisoryLock(
+        ctx.systemDb.unsafeRaw(SUBMIT_LOCK_REASON),
+        SUBMIT_LOCK_NAMESPACE,
+        email,
+      );
+      if (await hasOpenEntryForEmail(email, ctx)) return SUBMITTED;
+
+      const created = await waitlistExecutor.create(
+        {
+          name: payload.name,
+          email,
+          locale: payload.locale,
+          ...presentOptionalFields(payload),
+          status: WAITLIST_STATUS.Pending,
+          submittedAt: Temporal.Now.instant(),
+        },
+        platformActor(),
+        waitlistDb(ctx),
+      );
+      if (!created.isSuccess) return created;
+
+      await sendBestEffort(ctx, "confirmation", (notify) =>
+        notify(WAITLIST_NOTIFICATION_TYPES.confirmation, {
+          route: { email },
+          data: renderWaitlistConfirmationEmail({
+            locale: payload.locale,
+            appName: opts.appName,
+          }),
+          priority: "normal",
+          locale: resolveWaitlistMailLocale(payload.locale),
+        }),
+      );
+
+      await sendBestEffort(ctx, "admin notice", async (notify) => {
+        const adminRecipient = opts.notifyRecipient?.(ctx);
+        // skip: no admin recipient configured
+        if (!adminRecipient) return;
+        await notify(WAITLIST_NOTIFICATION_TYPES.adminNotice, {
+          route: { email: adminRecipient },
+          data: renderWaitlistAdminNoticeEmail({
+            name: payload.name,
+            email,
+            company: payload.company,
+            message: payload.message,
+            adminLocale: ctx.locale,
+          }),
+          priority: "normal",
+          locale: resolveWaitlistAdminMailLocale(ctx.locale),
+        });
+      });
+
+      return SUBMITTED;
+    },
+  });
+}

package/packages/bundled-features/src/waitlist/i18n.ts

@@ -0,0 +1,33 @@
+type LocalizedString = { readonly en: string; readonly de: string };
+
+export const WAITLIST_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:waitlist-list.title": { en: "Waitlist", de: "Warteliste" },
+  "waitlist.nav.waitlist": { en: "Waitlist", de: "Warteliste" },
+  "waitlist:entity:waitlistEntry:field:name": { en: "Name", de: "Name" },
+  "waitlist:entity:waitlistEntry:field:email": { en: "Email", de: "E-Mail" },
+  "waitlist:entity:waitlistEntry:field:company": { en: "Company", de: "Firma" },
+  "waitlist:entity:waitlistEntry:field:portfolio": { en: "Portfolio", de: "Portfolio" },
+  "waitlist:entity:waitlistEntry:field:message": { en: "Message", de: "Nachricht" },
+  "waitlist:entity:waitlistEntry:field:locale": { en: "Locale", de: "Sprache" },
+  "waitlist:entity:waitlistEntry:field:status": { en: "Status", de: "Status" },
+  "waitlist:entity:waitlistEntry:field:submittedAt": { en: "Created", de: "Erstellt" },
+  "waitlist:entity:waitlistEntry:field:status:option:pending": {
+    en: "Pending",
+    de: "Ausstehend",
+  },
+  "waitlist:entity:waitlistEntry:field:status:option:invited": {
+    en: "Invited",
+    de: "Eingeladen",
+  },
+  "waitlist:entity:waitlistEntry:field:status:option:rejected": {
+    en: "Rejected",
+    de: "Abgelehnt",
+  },
+  "waitlist.action.invite": { en: "Invite", de: "Einladen" },
+  "waitlist.action.reInvite": { en: "Re-invite", de: "Erneut einladen" },
+  "waitlist.action.reject": { en: "Reject", de: "Ablehnen" },
+  "waitlist.action.reject.confirm": {
+    en: "Reject this entry? The data stays stored.",
+    de: "Eintrag ablehnen? Die Daten bleiben gespeichert.",
+  },
+};

package/packages/bundled-features/src/waitlist/index.ts

@@ -0,0 +1,15 @@
+export {
+  DEFAULT_OWN_TENANT_INVITE_ROLE,
+  WAITLIST_FEATURE,
+  WAITLIST_FIELD_LIMITS,
+  WAITLIST_NOTIFICATION_TYPES,
+  WAITLIST_STATUS,
+  WaitlistErrors,
+  WaitlistHandlers,
+  WaitlistQueries,
+  type WaitlistStatus,
+} from "./constants.js";
+export { isOpenWaitlistStatus, waitlistEntryEntity, waitlistEntryTable } from "./entity.js";
+export { createWaitlistFeature } from "./feature.js";
+export type { WaitlistInviteOptions, WaitlistOptions } from "./options.js";
+export { type WaitlistSubmitInput, WaitlistSubmitSchema } from "./payloads.js";

package/packages/bundled-features/src/waitlist/lib.ts

@@ -0,0 +1,36 @@
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createSystemUser,
+  type HandlerContext,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { waitlistEntryEntity, waitlistEntryTable } from "./entity.js";
+
+export const WAITLIST_CROSS_TENANT_REASON = "waitlist is platform-wide (systemScope)";
+
+export const adminAccess = { roles: access.systemAdmin } as const;
+
+export const waitlistExecutor = createEventStoreExecutor(waitlistEntryTable, waitlistEntryEntity, {
+  entityName: "waitlistEntry",
+});
+
+export function normalizeEmail(email: string): string {
+  return email.toLowerCase();
+}
+
+export function waitlistDb(ctx: HandlerContext): TenantDb {
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message: "waitlist requires ctx.systemDb — is r.systemScope() set on the feature?",
+    });
+  }
+  return ctx.systemDb.acknowledgeCrossTenant(WAITLIST_CROSS_TENANT_REASON);
+}
+
+// Entries are systemStream rows, so every write targets the system tenant's stream.
+export function platformActor(): SessionUser {
+  return createSystemUser(SYSTEM_TENANT_ID);
+}