@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/data-retention/run-retention-cleanup.js

@@ -1,46 +1,46 @@
-// Retention-Cleanup-Runner (S2.D2b) — pure Function, vom retention-cleanup-Cron
-// pro fan-out-Tenant aufgerufen.
+// Retention-Cleanup-Runner — pure function, called by the retention-cleanup cron
+// for each fan-out tenant.
 //
-// Iteriert alle implicit-Entity-Projektionen, loest pro Entity die effektive
-// Retention-Policy (3-Schicht-Resolver, siehe resolver.ts) und wendet die
-// Strategy auf Rows an deren reference-Timestamp aelter als der keepFor-Cutoff
-// ist:
+// Iterates all implicit entity projections, resolves the effective retention
+// policy per entity (3-layer resolver, see resolver.ts), and applies the
+// strategy to rows whose reference timestamp is older than the keepFor cutoff:
 //
-//   - hardDelete  → executor.forget pro Row (Event → rebuild-safe hard purge).
+//   - hardDelete  → executor.forget per row (event → rebuild-safe hard purge).
 //                   Entities with file/image/files/images fields: bytes first
 //                   (incl. derivatives), then the fileRef row(s), then the row;
 //                   shared fileRefs (other owner, other row of the same table)
 //                   stay untouched.
-//   - softDelete  → executor.delete pro Row (Event → rebuild-safe soft-delete),
-//                   nur auf noch-nicht-geloeschte (isDeleted:false-Filter)
-//   - anonymize   → executor.update pro Row mit den Werten der per-Feld
-//                   anonymize-Funktionen; Row bleibt (fields.ts-Contract)
-//   - blockDelete → waehrend keepFor unangetastet (Aufbewahrungs-Pflicht;
-//                   user-forget loest anonymize aus). NACH Ablauf laufen die
-//                   anonymize-Funktionen — Geschaeftsdaten bleiben, Personen-
-//                   Bezug raus (fields.ts:44-47).
+//   - softDelete  → executor.delete per row (event → rebuild-safe soft-delete),
+//                   only on not-yet-deleted rows (isDeleted:false filter)
+//   - anonymize   → executor.update per row with the values of the per-field
+//                   anonymize functions; row remains (fields.ts contract)
+//   - blockDelete → untouched during keepFor (retention requirement;
+//                   user-forget triggers anonymize). AFTER expiration, the
+//                   anonymize functions run — business data remains, the person-
+//                   identifying link is removed (fields.ts:44-47).
 //
-// Über den Executor statt Batch-deleteMany/updateMany: ein eventloser Batch-Write
-// auf die (erased) Projektions-Tabelle wird beim Projection-Rebuild
-// gewischt/resurrektiert — das #648-Loch. Kosten: N Events pro Cleanup statt ein
-// Batch-Statement (per-Row-Ceiling, Batch-Event-Variante als Follow-up).
+// Via the executor instead of batch-deleteMany/updateMany: an eventless batch write
+// to the (erased) projection table is wiped/resurrected during a projection rebuild.
+// Cost: N events per cleanup instead of one batch statement (per-row ceiling, with
+// a batch-event variant later).
 //
-// **Schaerfer als soft-delete-cleanup:** dieser Cron hardDeleted LIVE Rows
-// (keyed auf reference, Default createdAt), nicht bereits-soft-geloeschte.
-// Darum die Spalten-Existenz-Pruefung vor jedem WHERE — eine fehlende/vertippte
-// reference-Spalte wuerde sonst ein malformed/all-matching WHERE ergeben und
-// pauschal loeschen.
+// **Stricter than soft-delete-cleanup:** this cron hard-deletes LIVE rows
+// (keyed on reference, default createdAt), not already-soft-deleted ones.
+// Therefore the column-existence check comes before every WHERE — a missing/mistyped
+// reference column would otherwise produce a malformed/all-matching WHERE and
+// delete everything.
 //
