@cosmicdrift/kumiko-samples 0.340.0 → 0.341.0

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

@@ -0,0 +1,114 @@
+import type { AuthMailContent } from "../auth-email-password/index.js";
+
+export type WaitlistMailLocale = "en" | "de" | "es";
+
+type ConfirmationStrings = {
+  readonly subject: (app: string | undefined) => string;
+  readonly header: string;
+  readonly intro: (app: string | undefined) => string;
+  readonly footer: (app: string | undefined) => string;
+};
+
+const CONFIRMATION_STRINGS: Readonly<Record<WaitlistMailLocale, ConfirmationStrings>> = {
+  en: {
+    subject: (app) => (app ? `You're on the ${app} waitlist` : "You're on the waitlist"),
+    header: "Waitlist confirmed",
+    intro: (app) =>
+      `Hi, we received your request${app ? ` for ${app}` : ""} and look at it personally. We'll email you when you can get started.`,
+    footer: (app) => `If you didn't ask to join${app ? ` ${app}` : ""}, you can ignore this email.`,
+  },
+  de: {
+    subject: (app) =>
+      app ? `Du stehst auf der ${app}-Warteliste` : "Du stehst auf der Warteliste",
+    header: "Warteliste bestätigt",
+    intro: (app) =>
+      `Hallo, wir haben deine Anfrage${app ? ` für ${app}` : ""} erhalten und schauen sie uns persönlich an. Wir melden uns per E-Mail, sobald du loslegen kannst.`,
+    footer: (app) =>
+      `Falls du dich nicht${app ? ` für ${app}` : ""} angemeldet hast, kannst du diese E-Mail ignorieren.`,
+  },
+  es: {
+    subject: (app) =>
+      app ? `Estás en la lista de espera de ${app}` : "Estás en la lista de espera",
+    header: "Lista de espera confirmada",
+    intro: (app) =>
+      `Hola, hemos recibido tu solicitud${app ? ` para ${app}` : ""} y la revisamos personalmente. Te avisaremos por correo cuando puedas empezar.`,
+    footer: (app) =>
+      `Si no solicitaste unirte${app ? ` a ${app}` : ""}, puedes ignorar este correo.`,
+  },
+};
+
+type AdminNoticeStrings = {
+  readonly subject: (name: string) => string;
+  readonly header: string;
+  readonly intro: string;
+  readonly footer: string;
+};
+
+const ADMIN_NOTICE_STRINGS: Readonly<Record<"en" | "de", AdminNoticeStrings>> = {
+  en: {
+    subject: (name) => `New waitlist entry: ${name}`,
+    header: "New waitlist entry",
+    intro: "Someone just joined the waitlist.",
+    footer: "Review the entry in the admin waitlist screen.",
+  },
+  de: {
+    subject: (name) => `Neuer Wartelisten-Eintrag: ${name}`,
+    header: "Neuer Wartelisten-Eintrag",
+    intro: "Jemand hat sich gerade auf die Warteliste eingetragen.",
+    footer: "Den Eintrag findest du in der Wartelisten-Verwaltung.",
+  },
+};
+
+function languageOf(locale: string | undefined): string {
+  return (locale ?? "").split("-")[0]?.toLowerCase() ?? "";
+}
+
+function isConfirmationLocale(language: string): language is WaitlistMailLocale {
+  return language === "en" || language === "de" || language === "es";
+}
+
+export function resolveWaitlistMailLocale(locale: string | undefined): WaitlistMailLocale {
+  const language = languageOf(locale);
+  return isConfirmationLocale(language) ? language : "en";
+}
+
+// The submitter's name stays out: the address is unverified, so any text in
+// this mail could be planted by whoever typed someone else's email.
+export function renderWaitlistConfirmationEmail(args: {
+  readonly locale: string | undefined;
+  readonly appName?: string | undefined;
+}): AuthMailContent {
+  const t = CONFIRMATION_STRINGS[resolveWaitlistMailLocale(args.locale)];
+  return {
+    subject: t.subject(args.appName),
+    header: t.header,
+    sections: [{ text: t.intro(args.appName) }],
+    footer: t.footer(args.appName),
+  };
+}
+
+// Operator-facing, so the entrant's locale does not apply: en/de, en default.
+export function resolveWaitlistAdminMailLocale(adminLocale: string | undefined): "en" | "de" {
+  return languageOf(adminLocale) === "de" ? "de" : "en";
+}
+
+export function renderWaitlistAdminNoticeEmail(args: {
+  readonly name: string;
+  readonly email: string;
+  readonly company: string | undefined;
+  readonly message: string | undefined;
+  readonly adminLocale: string | undefined;
+}): AuthMailContent {
+  const t = ADMIN_NOTICE_STRINGS[resolveWaitlistAdminMailLocale(args.adminLocale)];
+  const details = [
+    `${args.name} <${args.email}>`,
+    ...(args.company ? [args.company] : []),
+    ...(args.message ? [args.message] : []),
+  ];
+  return {
+    subject: t.subject(args.name),
+    header: t.header,
+    sections: [{ text: t.intro }, { text: details.join("\n") }],
+    footer: t.footer,
+  };
+}

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/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`.