@cosmicdrift/kumiko-samples 0.339.0 → 0.341.0

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

@@ -0,0 +1,41 @@
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { PayloadRateLimitOption, RateLimitOption } from "@cosmicdrift/kumiko-types/handlers";
+
+export type WaitlistInviteOptions =
+  | {
+      /** Each invited entry gets its own tenant, named after company or name. */
+      readonly mode: "own-tenant";
+      /** Membership role in the new tenant. Default "TenantAdmin". */
+      readonly role?: string;
+    }
+  | {
+      /** Every invited entry joins one existing tenant. */
+      readonly mode: "shared-tenant";
+      readonly tenantId: TenantId;
+      readonly role: string;
+    };
+
+export type WaitlistOptions = {
+  /** Address for an admin notification mail on each new entry. Null, an empty
+   *  string or an absent option sends none. Best effort, never fails the submit. */
+  readonly notifyRecipient?: (ctx: HandlerContext) => string | null;
+  /** Default `{ mode: "own-tenant", role: "TenantAdmin" }`. */
+  readonly invite?: WaitlistInviteOptions;
+  /** Default: 5 submits per IP per 10 minutes. */
+  readonly rateLimit?: RateLimitOption;
+  /** Default: 3 submits per email address per day, across all IPs. Stops a botnet
+   *  from flooding one address with confirmation mails. Pass `[]` to disable. */
+  readonly emailRateLimits?: readonly PayloadRateLimitOption[];
+  /** Shown in the confirmation mail; omitted when unset. */
+  readonly appName?: string;
+};
+
+export const DEFAULT_SUBMIT_RATE_LIMIT: RateLimitOption = {
+  per: "ip+handler",
+  limit: 5,
+  windowSeconds: 10 * 60,
+};
+
+export const DEFAULT_SUBMIT_EMAIL_RATE_LIMITS: readonly PayloadRateLimitOption[] = [
+  { per: { payloadField: "email" }, limit: 3, windowSeconds: 24 * 60 * 60 },
+];

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

@@ -0,0 +1,55 @@
+import { canonicalizeLocaleTag, isValidLocaleTag } from "@cosmicdrift/kumiko-framework/i18n";
+import * as z from "zod";
+import { WAITLIST_FIELD_LIMITS } from "./constants.js";
+
+// Submitted text lands in a mail subject; CR/LF there would allow header injection.
+const NO_CONTROL_CHARS = /^\P{Cc}*$/u;
+const NO_CONTROL_CHARS_EXCEPT_WHITESPACE = /^(?:[^\p{Cc}]|[\n\r\t])*$/u;
+const noControlChars = (value: string) => NO_CONTROL_CHARS.test(value);
+
+export const WaitlistSubmitSchema = z
+  .object({
+    name: z
+      .string()
+      .trim()
+      .min(1)
+      .max(WAITLIST_FIELD_LIMITS.name)
+      .refine(noControlChars, "control characters not allowed"),
+    email: z.email().max(WAITLIST_FIELD_LIMITS.email),
+    company: z
+      .string()
+      .trim()
+      .min(1)
+      .max(WAITLIST_FIELD_LIMITS.company)
+      .refine(noControlChars, "control characters not allowed")
+      .optional(),
+    portfolio: z
+      .string()
+      .trim()
+      .min(1)
+      .max(WAITLIST_FIELD_LIMITS.portfolio)
+      .refine(noControlChars, "control characters not allowed")
+      .optional(),
+    message: z
+      .string()
+      .trim()
+      .min(1)
+      .max(WAITLIST_FIELD_LIMITS.message)
+      .refine(
+        (value) => NO_CONTROL_CHARS_EXCEPT_WHITESPACE.test(value),
+        "control characters not allowed",
+      )
+      .optional(),
+    locale: z
+      .string()
+      .max(WAITLIST_FIELD_LIMITS.locale)
+      .refine(isValidLocaleTag, "invalid locale tag")
+      .transform(canonicalizeLocaleTag),
+    // Honeypot: bots fill it, humans leave it empty.
+    website: z.string().max(WAITLIST_FIELD_LIMITS.honeypot).optional(),
+  })
+  .strict();
+
+export type WaitlistSubmitInput = z.infer<typeof WaitlistSubmitSchema>;
+
+export const WaitlistIdSchema = z.object({ id: z.uuid() }).strict();

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

