@cosmicdrift/kumiko-bundled-features 0.371.0 → 0.372.0

package/dist/custom-fields/executor.d.ts

@@ -1 +1,19 @@
-export declare const fieldDefinitionExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+export declare const fieldDefinitionExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
+    readonly id: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly insertedAt: Temporal.Instant;
+    readonly modifiedAt: Temporal.Instant | null;
+    readonly insertedById: string | null;
+    readonly modifiedById: string | null;
+    readonly isDeleted?: boolean | undefined;
+    readonly deletedAt?: Temporal.Instant | null | undefined;
+    readonly deletedById?: string | null | undefined;
+    readonly displayOrder: number;
+    readonly entityName: string;
+    readonly fieldKey: string;
+    readonly required: boolean;
+    readonly searchable: boolean;
+    readonly serializedField: string;
+    readonly type: string;
+}>;

package/dist/data-retention/index.d.ts

@@ -1,3 +1,4 @@
 export type { EffectiveRetentionPolicy, ResolveForTenantArgs, ResolveRetentionPolicyArgs, ResolveTenantPresetArgs, RetentionOverride, RetentionPreset, RetentionPresetKey, } from "./feature.ts";
 export { createDataRetentionFeature, RETENTION_PRESETS, resolveRetentionPolicy, resolveRetentionPolicyForTenant, resolveTenantRetentionPreset, retentionOverrideSchema, SELECTABLE_RETENTION_PRESETS, tenantRetentionOverrideEntity, tenantRetentionOverrideTable, } from "./feature.ts";
 export { computeCutoff, type Instant } from "./keep-for.ts";
+export { type RetentionCleanupSkip, type RunRetentionCleanupArgs, type RunRetentionCleanupResult, runRetentionCleanup, } from "./run-retention-cleanup.ts";

package/dist/data-retention/index.js

@@ -1,2 +1,3 @@
 export { createDataRetentionFeature, RETENTION_PRESETS, resolveRetentionPolicy, resolveRetentionPolicyForTenant, resolveTenantRetentionPreset, retentionOverrideSchema, SELECTABLE_RETENTION_PRESETS, tenantRetentionOverrideEntity, tenantRetentionOverrideTable, } from "./feature.js";
 export { computeCutoff } from "./keep-for.js";
+export { runRetentionCleanup, } from "./run-retention-cleanup.js";

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

@@ -43,7 +43,7 @@ import { deleteFileRefBytes } from "@cosmicdrift/kumiko-framework/derivatives";
 import { createSystemUser, entityHasAnonymizableSubjectField, } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefEntity, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { runInSubTransaction } from "../shared/index.js";
+import { collectSingleFileHolders, planFileFields, purgeRowFileRefs, runInSubTransaction, } from "../shared/index.js";
 import { computeCutoff } from "./keep-for.js";
 import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.js";
 import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override.js";
@@ -152,106 +152,7 @@ async function forgetRowAndEraseKeys(args) {
         return { isSuccess: true };
     });
 }