-// **anonymize-Idempotenz ohne Marker-Spalte:** die anonymize-Funktionen sind
-// row-unabhaengig (`() => unknown`) — einmal pro Entity ausgewertet ergeben
-// sie die Ziel-Werte. Eine Row die sie schon traegt wird uebersprungen, der
-// taegliche Re-Lauf appended also null Events. Der WHERE matcht anonymisierte
-// Rows weiter (reference bleibt alt), deshalb id-Cursor-Paging statt einer
-// einzelnen Page — sonst verstopfen erledigte Rows das batchLimit-Fenster.
+// **anonymize idempotence without a marker column:** the anonymize functions are
+// row-independent (`() => unknown`) — evaluated once per entity, they produce
+// the target values. A row that already carries them is skipped, so the
+// daily rerun appends zero events. The WHERE continues to match anonymized
+// rows (reference remains old), hence id-cursor paging instead of a single
+// page — otherwise completed rows clog the batchLimit window.
 import { collectPiiSubjectFields, configuredPiiSubjectKms, isRecordKeyedField, isSelfPiiField, resolveSubjectForField, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEventStoreExecutor, createTenantDb, nullBlindIndexesForSubject, selectMany, WritePurposes, } from "@cosmicdrift/kumiko-framework/db";
 import { deleteFileRefBytes } from "@cosmicdrift/kumiko-framework/derivatives";
 import { createSystemUser, entityHasAnonymizableSubjectField, } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { fileRefEntity, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { collectSingleFileHolders, planFileFields, purgeRowFileRefs, runInSubTransaction, } from "../shared/index.js";
@@ -49,13 +49,13 @@ import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.js";
 import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override.js";
 const DEFAULT_BATCH_LIMIT = 1000;
 const DEFAULT_REFERENCE_FIELD = "createdAt";
-// Der Boot-Validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
-// erlaubt diese Aliase als retention.reference, auch wenn sie nicht in
-// entity.fields deklariert sind — die physischen Spalten heissen aber anders
-// (table-builder.ts: inserted_at/modified_at). Hier zur Cleanup-Zeit auf das
-// echte Entity-Feld mappen, sonst trifft die Spalten-Existenz-Pruefung unten
-// und der Cron wuerde lautlos nichts tun. deletedAt/lastSeenAt sind echte
-// Felder (softDelete bzw. session) und brauchen keine Uebersetzung.
+// The boot validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
+// permits these aliases as retention.reference even when they are not declared in
+// entity.fields, but the physical columns use different names
+// (table-builder.ts: inserted_at/modified_at). Map them to the actual entity field
+// during cleanup; otherwise the column existence check below would cause the cron
+// to do nothing silently. deletedAt/lastSeenAt are real fields (softDelete and
+// session respectively) and need no translation.
 const FRAMEWORK_REFERENCE_ALIAS = {
     createdAt: "insertedAt",
     updatedAt: "modifiedAt",
@@ -72,7 +72,7 @@ async function purgeMatchingRows(db, table, where, batchLimit, op) {
     }
     return count;
 }
-// --- hardDelete crypto-shredding (Refs #2057) ---
+// --- hardDelete crypto-shredding ---
 //
 // recordOwned/self-pii resolution (subject-resolver.ts) only ever reads
 // `row.id` for these two kinds — resolveRecordSubject uses opts.entityName +
@@ -137,7 +137,7 @@ async function eraseHardDeletedRowKeys(args) {
 async function forgetRowAndEraseKeys(args) {
     return runInSubTransaction(args.db, async (sp) => {
         const tdb = createTenantDb({ db: sp, tenantId: args.tenantId, mode: "system" });
-        const result = await args.executor.forget({ id: args.row["id"] }, args.systemUser, tdb);
+        const result = await args.executor.forget({ id: args.rowId }, args.systemUser, tdb);
         if (!result.isSuccess)
             return { isSuccess: false };
         await eraseHardDeletedRowKeys({
@@ -152,7 +152,7 @@ async function forgetRowAndEraseKeys(args) {
         return { isSuccess: true };
     });
 }
-// --- hardDelete + file-fields (kumiko-framework#3089) ---
+// --- hardDelete + file-fields ---
 // Throws (unsafe key, missing list permission) must fail this row closed,
 // not abort the whole tenant run.
 async function deleteFileFailingClosed(key, files, logContext) {
@@ -169,8 +169,7 @@ async function deleteFileFailingClosed(key, files, logContext) {
 // fields: purge the un-shared fileRefs (bytes + derivatives, then the fileRef
 // rows), then the entity row itself.
 async function purgeHardDeleteRowWithFiles(args) {
-    const rowId = String(args.row["id"]);
-    const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`;
+    const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${String(args.rowId)}`;
     const files = args.files;
     const outcome = await purgeRowFileRefs({
         db: args.db,
@@ -198,6 +197,7 @@ async function purgeHardDeleteRowWithFiles(args) {
         entityName: args.entityName,
         tenantId: args.tenantId,
         systemUser: args.systemUser,
+        rowId: args.rowId,
         row: args.row,
         kms: args.kms,
         registry: args.registry,
@@ -230,7 +230,14 @@ async function purgeHardDeleteRowsWithFiles(args) {
         if (rows.length === 0)
             break;
         for (const row of rows) {
-            cursor = row["id"]; // @cast-boundary db-row
+            const rawId = row["id"];
+            if (typeof rawId !== "string" && typeof rawId !== "number") {
+                throw new InternalError({
+                    message: `data-retention: ${args.entityName} row has no usable id (got ${typeof rawId})`,
+                });
+            }
+            const rowId = rawId;
+            cursor = rowId;
             const ok = await purgeHardDeleteRowWithFiles({
                 db: args.db,
                 table: args.table,
@@ -238,6 +245,7 @@ async function purgeHardDeleteRowsWithFiles(args) {
                 tenantId: args.tenantId,
                 entityName: args.entityName,
                 entity: args.entity,
+                rowId,
                 row,
                 files: args.files,
                 entityExecutor: args.entityExecutor,
@@ -311,9 +319,9 @@ export async function runRetentionCleanup(args) {
     const skipped = [];
     // Retention writes go through the executor (events) so a projection rebuild
     // replays the cleanup — a batch deleteMany/updateMany on the (erased)
-    // projection table is eventless and gets wiped/resurrected on rebuild (the
-    // #648 hole this closes). The cron acts as the system actor; the WHERE already
-    // tenant-scopes, so a system-mode TenantDb (no extra filter) is correct.
+    // projection table is eventless and gets wiped/resurrected on rebuild.
+    // The cron acts as the system actor; the WHERE already tenant-scopes, so a
+    // system-mode TenantDb (no extra filter) is correct.
     // ponytail: per-row events, one batchLimit-sized page per entity per run —
     // the daily cron converges (hardDelete removes rows, softDelete's isDeleted
     // filter shrinks the set). A single batched forget/delete event is a follow-up.
@@ -326,8 +334,9 @@ export async function runRetentionCleanup(args) {
     const overrideRows = await selectMany(db, tenantRetentionOverrideTable, { tenantId });
     const overrideByEntity = new Map(overrideRows.map((r) => [r.entityName, { config: r.config }]));
     for (const proj of registry.getAllProjections().values()) {
-        // Nur implicit-Entity-Projektionen mit Tabelle — wie soft-delete-cleanup.
-        // Custom-Projektionen + unmanaged-Tables (z.B. sessions) sind kein Target.
+        // Only implicit entity projections with a table are targets, as in
+        // soft-delete-cleanup. Custom projections and unmanaged tables (such as
+        // sessions) are excluded.
         if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
             continue;
         const entityName = proj.source;
@@ -353,9 +362,9 @@ export async function runRetentionCleanup(args) {
         }
         const cutoff = computeCutoff(policy.keepFor, now);
         const where = { [referenceField]: { lt: cutoff } };
-        // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
-        // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
-        // anderen treffen.
+        // Apply tenant scoping only when the table has a tenantId column, as in
+        // soft-delete-cleanup. Without this filter, one tenant could affect another
+        // tenant's rows.
         if (propertyOf(proj.table, "tenantId") !== undefined) {
             where["tenantId"] = tenantId;
         }
@@ -371,6 +380,7 @@ export async function runRetentionCleanup(args) {
                         entityName,
                         tenantId,
                         systemUser,
+                        rowId: id,
                         row: { id },
                         kms,
                         registry,

package/dist/data-retention/schema/tenant-retention-override.js

@@ -1,20 +1,22 @@
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createLongTextField, createTextField, } from "@cosmicdrift/kumiko-framework/engine";
-// tenantRetentionOverride — Layer 3 im 3-Schicht-Resolver.
+// tenantRetentionOverride — Layer 3 in the three-layer resolver.
 //
-// Per (tenantId, entityName) eine optionale Override-Config die das
-// Preset (Layer 2) für genau diese eine Entity überschreibt. Use-Cases:
-//   - Anwaltskanzlei in DE: caseFile 6y blockDelete (nicht im Preset)
-//   - Pilot-Tenant der länger speichert für Test
-//   - Branchenspezifische verkürzte Fristen
+// One optional override config per (tenantId, entityName) replaces the
+// preset (Layer 2) for that entity only. Use cases:
+//   - Law firm in DE: caseFile 6y blockDelete (not in the preset)
+//   - Pilot tenant retaining data longer for testing
+//   - Industry-specific shorter retention periods
 //
-// reason ist Pflicht — Audit für DPO + Aufsichtsbehörde nachvollziehbar.
+// reason is required so the decision is auditable by the DPO and supervisory
+// authorities.
 //
-// config ist JSON-String mit `{ keepFor, strategy, reference? }`. Zod-
-// Schema validiert beim set-override-Call (S2.D2 ggf. erweitert).
+// config is a JSON string with `{ keepFor, strategy, reference? }`. The Zod
+// schema validates it when set-override is called.
 //
-// Tenant-1-zu-N: pro Tenant beliebig viele Entity-Overrides. UNIQUE-
-// Index auf (tenantId, entityName) damit pro Entity max ein Override.
+// Tenant one-to-many: each tenant can have any number of entity overrides.
+// A UNIQUE index on (tenantId, entityName) allows at most one override per
+// entity.
 export const tenantRetentionOverrideEntity = createEntity({
     table: "read_tenant_retention_overrides",
     fields: {

package/dist/delivery/channel-context.js

@@ -1,7 +1,7 @@
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { readFileRefContent } from "../file-foundation/index.js";
+import { FileStorageUnavailableError, readFileRefContent, } from "../file-foundation/index.js";
 import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
 import { FALLBACK_LOCALE } from "../template-resolver/index.js";
 export function createTemplateMailRenderer(db, registry, tenantId, config) {
@@ -44,15 +44,18 @@ function createPdfRenderer(db, registry, tenantId, config, filesForTenant) {
         return { content: response.pdfBytes, contentType: PDF_CONTENT_TYPE };
     };
 }
-// A decorative inline image (logo) that cannot be read must not fail the whole mail.
+// A decorative inline image (logo) of a tenant without file storage must not fail the whole mail;
+// transient read errors rethrow so the send job retries.
 async function readInlineImageOrNull(fileRefId, read) {
     try {
         return await read();
     }
     catch (err) {
+        if (!(err instanceof FileStorageUnavailableError))
+            throw err;
         createFallbackLogger("delivery").warn("inline image could not be read, sending without it", {
             fileRefId,
-            errorName: err instanceof Error ? err.name : typeof err,
+            errorName: err.name,
         });
         return null;
     }

package/dist/delivery/db/queries/preferences.js

@@ -1,4 +1,4 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 // @wrapper-known semantic-alias
 export async function selectNotificationPreferences(db, tenantId, userId, notificationTypeNames, channelName) {
     return unsafeReadRetrying(db, `SELECT notification_type AS "notificationType", channel, enabled
@@ -9,5 +9,5 @@ export async function selectNotificationPreferences(db, tenantId, userId, notifi
          (notification_type = ANY($3::text[]) AND channel = $4)
          OR (notification_type = '*' AND channel = $4)
          OR (notification_type = ANY($3::text[]) AND channel = '*')
-       )`, [tenantId, userId, notificationTypeNames, channelName]);
+       )`, [tenantId, userId, toPostgresArrayLiteral(notificationTypeNames), channelName]);
 }

package/dist/delivery/delivery-service.js

@@ -266,9 +266,27 @@ export function createDeliveryService(options) {
             });
         }
     }
+    // The app's tenantOrigin callback typically hits the DB: once per run and tenant, not per recipient.
+    const unsubscribeOriginsByRun = new WeakMap();
+    function unsubscribeOriginOnce(run, links, channelCtx, notificationType) {
+        let originsByTenant = unsubscribeOriginsByRun.get(run);
+        if (originsByTenant === undefined) {
+            originsByTenant = new Map();
+            unsubscribeOriginsByRun.set(run, originsByTenant);
+        }
+        let origin = originsByTenant.get(channelCtx.tenantId);
+        if (origin === undefined) {
+            origin = unsubscribeLinkOrigin(links, channelCtx, (reason) => logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
+                tenantId: channelCtx.tenantId,
+                notificationType,
+            }));
+            originsByTenant.set(channelCtx.tenantId, origin);
+        }
+        return origin;
+    }
     // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
     // context, never from the notification data.
-    async function withUnsubscribeUrl(message, channelName, recipient, channelCtx) {
+    async function withUnsubscribeUrl(run, message, channelName, recipient, channelCtx) {
         if (!unsubscribeLinks || channelName !== EMAIL_CHANNEL_NAME)
             return message;
         if (registry.getAllNotifications().get(message.notificationType)?.unsubscribe !== true) {
@@ -277,10 +295,7 @@ export function createDeliveryService(options) {
         const supplied = message.data?.["unsubscribeUrl"];
         if (typeof supplied === "string" && supplied !== "")
             return message;
-        const origin = await unsubscribeLinkOrigin(unsubscribeLinks, channelCtx, (reason) => logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
-            tenantId: channelCtx.tenantId,
-            notificationType: message.notificationType,
-        }));
+        const origin = await unsubscribeOriginOnce(run, unsubscribeLinks, channelCtx, message.notificationType);
         const unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
             tenantId: channelCtx.tenantId,
             notificationType: message.notificationType,
@@ -476,7 +491,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message: await withUnsubscribeUrl(message, channel.name, { kind: "user", userId }, channelCtx),
+                    message: await withUnsubscribeUrl(run, message, channel.name, { kind: "user", userId }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId: userId,
@@ -549,7 +564,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message: await withUnsubscribeUrl(message, channel.name, { kind: "address", address }, channelCtx),
+                    message: await withUnsubscribeUrl(run, message, channel.name, { kind: "address", address }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId,

package/dist/delivery/feature.js

@@ -55,10 +55,10 @@ export function createDeliveryFeature(options) {
         // boot-validator accepts the projection below because at least one
         // apply-key is a registered domain-event (DELIVERY_ATTEMPT_EVENT).
         // recipientAddress is the real PII (email address); recipientId stays
-        // plaintext — pseudonymous fk, same line as config.userId (#821).
+        // plaintext — pseudonymous fk, same line as config.userId.
         // recipientId is nullable (system-triggered sends to non-users), so the
         // address falls back to the tenant key instead of the plaintext it used
-        // to be — still shreddable, one tenant wide (fw#2776).
+        // to be — still shreddable, one tenant wide.
         r.defineEvent("attempt", deliveryAttemptSchema, {
             piiFields: {
                 recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },

package/dist/delivery/handlers/log.query.js

@@ -135,7 +135,7 @@ export const logQuery = definePagedQueryHandler({
         const rows = [...tiedRows, ...beyondRows];
         const lastRow = rows[rows.length - 1];
         const nextCursor = rows.length === limit && lastRow ? encodeSortCursor(sortColumn, lastRow) : null;
-        // recipientAddress is stored encrypted under the recipient's DEK (#799)
+        // recipientAddress is stored encrypted under the recipient's DEK
         // — decrypt for the admin log view; forgotten subjects show [[erased]].
         // The notificationType/recipientAddress → type/recipient rename happens
         // here, not in the client: a projectionList screen has no entity to

package/dist/delivery/handlers/preferences.query.d.ts

@@ -1,4 +1,4 @@
 import * as z from "zod";
 export declare const preferencesQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"preferences", z.ZodObject<{}, z.core.$strip>, {
-    rows: readonly any[];
+    rows: any[];
 }, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/delivery/handlers/preferences.query.js

@@ -2,6 +2,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.js";
 import { notificationPreferencesTable } from "../tables.js";
 export const preferencesQuery = defineQueryHandler({
     name: "preferences",
@@ -31,6 +32,24 @@ export const preferencesQuery = defineQueryHandler({
             tenantId: query.user.tenantId,
             userId: query.user.id,
         });
-        return { rows };
+        // Rows stored under a former notification name are reported under the current
+        // one, collapsed with the same precedence as delivery: an exact row wins,
+        // otherwise any disabled former-name row disables.
+        const collapsed = new Map();
+        for (const row of rows) {
+            const notificationType = currentNotificationType(ctx.registry, row.notificationType);
+            const key = `${notificationType}\u0000${row.channel}`;
+            const isExact = row.notificationType === notificationType;
+            const existing = collapsed.get(key);
+            if (existing?.isExact)
+                continue;
+            const formerNameRowDisablesAlready = existing !== undefined &&
+                !isExact &&
+                (existing.row.enabled === false || row.enabled !== false);
+            if (formerNameRowDisablesAlready)
+                continue;
+            collapsed.set(key, { row: { ...row, notificationType }, isExact });
+        }
+        return { rows: [...collapsed.values()].map((entry) => entry.row) };
     },
 });

package/dist/delivery/handlers/unsubscribe-page-chrome.query.js

@@ -23,7 +23,7 @@ export const unsubscribePageChromeQuery = defineQueryHandler({
     // Only reachable via a system dispatch: the signed unsubscribe routes after verify(),
     // or createUnsubscribePageChromeReader for a tenant the app resolved server-side.
     agent: { expose: false },
-    description: "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route to dress its pages like the mail, not meant for UI callers.",
+    description: "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route or by createUnsubscribePageChromeReader for a tenant the app resolved server-side, to dress its pages like the mail; not meant for UI callers.",
     handler: async (query, ctx) => {
         const { tenantId } = query.user;
         if (!ctx.systemDb) {

package/dist/delivery/tables.js

@@ -30,14 +30,15 @@ export const deliveryAttemptsTable = pgTable("store_delivery_attempts", {
     priority: text("priority").notNull().default("normal").$type(),
     createdAt: instant("created_at").default(sql `now()`).notNull(),
 }, (t) => [index(DELIVERY_ATTEMPTS_TENANT_CREATED_INDEX).on(t.tenantId, t.createdAt)]);
-// **Unmanaged table** — bewusst KEIN createEntity. Begründung:
-//   - id kommt aus dem Aggregate-Stream (kein gen_random_uuid()-DEFAULT)
-//   - kein version/inserted_by/modified_by/modified_at — keine in-place-
-//     Edits, keine Audit-Spalten nötig (idempotent-on-replay via PK-Konflikt)
-//   - created_at statt inserted_at — historischer Naming-Drift, kein Bug
-// App trägt Verantwortung für tenant-scoping in Queries + replay-idempotency.
-// pgTable bleibt source-of-truth für Query-API; Phase 4 leitet das pgTable
-// aus dieser Meta ab.
+// **Unmanaged table** — deliberately has no createEntity because:
+//   - id comes from the aggregate stream (no gen_random_uuid()-DEFAULT)
+//   - no version/inserted_by/modified_by/modified_at: no in-place edits or
+//     audit columns are needed (idempotent-on-replay via PK conflict)
+//   - created_at rather than inserted_at reflects historical naming drift, not
+//     a bug
+// The app is responsible for tenant scoping in queries and replay idempotency.
+// pgTable remains the source of truth for the query API; the pgTable is derived
+// from this metadata.
 export const deliveryAttemptsTableMeta = defineUnmanagedTable({
     tableName: "store_delivery_attempts",
     indexes: [{ name: DELIVERY_ATTEMPTS_TENANT_CREATED_INDEX, columns: ["tenant_id", "created_at"] }],

package/dist/delivery/unsubscribe-link.d.ts

@@ -5,7 +5,9 @@ export type UnsubscribeLinkConfig = {
     readonly secret: string;
     readonly baseUrl: string;
     /** The sending tenant's own public origin (subdomain or custom domain), null when it has
-     *  none. The host must serve this app's `/api` routes. Null, a throw or an unusable value
+     *  none. The host must serve this app's `/api` routes, and the callback must only return a
+     *  verified, active domain of the tenant (the check that lets the app serve under it), else null:
+     *  the link carries a bearer token that unsubscribes and yields a resubscribe token. Null, a throw or an unusable value
      *  fall back to `baseUrl`, so a missing tenant origin never fails a send. */
     readonly tenantOrigin?: (ctx: ChannelContext) => Promise<string | null | undefined>;
 };

package/dist/delivery/unsubscribe-page-strings.d.ts

@@ -10,6 +10,7 @@ export declare const UNSUBSCRIBE_PAGE_EN: {
     readonly "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.";
     readonly "mail.unsubscribe.failed": "That did not work. Please try again later.";
     readonly "mail.unsubscribe.failedTitle": "Something went wrong";
+    readonly "mail.unsubscribe.resubscribeLimitReached": "This address cannot be subscribed again here.";
     readonly "mail.unsubscribe.invalidTitle": "Link no longer valid";
     readonly "mail.unsubscribe.invalidMessage": "This link is invalid or has expired. Please use the unsubscribe link in a more recent email.";
 };

package/dist/delivery/unsubscribe-page-strings.js

@@ -13,6 +13,7 @@ export const UNSUBSCRIBE_PAGE_EN = {
     "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.",
     "mail.unsubscribe.failed": "That did not work. Please try again later.",
     "mail.unsubscribe.failedTitle": "Something went wrong",
+    "mail.unsubscribe.resubscribeLimitReached": "This address cannot be subscribed again here.",
     "mail.unsubscribe.invalidTitle": "Link no longer valid",
     "mail.unsubscribe.invalidMessage": "This link is invalid or has expired. Please use the unsubscribe link in a more recent email.",
 };

package/dist/delivery/unsubscribe-page.d.ts

@@ -10,6 +10,8 @@ export type UnsubscribePageState = {
     readonly kind: "resubscribed";
 } | {
     readonly kind: "failed";
+} | {
+    readonly kind: "resubscribeLimitReached";
 } | {
     readonly kind: "invalid";
 };

package/dist/delivery/unsubscribe-page.js

@@ -135,6 +135,11 @@ ${tokenForm(DELIVERY_RESUBSCRIBE_PATH, state.resubscribeToken, mailT(lang, "mail
                 title: mailT(lang, "mail.unsubscribe.failedTitle"),
                 bodyHtml: paragraph("mail.unsubscribe.failed"),
             };
+        case "resubscribeLimitReached":
+            return {
+                title: mailT(lang, "mail.unsubscribe.failedTitle"),
+                bodyHtml: paragraph("mail.unsubscribe.resubscribeLimitReached"),
+            };
         case "invalid":
             return {
                 title: mailT(lang, "mail.unsubscribe.invalidTitle"),

package/dist/delivery/unsubscribe.js

@@ -13,13 +13,13 @@ const localeClaimSchema = z
     .string()
     .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
     .optional();
-// Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
-// wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+// Shape of verified JWT payloads. `tenantId` arrives from jose as a string and
+// becomes a branded `TenantId` only after successful `parse()`—never via a blind cast.
 //
 // `kind` is explicitly typed as "absent or undefined, nothing else" here
 // (not bare `.optional()`, which would also accept any other value on an
-// unrelated key) so an address-token payload — which always carries
-// `kind: "address"` — fails this schema instead of silently parsing with
+// unrelated key) so an address-token payload—which always carries
+// `kind: "address"`—fails this schema instead of silently parsing with
 // `addressHash` mistaken for a userId.
 const unsubscribeJwtPayloadSchema = z.object({
     kind: z.undefined().optional(),
@@ -373,10 +373,16 @@ async function verifyForPage(token, encodedSecret, purpose, headers) {
     }
 }
 async function verifyPost(request, token, encodedSecret, purpose) {
-    return isFormRequest(request.headers["content-type"])
+    return isFormRequest(request.headers["content-type"]) && !isOneClickPost(request)
         ? verifyForPage(token, encodedSecret, purpose, request.headers)
         : verifyUnsubscribeToken(token, encodedSecret, purpose);
 }
+// RFC 8058 mail-provider POSTs are form-encoded too, but nobody looks at the answer: they keep
+// the JSON rejection and get no branded page.
+function isOneClickPost(request) {
+    return (isFormRequest(request.headers["content-type"]) &&
+        request.rawBody.trim() === DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE);
+}
 function isFormRequest(contentType) {
     return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
@@ -435,22 +441,31 @@ export function createUnsubscribeRoutes(options) {
         method: "POST",
         path: DELIVERY_UNSUBSCRIBE_PATH,
         entry: "signature",
-        verify: async (request) => verifyPost(request, tokenFromPostRequest(request), encodedSecret, "unsubscribe"),
+        verify: async (request) => {
+            const verified = await verifyPost(request, tokenFromPostRequest(request), encodedSecret, "unsubscribe");
+            return verified.kind === "rejected"
+                ? verified
+                : { ...verified, oneClick: isOneClickPost(request) };
+        },
         handler: async (c, verified, deps) => {
             if (verified.kind === "rejected") {
                 return pageResponse(c, deps, { kind: "invalid" }, verified, 400);
             }
+            // No chrome lookup for a one-click client: it never renders the page.
+            const pageScope = verified.oneClick
+                ? { tenantId: undefined, locale: verified.locale }
+                : verified;
             // Token-verify passed — everything below is a legitimate write. Don't
             // swallow write-errors as "invalid token", that would mask real bugs
             // (e.g. events-table missing, DB down) behind a misleading 400.
             const succeeded = await dispatchUnsubscribeWrite(verified, deps);
             if (!succeeded) {
-                return pageResponse(c, deps, { kind: "failed" }, verified, 500);
+                return pageResponse(c, deps, { kind: "failed" }, pageScope, 500);
             }
             return pageResponse(c, deps, {
                 kind: "unsubscribed",
                 resubscribeToken: await signResubscribeToken(verified, encodedSecret),
-            }, verified, 200);
+            }, pageScope, 200);
         },
     });
     // Undo direction: token only from the JSON/form body, never the query
@@ -468,9 +483,12 @@ export function createUnsubscribeRoutes(options) {
             const outcome = await dispatchResubscribeWrite(verified, deps);
             // The undo button on the unsubscribed page posts a form; a browser should land on a page.
             if (isFormRequest(c.req.header("content-type"))) {
-                return outcome === "success"
-                    ? pageResponse(c, deps, { kind: "resubscribed" }, verified, 200)
-                    : pageResponse(c, deps, { kind: "failed" }, verified, outcome === "limit_reached" ? 409 : 500);
+                if (outcome === "success") {
+                    return pageResponse(c, deps, { kind: "resubscribed" }, verified, 200);
+                }
+                return outcome === "limit_reached"
+                    ? pageResponse(c, deps, { kind: "resubscribeLimitReached" }, verified, 409)
+                    : pageResponse(c, deps, { kind: "failed" }, verified, 500);
             }
             if (outcome === "limit_reached") {
                 return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, NO_STORE_HEADERS);