@@ -0,0 +1,43 @@
+import { type EntityListScreenDefinition, i18nKey } from "@cosmicdrift/kumiko-framework/engine";
+import { WAITLIST_STATUS, WaitlistHandlers } from "./constants.js";
+import { adminAccess } from "./lib.js";
+
+export const waitlistListScreen: EntityListScreenDefinition = {
+  id: "waitlist-list",
+  type: "entityList",
+  entity: "waitlistEntry",
+  columns: ["name", "email", "company", "status", "locale", "submittedAt"],
+  defaultSort: { field: "submittedAt", dir: "desc" },
+  access: adminAccess,
+  searchable: true,
+  rowActions: [
+    {
+      id: "invite",
+      label: i18nKey("waitlist.action.invite"),
+      handler: WaitlistHandlers.invite,
+      visible: { field: "status", eq: WAITLIST_STATUS.Pending },
+    },
+    {
+      id: "re-invite",
+      label: i18nKey("waitlist.action.reInvite"),
+      handler: WaitlistHandlers.invite,
+      visible: { field: "status", eq: WAITLIST_STATUS.Invited },
+    },
+    {
+      id: "reject",
+      label: i18nKey("waitlist.action.reject"),
+      handler: WaitlistHandlers.reject,
+      confirm: i18nKey("waitlist.action.reject.confirm"),
+      style: "danger",
+      visible: { field: "status", eq: WAITLIST_STATUS.Pending },
+    },
+    {
+      id: "reject-invited",
+      label: i18nKey("waitlist.action.reject"),
+      handler: WaitlistHandlers.reject,
+      confirm: i18nKey("waitlist.action.reject.confirm"),
+      style: "danger",
+      visible: { field: "status", eq: WAITLIST_STATUS.Invited },
+    },
+  ],
+};

package/packages/bundled-features/src/waitlist/user-data-hooks.ts