-const NO_FILE_FIELDS = { singleFields: [], multiFields: [] };
-// file/image = single-column fields (fileRef-id lives directly in the entity
-// row); files/images = plural, resolved via file_refs. Same set
-// as boot-validator/entity-handler.ts FILE_FIELD_TYPES and engine's
-// isFileField — inlined here rather than importing across the package
-// barrel since this module already needs the single/multi split, not just
-// membership.
-function planFileFields(fields) {
-    const singleFields = [];
-    const multiFields = [];
-    for (const [name, field] of Object.entries(fields)) {
-        const type = field.type; // @cast-boundary schema-walk
-        if (type === "file" || type === "image")
-            singleFields.push(name);
-        else if (type === "files" || type === "images")
-            multiFields.push(name);
-    }
-    return singleFields.length > 0 || multiFields.length > 0
-        ? { singleFields, multiFields }
-        : NO_FILE_FIELDS;
-}
-// Every fileRef-id a row's file/image/files/images-fields reference: single
-// fields hold the id in their own column, plural fields resolve
-// via file_refs (tenantId, entityType, entityId, fieldName).
-async function collectFileRefIds(db, tenantId, entityName, row, plan) {
-    const ids = new Set();
-    for (const field of plan.singleFields) {
-        const value = row[field];
-        if (typeof value === "string" && value.length > 0)
-            ids.add(value);
-    }
-    if (plan.multiFields.length > 0) {
-        const refRows = await selectMany(db, fileRefsTable, {
-            tenantId,
-            entityType: entityName,
-            entityId: String(row["id"]),
-            fieldName: { in: plan.multiFields },
-        });
-        for (const r of refRows)
-            ids.add(r.id);
-    }
-    return Array.from(ids);
-}
-// A fileRef is bound to a DIFFERENT entity/record than the row currently
-// being purged — its binding (entityType/entityId), not the row's own
-// single-field column, decides ownership. A single-field value can point at
-// a fileRef uploaded/attached elsewhere; that fileRef's bytes belong to
-// whatever it's actually bound to, not to this row.
-function isFileRefBoundElsewhere(fileRef, entityName, rowId) {
-    const entityType = fileRef["entityType"];
-    const entityId = fileRef["entityId"];
-    if (typeof entityType === "string" && entityType !== entityName)
-        return true;
-    if (typeof entityId === "string" && entityId !== rowId)
-        return true;
-    return false;
-}
-// Every implicit entity table with file/image fields: an unbound fileRef
-// (POST /files without entityType/entityId) can sit in single fields of
-// several entity types, so the sharing check must look beyond the purged
-// row's own table.
-function collectSingleFileHolders(registry) {
-    const holders = [];
-    for (const proj of registry.getAllProjections().values()) {
-        if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
-            continue;
-        const entity = registry.getEntity(proj.source);
-        if (!entity)
-            continue;
-        const { singleFields } = planFileFields(entity.fields);
-        if (singleFields.length === 0)
-            continue;
-        holders.push({
-            table: proj.table,
-            tableHasTenantId: propertyOf(proj.table, "tenantId") !== undefined,
-            singleFields,
-        });
-    }
-    return holders;
-}
-// A single-field fileRef-id can be shared by more than one row, in the SAME
-// table (e.g. a stock-photo re-picked across records) or in another entity's
-// table. Purging its bytes would corrupt the row that isn't being deleted.
-// Bounded by batchLimit rows per run and holderFields queries per fileRef —
-// the same per-row event-cost tradeoff as the rest of this cron (see header).
-async function isFileRefSharedByOtherRow(db, holders, ownTable, tenantId, rowId, fileRefId) {
-    for (const holder of holders) {
-        for (const field of holder.singleFields) {
-            const where = { [field]: fileRefId };
-            if (holder.table === ownTable)
-                where["id"] = { ne: rowId };
-            if (holder.tableHasTenantId)
-                where["tenantId"] = tenantId;
-            const others = await selectMany(db, holder.table, where, { limit: 1 });
-            if (others.length > 0)
-                return true;
-        }
-    }
-    return false;
-}
+// --- hardDelete + file-fields (kumiko-framework#3089) ---
 // Throws (unsafe key, missing list permission) must fail this row closed,
 // not abort the whole tenant run.
 async function deleteFileFailingClosed(key, files, logContext) {
@@ -265,14 +166,32 @@ async function deleteFileFailingClosed(key, files, logContext) {
     }
 }
 // hardDelete for ONE row of an entity that has file/image/files/images