@@ -0,0 +1,82 @@
+import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
+import type {
+  UserDataDeleteHook,
+  UserDataExportHook,
+  UserDataHookCtx,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { collectErasureFailure, decryptStoredPii, throwIfErasureFailed } from "../shared/index.js";
+import { userTable } from "../user/index.js";
+import { normalizeEmail, platformActor, waitlistExecutor } from "./lib.js";
+
+const PII_DECRYPT_REASON = "waitlist:user-data";
+const ERASE_REASON = "waitlist:user-data-forget";
+const ENTRY_LOOKUP_LIMIT = 100;
+
+// Entries are matched by email, so the user must have proven they own it:
+// otherwise registering with someone else's address would expose or erase that
+// person's entries. The forget anonymization leaves emailVerified untouched,
+// so the live row stays a reliable source; only the email needs the pre-tx
+// copy because the user hook has already rewritten it by now.
+async function resolveVerifiedUserEmail(ctx: UserDataHookCtx): Promise<string | null> {
+  const row = await ctx.db.fetchOne<{ email: string; emailVerified: boolean }>(userTable, {
+    id: ctx.userId,
+  });
+  if (row?.emailVerified !== true) return null;
+  if (ctx.userEmailBeforeDelete) return normalizeEmail(ctx.userEmailBeforeDelete);
+  return normalizeEmail(await decryptStoredPii(row.email, "email", PII_DECRYPT_REASON));
+}
+
+// Entries are decrypted by the executor's list (subject-encrypted name/email/message).
+async function findEntriesByEmail(ctx: UserDataHookCtx, email: string) {
+  const found = await waitlistExecutor.list(
+    { filter: { field: "email", op: "eq", value: email }, limit: ENTRY_LOOKUP_LIMIT },
+    platformActor(),
+    ctx.db,
+  );
+  return found.rows;
+}
+
+export const waitlistEntryExportHook: UserDataExportHook = async (ctx) => {
+  const email = await resolveVerifiedUserEmail(ctx);
+  // skip: unverified or missing email must not be matched against waitlist entries
+  if (!email) return null;
+  const rows = await findEntriesByEmail(ctx, email);
+  if (rows.length === 0) return null;
+  return {
+    entity: "waitlistEntry",
+    rows: rows.map((row) => ({
+      name: row["name"],
+      email: row["email"],
+      company: row["company"],
+      portfolio: row["portfolio"],
+      message: row["message"],
+      locale: row["locale"],
+      status: row["status"],
+      submittedAt: String(row["submittedAt"] ?? ""),
+    })),
+  };
+};
+
+// Waitlist entries carry no retention duty, so both strategies erase: the row
+// is purged through the executor (replays on rebuild) and its record subject
+// key is shredded so the event log's ciphertext becomes unreadable.
+export const waitlistEntryDeleteHook: UserDataDeleteHook = async (ctx) => {
+  const email = await resolveVerifiedUserEmail(ctx);
+  // skip: unverified or missing email must not be matched against waitlist entries
+  if (!email) return;
+  const kms = configuredPiiSubjectKms();
+  const failures: string[] = [];
+  for (const row of await findEntriesByEmail(ctx, email)) {
+    const id = row["id"];
+    if (typeof id !== "string") continue;
+    const forgotten = await waitlistExecutor.forget({ id }, platformActor(), ctx.db);
+    collectErasureFailure(forgotten, "waitlistEntry", id, failures);
+    if (forgotten.isSuccess && kms) {
+      await kms.eraseKey(
+        { kind: "record", entity: "waitlistEntry", id },
+        { requestId: ERASE_REASON, userId: ctx.userId, eraseReason: ERASE_REASON },
+      );
+    }
+  }
+  throwIfErasureFailed(failures);
+};

package/packages/bundled-features/src/workflow-runner/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "The resume job reads due runs through the job's TenantDb",
+    "detail": "`selectDueWorkflowRunPending` takes a `TenantDb` and returns `{ runId, stepIndex }` rows, so the tenant filter comes from the TenantDb instead of a hand-written `WHERE tenant_id`.",
+    "migration": "keine"
+  },
   {
     "version": "0.339.0",
     "type": "breaking",

package/packages/bundled-features/src/workflow-runner/db/queries/due-runs.ts

@@ -1,8 +1,7 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { sql, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { workflowRunPendingTable } from "../../tables.js";
 
-export type DueRow = { readonly run_id: string; readonly step_index: number };
+export type DueRow = { readonly runId: string; readonly stepIndex: number };
 
 // Oldest first and capped, so a backlog after an outage drains over several
 // ticks instead of holding one tick's `concurrency: "skip"` slot for minutes.
@@ -12,13 +11,11 @@ export const DUE_RUNS_BATCH_SIZE = 100;
 // (ctx.tryAppendEvent on WORKFLOW_RESUMED) — a second dispatch for the same
 // row loses that race and no-ops. No row locks: in an autocommit statement
 // they would be released right after the SELECT and guard nothing.
-export async function selectDueWorkflowRunPending(
-  db: DbConnection,
-  tenantId: TenantId,
-): Promise<readonly DueRow[]> {
-  // kumiko-lint-ignore raw-sql tenant-scoped due-row pickup
-  return (await asRawClient(db).unsafe(
-    `SELECT run_id, step_index FROM workflow_run_pending WHERE tenant_id = $1 AND wake_at < now() ORDER BY wake_at ASC LIMIT ${DUE_RUNS_BATCH_SIZE}`,
-    [tenantId],
-  )) as readonly DueRow[];
+// `now()` stays the DB clock so job-host clock skew cannot mark rows due early.
+export function selectDueWorkflowRunPending(db: TenantDb): Promise<readonly DueRow[]> {
+  return db.selectMany<DueRow>(
+    workflowRunPendingTable,
+    { wakeAt: { lt: sql`now()` } },
+    { orderBy: { col: "wakeAt", direction: "asc" }, limit: DUE_RUNS_BATCH_SIZE },
+  );
 }

package/packages/bundled-features/src/workflow-runner/feature.ts

@@ -24,7 +24,6 @@
 //
 // wait/retry/waitForEvent suspensions all resume automatically now.
 
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { selectDueWorkflowRunPending } from "./db/queries/due-runs.js";
 import { resumeRunHandler } from "./handlers/resume-run.write.js";
@@ -68,26 +67,20 @@ export const workflowRunnerFeature = defineFeature(FEATURE_NAME, (r) => {
         return;
       }
 
-      ctx.systemDb.assertTenantMatch(tenantId);
-      const dueRows = await selectDueWorkflowRunPending(
-        ctx.systemDb.unsafeRaw(
-          "due-row pickup needs FOR UPDATE SKIP LOCKED raw SQL; the query filters by this job's tenantId",
-        ) as DbConnection, // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
-        tenantId,
-      );
+      const dueRows = await selectDueWorkflowRunPending(ctx.systemDb.assertTenantMatch(tenantId));
 
       for (const row of dueRows) {
         try {
           await ctx.write("workflow-runner:write:resume-run", {
-            runId: row.run_id,
-            stepIndex: row.step_index,
+            runId: row.runId,
+            stepIndex: row.stepIndex,
           });
         } catch (error) {
           // skip: one row's dispatch failing (infra hiccup, not a business
           // outcome — resume-run itself never throws for expected cases)
           // must not stop the rest of this tenant's due rows from resuming.
           ctx.log.warn(
-            `[workflow-runner:resume-due-runs] runId=${row.run_id} stepIndex=${row.step_index} dispatch failed: ${String(error)}`,
+            `[workflow-runner:resume-due-runs] runId=${row.runId} stepIndex=${row.stepIndex} dispatch failed: ${String(error)}`,
           );
         }
       }

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 80,
+  "featureCount": 81,
   "features": [
     {
       "name": "admin-shell",
@@ -102,6 +102,7 @@
         "auth-email-password:write:reset-password",
         "auth-email-password:write:signup-confirm",
         "auth-email-password:write:signup-request",
+        "auth-email-password:write:system-invite-create",
         "auth-email-password:write:verify-email"
       ],
       "uiHints": {
@@ -193,9 +194,7 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "Admin",
-            "SystemAdmin"
+            "system"
           ],
           "readRoles": [
             "all"
@@ -516,7 +515,7 @@
     },
     {
       "name": "channel-telegram",
-      "description": "Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: \"<chat id or @channel>\" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL and request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.",
+      "description": "Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: \"<chat id or @channel>\" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL, its host allowlist (`allowedHosts`, default `api.telegram.org`), `requireHttps` (default true; boot fails on a mismatch) and the request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.",
       "toggleableDefault": null,
       "requires": [
         "delivery",
@@ -3053,6 +3052,38 @@
         "recommended": true
       }
     },
+    {
+      "name": "waitlist",
+      "description": "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.",
+      "toggleableDefault": null,
+      "requires": [
+        "tenant",
+        "auth-email-password",
+        "user-data-rights"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "userData",
+          "entityName": "waitlistEntry"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [
+        "waitlist:write:invite",
+        "waitlist:write:reject",
+        "waitlist:write:submit"
+      ],
+      "uiHints": {
+        "displayLabel": "Waitlist",
+        "category": "data",
+        "recommended": false
+      }
+    },
     {
       "name": "workflow-runner",
       "description": "Writes the run-envelope (`workflow.run-started` / `workflow.run-completed` / `workflow.run-failed`) for a workflow run onto its `workflow-run` aggregate stream. Provides `startAndRunWorkflow` and `registerEventTrigger` for consumer features to wire up `defineWorkflow`-based workflows against domain events. Registers no workflows itself. Runs the resume loop for suspended `wait`/`retry`/`waitForEvent` steps (`resume-due-runs` job + `resume-run` handler); `registerEventTrigger` wires an event-wakeup subscriber per workflow that declares `awaits` so a `waitForEvent` step resumes as soon as its awaited event arrives, not just on timeout.",

package/samples/apps/use-all-bundled/kumiko/migrations/0033_waitlist.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_waitlist_entries"]
+}

package/samples/apps/use-all-bundled/schema/generate.ts

@@ -284,6 +284,11 @@ const FEATURE_IMPORT_REGISTRY: Record<string, FeatureImport> = {
     path: "@cosmicdrift/kumiko-bundled-features/legal-pages",
     factory: "createLegalPagesFeature",
   },
+  waitlist: {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-bundled-features/waitlist",
+    factory: "createWaitlistFeature",
+  },
   "managed-pages": {
     kind: "factory",
     path: "@cosmicdrift/kumiko-bundled-features/managed-pages",

package/samples/apps/use-all-bundled/schema/schema.generated.ts

@@ -17,6 +17,7 @@ import { capCounterFeature } from "@cosmicdrift/kumiko-bundled-features/cap-coun
 import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
 import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
 import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import { createWaitlistFeature } from "@cosmicdrift/kumiko-bundled-features/waitlist";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import { createManagedPagesFeature } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 import { customFieldsFeature } from "@cosmicdrift/kumiko-bundled-features/custom-fields";
@@ -39,6 +40,7 @@ const _capCounter = capCounterFeature;
 const _complianceProfiles = createComplianceProfilesFeature();
 const _dataRetention = createDataRetentionFeature();
 const _userDataRights = createUserDataRightsFeature();
+const _waitlist = createWaitlistFeature();
 const _templateResolver = createTemplateResolverFeature();
 const _managedPages = createManagedPagesFeature({ resolveApexTenant: () => null, allowCustomCss: true });
 const _customFields = customFieldsFeature;
@@ -66,6 +68,7 @@ export const tenantRetentionOverrideTable = buildEntityTable("tenant-retention-o
 export const exportJobTable = buildEntityTable("export-job", _userDataRights.entities["export-job"]!);
 export const exportDownloadTokenTable = buildEntityTable("export-download-token", _userDataRights.entities["export-download-token"]!);
 export const downloadAttemptTable = buildEntityTable("download-attempt", _userDataRights.entities["download-attempt"]!);
+export const waitlistEntryTable = buildEntityTable("waitlistEntry", _waitlist.entities["waitlistEntry"]!);
 export const templateResourceTable = buildEntityTable("template-resource", _templateResolver.entities["template-resource"]!);
 export const userContentEntryTable = buildEntityTable("user-content-entry", _templateResolver.entities["user-content-entry"]!);
 export const pageTable = buildEntityTable("page", _managedPages.entities["page"]!);

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -92,6 +92,7 @@ import { tierEngineFeature } from "@cosmicdrift/kumiko-bundled-features/tier-eng
 import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
 import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights-defaults";
 import { createUserProfileFeature } from "@cosmicdrift/kumiko-bundled-features/user-profile";
+import { createWaitlistFeature } from "@cosmicdrift/kumiko-bundled-features/waitlist";
 import { workflowRunnerFeature } from "@cosmicdrift/kumiko-bundled-features/workflow-runner";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
@@ -288,6 +289,7 @@ export const APP_FEATURES = [
 
   // CMS / content
   createLegalPagesFeature(),
+  createWaitlistFeature(),
   createTemplateResolverFeature({
     // One collection per ownership mode so the smoke app exercises both paths:
     // a shared set an admin curates, and a per-user set every agent keeps.

package/samples/recipes/chat-channels/README.md

@@ -10,6 +10,8 @@ Shows how a feature posts to a tenant's Slack channel without ever handling the
 
 **App-level hardening:** Each channel only talks to its provider's hosts, over https, without following redirects. `allowedHosts`, `requireHttps` and `timeoutMs` are options of `createChannelSlackFeature(opts)`. Tenants cannot change them; the test uses them to point at a local stub.
 
+**Production boot:** `runProdApp`, `runDevApp` and `runWorkerApp` wire `ctx.notify` and the tenant secrets for you, so no app wiring is needed. Queued channels run through the `delivery.render`/`delivery.send` jobs on the worker lane (all-in-one by default); a "send test message" handler can pass `immediate: true` to `ctx.notify` to deliver inline and read `sent`/`failed` from the returned `deliveries`.
+
 The same shape works for `channel-discord`, `channel-teams` (connection name + webhook secret) and `channel-telegram` (one `botToken` secret, the address is the chat id).
 
 ## Run

package/samples/recipes/managed-config/README.md

@@ -74,7 +74,7 @@ await runProdApp({
     _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
     // Required whenever a key declares backing:"secrets" — without it the set
     // and read paths fail loud, never silently miss.
-    secrets: createSecretsContext({ db, masterKeyProvider }),
+    secrets: createSecretsContext({ db, masterKeyProvider, registry }),
   }),
   // ...
 });

package/samples/recipes/rate-limiting/README.md

@@ -7,6 +7,27 @@ End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.
 - Handler `rateLimit: { per, limit, windowSeconds }`
 - How L1/L2 from `buildServer` stack with L3
 
+## Per-payload limits
+
+A public write handler that mails an address typed by the caller is also limited per
+address, so rotating IPs does not help against mail flooding. Declare it next to `rateLimit`:
+
+```ts
+r.writeHandler({
+  // ...
+  access: { roles: ["anonymous"] },
+  rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
+  additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
+});
+```
+
+`additionalRateLimits` only complements `rateLimit`: an anonymous handler still needs a real,
+ip-keyed `rateLimit` (boot fails otherwise), and `payloadField` must be a top-level string field
+of the handler's Zod object schema. The value is trimmed, lowercased and HMAC-hashed into the
+bucket key, so Redis never holds the address in plaintext. The check runs after schema
+validation and before the handler, identically for matching and non-matching values, and is
+skipped for system callers. Exceeding it answers 429 `rate_limited`.
+
 ## Source
 
 Feature entry point: `src/feature.ts`.

package/packages/bundled-features/src/billing-foundation/db/queries/payment-projection.ts

@@ -1,19 +0,0 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-
-// INSERT-once, not UPSERT: unlike subscriptionsProjectionTable (one row per
-// tenant, state overwritten on every event), a payment row is an immutable
-// fact keyed by paymentRowId(tenantId, providerName, providerEventId) — ON
-// CONFLICT DO NOTHING makes a projection rebuild/replay idempotent without
-// ever mutating an existing row.
-export async function insertPaymentProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
-  // kumiko-lint-ignore raw-sql tableName + column keys are code-controlled, not user input: tableName is buildEntityTable()'s static table name and insertKeys come from applyPaymentReceived's hardcoded object-literal columns in projection.ts — only values flow through $1..$n
-  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
-}

package/packages/bundled-features/src/billing-foundation/db/queries/subscription-projection.ts

@@ -1,15 +0,0 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-
-export async function upsertSubscriptionProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-  setClauses: readonly string[],
-  params: readonly unknown[],
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO UPDATE SET ${setClauses.join(", ")}`;
-  await asRawClient(tx).unsafe(sqlText, params);
-}

package/packages/bundled-features/src/inbound-mail-foundation/db/queries/inbound-projections.ts

@@ -1,38 +0,0 @@
-// Raw-SQL-Helper für die inline projections — Muster
-// billing-foundation/db/queries/subscription-projection.ts.
-//
-// Warum raw statt drizzle-insert: die apply-fns laufen in der event-TX
-// mit einem DbRunner, und die ON-CONFLICT-Semantik (UPSERT vs.
-// DO NOTHING) ist der fachliche Kern — explizit hingeschrieben statt
-// hinter einem ORM-Builder versteckt.
-
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-
-/** INSERT ... ON CONFLICT ("id") DO UPDATE SET <setClauses>. */
-export async function upsertProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-  setClauses: readonly string[],
-  params: readonly unknown[],
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO UPDATE SET ${setClauses.join(", ")}`;
-  await asRawClient(tx).unsafe(sqlText, params);
-}
-
-/** INSERT ... ON CONFLICT ("id") DO NOTHING — für append-only-Rows
- *  (inbound-message: genau EIN received-event pro Stream, Replays
- *  no-op'en auf der PK). */
-export async function insertIgnoreProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
-  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
-}