-// fields: delete the un-shared fileRefs' bytes (+ derivatives) first, then
-// their fileRef rows, then the entity row itself — bytes before rows so a
-// crash mid-way leaves an orphaned fileRef pointing at already-gone bytes
-// (safe: a later run's provider.delete is idempotent) rather than a gone
-// fileRef whose bytes leak forever.
+// 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 forgetEntityRow = () => forgetRowAndEraseKeys({
+    const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`;
+    const files = args.files;
+    const outcome = await purgeRowFileRefs({
+        db: args.db,
+        tenantId: args.tenantId,
+        entityName: args.entityName,
+        entity: args.entity,
+        table: args.table,
+        fileHolders: args.fileHolders,
+        row: args.row,
+        deleteBytes: files ? (key) => deleteFileFailingClosed(key, files, logContext) : undefined,
+        fileRefForget: async (fileRefId) => (await args.fileRefExecutor.forget({ id: fileRefId }, args.systemUser, args.tdb)).isSuccess,
+        onBytesDeleteFailed: (failedKeys) => {
+            // biome-ignore lint/suspicious/noConsole: operator-visibility for storage-cleanup failures
+            console.warn(`[data-retention:hardDelete] ${logContext} storage delete failed keys=${failedKeys.join(",")}`);
+        },
+    });
+    if (outcome !== "purged") {
+        args.onSkip(outcome);
+        return false;
+    }
+    return (await forgetRowAndEraseKeys({
         db: args.db,
         executor: args.entityExecutor,
         entity: args.entity,
@@ -282,56 +201,7 @@ async function purgeHardDeleteRowWithFiles(args) {
         row: args.row,
         kms: args.kms,
         registry: args.registry,
-    });
-    const fileRefIds = await collectFileRefIds(args.db, args.tenantId, args.entityName, args.row, args.plan);
-    if (fileRefIds.length === 0) {
-        return (await forgetEntityRow()).isSuccess;
-    }
-    const fileRefRows = await selectMany(args.db, fileRefsTable, {
-        id: { in: fileRefIds },
-        tenantId: args.tenantId,
-    });
-    const toDelete = [];
-    for (const fileRef of fileRefRows) {
-        if (isFileRefBoundElsewhere(fileRef, args.entityName, rowId))
-            continue;
-        const shared = await isFileRefSharedByOtherRow(args.db, args.fileHolders, args.table, args.tenantId, rowId, String(fileRef["id"]));
-        if (shared)
-            continue;
-        toDelete.push(fileRef);
-    }
-    if (toDelete.length === 0) {
-        return (await forgetEntityRow()).isSuccess;
-    }
-    if (!args.files) {
-        args.onSkip("missing_file_storage");
-        return false;
-    }
-    const files = args.files;
-    let anyFailed = false;
-    for (const fileRef of toDelete) {
-        const key = fileRef["storageKey"];
-        if (typeof key !== "string" || key.length === 0)
-            continue;
-        const failedKeys = await deleteFileFailingClosed(key, files, `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`);
-        if (failedKeys.length > 0) {
-            anyFailed = true;
-            // biome-ignore lint/suspicious/noConsole: operator-visibility for storage-cleanup failures
-            console.warn(`[data-retention:hardDelete] tenant=${args.tenantId} entity=${args.entityName} row=${rowId} storage delete failed keys=${failedKeys.join(",")}`);
-        }
-    }
-    if (anyFailed) {
-        args.onSkip("file_delete_failed");
-        return false;
-    }
-    for (const fileRef of toDelete) {
-        const res = await args.fileRefExecutor.forget({ id: fileRef["id"] }, args.systemUser, args.tdb);
-        if (!res.isSuccess) {
-            args.onSkip("file_delete_failed");
-            return false;
-        }
-    }
-    return (await forgetEntityRow()).isSuccess;
+    })).isSuccess;
 }
 // hardDelete page for an entity WITH file/image/files/images fields — loads
 // full rows (not just id) so file-field values are available, and reports
@@ -369,7 +239,6 @@ async function purgeHardDeleteRowsWithFiles(args) {
                 entityName: args.entityName,
                 entity: args.entity,
                 row,
-                plan: args.plan,
                 files: args.files,
                 entityExecutor: args.entityExecutor,
                 fileRefExecutor: args.fileRefExecutor,
@@ -520,7 +389,6 @@ export async function runRetentionCleanup(args) {
                     tenantId,
                     entityName,
                     entity,
-                    plan: filePlan,
                     files: args.files,
                     entityExecutor: executor,
                     fileRefExecutor,

package/dist/data-retention/schema/tenant-retention-override.d.ts

@@ -1,5 +1,5 @@
 export declare const tenantRetentionOverrideEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    entityName: {
+    readonly entityName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -22,7 +22,7 @@ export declare const tenantRetentionOverrideEntity: import("@cosmicdrift/kumiko-
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    config: {
+    readonly config: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -38,7 +38,7 @@ export declare const tenantRetentionOverrideEntity: import("@cosmicdrift/kumiko-
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    reason: {
+    readonly reason: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -63,7 +63,7 @@ export declare const tenantRetentionOverrideEntity: import("@cosmicdrift/kumiko-
     };
 }, "tenant">;
 export declare const tenantRetentionOverrideTable: import("@cosmicdrift/kumiko-framework/db").EntityTable<import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    entityName: {
+    readonly entityName: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -86,7 +86,7 @@ export declare const tenantRetentionOverrideTable: import("@cosmicdrift/kumiko-f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    config: {
+    readonly config: {
         readonly type: "longText";
         readonly description?: string;
         readonly maxLength?: number;
@@ -102,7 +102,7 @@ export declare const tenantRetentionOverrideTable: import("@cosmicdrift/kumiko-f
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    reason: {
+    readonly reason: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;

package/dist/delivery/delivery-service.d.ts

@@ -3,7 +3,7 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { ConfigAccessor, EscapeHatchAuditSink, NotifyJobDispatcher, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
-import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { EnvelopeCipher, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import { type DeliveryChannel, type DeliveryService } from "./types.ts";
 import { type UnsubscribeLinkConfig } from "./unsubscribe-link.ts";
@@ -25,6 +25,7 @@ export type DeliveryServiceOptions = {
     readonly idempotencyRedis?: Redis;
     readonly jobRunner?: NotifyJobDispatcher;
     readonly secrets?: SecretsContext;
+    readonly addressCipher?: EnvelopeCipher;
     readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
     readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;

package/dist/delivery/delivery-service.js

@@ -12,6 +12,7 @@ import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryIdempotencyRedisKey,
 import { addressOptOutKey, selectOptedOutAddresses, } from "./db/queries/address-opt-outs.js";
 import { selectNotificationPreferences } from "./db/queries/preferences.js";
 import { notificationTypeNames } from "./notification-type-aliases.js";
+import { sealRecipientAddress } from "./recipient-address-seal.js";
 import { isDeliveryChannelPlugin, } from "./types.js";
 import { buildUnsubscribeUrl, unsubscribeLinkOrigin, } from "./unsubscribe-link.js";
 export function redactedMessageOf(err) {
@@ -28,7 +29,7 @@ export function collectChannels(registry) {
     });
 }
 export function createDeliveryService(options) {
-    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, filesForTenant, tenantConfigFor, escapeHatchAuditSink, log, unsubscribeLinks, } = options;
+    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, addressCipher, filesForTenant, tenantConfigFor, escapeHatchAuditSink, log, unsubscribeLinks, } = options;
     const idemRedis = idempotencyRedis ?? rateLimit?.redis;
     const logError = createFallbackLogger("delivery", log);
     // Rate limit check: atomic INCR + TTL + over-limit rollback via server-side
@@ -219,7 +220,7 @@ export function createDeliveryService(options) {
             await appendAttemptEvent(run.db, registry, deliveryAttemptId, queuedEntry);
             await run.jobDispatcher.dispatch(channel.render ? DeliveryJobs.render : DeliveryJobs.send, {
                 channelName: channel.name,
-                address,
+                ...(await sealRecipientAddress(address, tenantId, addressCipher)),
                 tenantId,
                 recipientId,
                 notificationType,

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

@@ -20,8 +20,8 @@ export const unsubscribePageChromeQuery = defineQueryHandler({
     name: "unsubscribePageChrome",
     schema: z.object({ locale: z.string().min(2).max(35) }),
     access: { roles: access.systemAdmin },
-    // Only reachable via createUnsubscribeRoutes' dispatchSystemQuery once verify()
-    // proved the token signature.
+    // 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.",
     handler: async (query, ctx) => {

package/dist/delivery/index.d.ts

@@ -15,6 +15,6 @@ export { createDeliveryNotifyFactory } from "./notify-factory.ts";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.ts";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing.ts";
 export { type AttachmentOrigin, type ChannelContext, type ChannelMessage, type ChannelResult, type DeliveryChannel, type DeliveryChannelMode, type DeliveryChannelPlugin, type DeliveryLogEntry, type DeliveryService, isDeliveryChannelPlugin, type RenderedMessage, } from "./types.ts";
-export { type AddressUnsubscribeTokenPayload, createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, renderUnsubscribeResultPage, signAddressUnsubscribeToken, signUnsubscribeToken, type UnsubscribeResultPage, type UnsubscribeRouteOptions, type UnsubscribeTokenPayload, } from "./unsubscribe.ts";
+export { type AddressUnsubscribeTokenPayload, createUnsubscribePageChromeReader, createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, renderUnsubscribeResultPage, signAddressUnsubscribeToken, signUnsubscribeToken, type UnsubscribePageChromeReader, type UnsubscribeResultPage, type UnsubscribeRouteOptions, type UnsubscribeTokenPayload, } from "./unsubscribe.ts";
 export type { UnsubscribeLinkConfig } from "./unsubscribe-link.ts";
 export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.ts";

package/dist/delivery/index.js

@@ -14,5 +14,5 @@ export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
 export { createDeliveryTestContext } from "./testing.js";
 export { isDeliveryChannelPlugin, } from "./types.js";
-export { createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, renderUnsubscribeResultPage, signAddressUnsubscribeToken, signUnsubscribeToken, } from "./unsubscribe.js";
+export { createUnsubscribePageChromeReader, createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, renderUnsubscribeResultPage, signAddressUnsubscribeToken, signUnsubscribeToken, } from "./unsubscribe.js";
 export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/dist/delivery/jobs.js

@@ -12,6 +12,7 @@ import { appendAttemptEvent } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
 import { DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank } from "./constants.js";
 import { collectChannels, redactedMessageOf } from "./delivery-service.js";
+import { openRecipientAddress, recipientAddressFieldSchema, } from "./recipient-address-seal.js";
 const channelMessageSchema = z.object({
     notificationType: z.string(),
     title: z.string(),
@@ -19,9 +20,8 @@ const channelMessageSchema = z.object({
     data: z.record(z.string(), z.unknown()).optional(),
     locale: z.string().optional(),
 });
-const renderJobPayloadSchema = z.object({
+const renderJobBaseSchema = z.object({
     channelName: z.string(),
-    address: z.string(),
     tenantId: z.string(),
     recipientId: z.string().nullable(),
     notificationType: z.string(),
@@ -30,7 +30,9 @@ const renderJobPayloadSchema = z.object({
     message: channelMessageSchema,
     idempotencyKey: z.string().optional(),
 });
-const sendJobPayloadSchema = renderJobPayloadSchema.extend({
+const renderJobPayloadSchema = renderJobBaseSchema.and(recipientAddressFieldSchema);
+const sendJobPayloadSchema = renderJobBaseSchema
+    .extend({
     rendered: z
         .object({
         html: z.string(),
@@ -41,7 +43,8 @@ const sendJobPayloadSchema = renderJobPayloadSchema.extend({
         attachments: z.array(emailAttachmentRefSchema).max(MAX_EMAIL_ATTACHMENTS).optional(),
     })
         .optional(),
-});
+})
+    .and(recipientAddressFieldSchema);
 function requireTenantScopedDeps(ctx, tenantId) {
     const registry = ctx.registry;
     if (!registry)
@@ -141,6 +144,16 @@ async function releasingKeyOnTerminalFailure(ctx, p, run) {
         throw err;
     }
 }
+// A missing or rotated key must not hide the original failure, so the log row just omits the address.
+async function addressForAttemptLog(p, ctx) {
+    try {
+        return await openRecipientAddress(p, p.tenantId, // @cast-boundary engine-payload — job payload string is the stream tenant
+        ctx.configEncryption);
+    }
+    catch {
+        return null;
+    }
+}
 // The job runner stores err.message in the run row, and BullMQ keeps failedReason and
 // the stack trace in Redis in plain text, so the rethrown error carries only the code.
 // The redacted message goes to the log.
@@ -150,7 +163,7 @@ async function failAttempt(ctx, db, registry, p, code, err) {
         notificationType: p.notificationType,
         channel: p.channelName,
     });
-    await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, "failed", code, p.address));
+    await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, "failed", code, await addressForAttemptLog(p, ctx)));
     throw new Error(code);
 }
 // Render the message and hand off to delivery.send. On failure: record the
@@ -196,8 +209,9 @@ async function sendStep(p, ctx) {
     const channel = resolveChannel(registry, p.channelName);
     const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets, ctx.config, (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId));
     try {
-        const result = await channel.send(p.address, toMessage(p), channelCtx, p.rendered);
-        await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, result.status, result.error ?? null, result.address ?? p.address, result.confirmed));
+        const address = await openRecipientAddress(p, tenantId, ctx.configEncryption);
+        const result = await channel.send(address, toMessage(p), channelCtx, p.rendered);
+        await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, result.status, result.error ?? null, result.address ?? address, result.confirmed));
         // A soft failure ends the job successfully, so no retry follows and the caller's
         // retry must not be skipped as a duplicate.
         if (result.status === "failed")

package/dist/delivery/recipient-address-seal.d.ts

@@ -0,0 +1,13 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import * as z from "zod";
+export declare const recipientAddressFieldSchema: z.ZodUnion<readonly [z.ZodObject<{
+    address: z.ZodString;
+    sealedAddress: z.ZodOptional<z.ZodUndefined>;
+}, z.core.$strip>, z.ZodObject<{
+    sealedAddress: z.ZodString;
+    address: z.ZodOptional<z.ZodUndefined>;
+}, z.core.$strip>]>;
+export type RecipientAddressField = z.infer<typeof recipientAddressFieldSchema>;
+export declare function sealRecipientAddress(address: string, tenantId: TenantId, cipher: EnvelopeCipher | undefined): Promise<RecipientAddressField>;
+export declare function openRecipientAddress(payload: RecipientAddressField, tenantId: TenantId, cipher: EnvelopeCipher | undefined): Promise<string>;

package/dist/delivery/recipient-address-seal.js

@@ -0,0 +1,53 @@
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+// Queued delivery jobs sit in Redis and the job-run table, so the recipient address travels
+// sealed under the app master key. Without a master key it stays plaintext (`address`); jobs
+// queued before sealing existed carry `address` too and keep working.
+// Exactly one of the two fields: both or neither fails the payload parse.
+export const recipientAddressFieldSchema = z.union([
+    z.object({ address: z.string(), sealedAddress: z.undefined().optional() }),
+    z.object({ sealedAddress: z.string(), address: z.undefined().optional() }),
+]);
+// The cipher is shared with config values and PII entity fields and has no AAD, so the purpose is
+// bound inside the authenticated plaintext. Without it a foreign ciphertext of the same tenant
+// placed into sealedAddress would be decrypted and its plaintext sent to the channel. The tenant
+// is bound there too: the env key provider ignores the encrypt scope, so a sealedAddress of tenant
+// B would otherwise open inside a job of tenant A.
+const RECIPIENT_ADDRESS_PURPOSE = "delivery.recipientAddress";
+const sealedRecipientAddressSchema = z.object({
+    purpose: z.literal(RECIPIENT_ADDRESS_PURPOSE),
+    tenantId: z.string(),
+    address: z.string(),
+});
+export async function sealRecipientAddress(address, tenantId, cipher) {
+    if (!cipher)
+        return { address };
+    const plaintext = JSON.stringify({ purpose: RECIPIENT_ADDRESS_PURPOSE, tenantId, address });
+    return { sealedAddress: await cipher.encrypt(plaintext, { tenantId }) };
+}
+function parseSealedRecipientAddress(plaintext, tenantId) {
+    let decoded;
+    try {
+        decoded = JSON.parse(plaintext);
+    }
+    catch {
+        decoded = undefined;
+    }
+    const parsed = sealedRecipientAddressSchema.safeParse(decoded);
+    if (!parsed.success || parsed.data.tenantId !== tenantId) {
+        throw new InternalError({
+            message: "delivery job: sealedAddress was not sealed as a delivery recipient address",
+        });
+    }
+    return parsed.data.address;
+}
+export async function openRecipientAddress(payload, tenantId, cipher) {
+    if (payload.sealedAddress === undefined)
+        return payload.address;
+    if (!cipher) {
+        throw new InternalError({
+            message: "delivery job: payload carries a sealed recipient address but this process has no master key (configEncryption); run the worker with the same KUMIKO_SECRETS_MASTER_KEY_V<n> as the web process",
+        });
+    }
+    return parseSealedRecipientAddress(await cipher.decrypt(payload.sealedAddress, { tenantId }), tenantId);
+}

package/dist/delivery/tables.d.ts

@@ -2,7 +2,7 @@ import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 export declare const deliveryAttemptsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
 export declare const deliveryAttemptsTableMeta: EntityTableMeta;
 export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    userId: {
+    readonly userId: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -25,7 +25,7 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    notificationType: {
+    readonly notificationType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -48,7 +48,7 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    channel: {
+    readonly channel: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -71,13 +71,14 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    enabled: import("@cosmicdrift/kumiko-types/fields").BooleanFieldDef & {
+    readonly enabled: import("@cosmicdrift/kumiko-types/fields").BooleanFieldDef & {
         required: false;
+        default: boolean;
     };
 }, "tenant">;
 export declare const notificationPreferencesTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
 export declare const notificationAddressOptOutEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
-    addressHash: {
+    readonly addressHash: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -100,7 +101,7 @@ export declare const notificationAddressOptOutEntity: import("@cosmicdrift/kumik
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    notificationType: {
+    readonly notificationType: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
@@ -123,7 +124,7 @@ export declare const notificationAddressOptOutEntity: import("@cosmicdrift/kumik
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
-    channel: {
+    readonly channel: {
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;

package/dist/delivery/testing.d.ts

@@ -4,7 +4,7 @@ import type { ConfigAccessor, EscapeHatchAuditSink, Registry, TenantId } from "@
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
-import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { EnvelopeCipher, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.ts";
 import type { DeliveryService } from "./types.ts";
@@ -17,6 +17,7 @@ export type CreateDeliveryTestContextOptions = {
     readonly log?: Logger;
     readonly jobRunner?: JobRunner;
     readonly secrets?: SecretsContext;
+    readonly addressCipher?: EnvelopeCipher;
     readonly idempotencyRedis?: Redis;
     readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
     readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;

package/dist/delivery/testing.js

@@ -23,5 +23,6 @@ export function createDeliveryTestContext(deps, options = {}) {
     return {
         deliveryService, // exposed so tests can inspect/call directly if needed
         _notifyFactory: createDeliveryNotifyFactory(deliveryService),
+        ...(options.addressCipher && { configEncryption: options.addressCipher }),
     };
 }

package/dist/delivery/unsubscribe.d.ts

@@ -1,4 +1,4 @@
-import { type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import { type ExtraRouteDefinition, type SystemDispatchArgs } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { MailChrome } from "../renderer-foundation/index.ts";
 export type UnsubscribeTokenPayload = {
@@ -46,7 +46,9 @@ export type UnsubscribeResultPage = {
 };
 /** The result page the unsubscribe routes answer with, for apps serving their own
  *  (e.g. legacy) unsubscribe links. Texts come from the mail translations of `locale`;
- *  `chrome` (the mail renderer's readMailChrome) adds the tenant's brand row and footer.
+ *  `chrome` adds the tenant's brand row and footer: read it with
+ *  createUnsubscribePageChromeReader for a tenant the server resolved itself (e.g. by
+ *  Host), never for a tenantId taken from the query string or body.
  *  Served under runProdApp's default CSP the style block and the same-origin font pass;
  *  an https logo additionally needs its origin, e.g.
  *  `securityHeaders: { csp: { extend: { "img-src": [logoOrigin] } } }`. A hand-written CSP
@@ -55,4 +57,13 @@ export declare function renderUnsubscribeResultPage(page: UnsubscribeResultPage
     readonly locale?: string | undefined;
     readonly chrome?: MailChrome | null | undefined;
 }): string;
+type SystemQueryDispatch = {
+    readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+};
+export type UnsubscribePageChromeReader = (tenantId: TenantId, locale: string | undefined) => Promise<MailChrome | null>;
+/** Reads the chrome for renderUnsubscribeResultPage in an app route without
+ *  public access: build it once in the `wire` hook from its dispatchSystemQuery.
+ *  Null without a mail renderer or when the read fails. */
+export declare function createUnsubscribePageChromeReader(deps: SystemQueryDispatch): UnsubscribePageChromeReader;
 export declare function createUnsubscribeRoutes(options: UnsubscribeRouteOptions): readonly ExtraRouteDefinition[];
+export {};