@cosmicdrift/kumiko-bundled-features 0.366.0 → 0.367.0

package/dist/channel-email/email-channel.d.ts

@@ -1,9 +1,13 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { type DeliveryChannel, type EmailAttachmentRef } from "../delivery/index.js";
+import { type ChannelContext, type DeliveryChannel, type EmailAttachmentRef } from "../delivery/index.js";
 import type { EmailTransport } from "./types.js";
 export declare function fileAttachmentsFrom(data: Readonly<Record<string, unknown>> | undefined, messageLocale?: string): readonly EmailAttachmentRef[];
 export type EmailChannelOptions = {
+    /** The app-wide transport, used for every tenant `tenantTransport` returns null for. */
     readonly transport: EmailTransport;
+    /** Resolves the sending tenant's own transport, null when it has none. Built per send and
+     *  never cached, so a provider change applies to the next mail; a throw fails the send. */
+    readonly tenantTransport?: (ctx: ChannelContext) => Promise<EmailTransport | null>;
     readonly resolveEmail: (userId: string, ctx: {
         db: unknown;
         tenantId: TenantId;

package/dist/channel-email/email-channel.js

@@ -122,7 +122,7 @@ async function resolveAttachments(sources, ctx) {
     return { kind: "resolved", attachments: resolved };
 }
 export function createEmailChannel(options) {
-    const { transport, resolveEmail } = options;
+    const { transport, resolveEmail, tenantTransport } = options;
     // Render runs in the delivery.render job, decoupled from the SMTP send so
     // each can retry independently. Extracted so the inline path (no job runner)
     // can reuse it without going through the channel's own render() indirection.
@@ -150,6 +150,11 @@ export function createEmailChannel(options) {
             ...(attachments !== undefined && { attachments }),
         };
     }
+    async function transportFor(ctx) {
+        if (tenantTransport === undefined)
+            return transport;
+        return (await tenantTransport(ctx)) ?? transport;
+    }
     return {
         name: EMAIL_CHANNEL_NAME,
         mode: "queued",
@@ -184,7 +189,8 @@ export function createEmailChannel(options) {
                 return { status: "failed", error: "send_failed", address };
             }
             const resolvedAttachments = resolution.attachments;
-            await transport.send(guardEmailMessage({
+            const sendTransport = await transportFor(ctx);
+            await sendTransport.send(guardEmailMessage({
                 to: address,
                 subject,
                 html,

package/dist/channel-email/feature.js

@@ -4,7 +4,7 @@ import { createEmailChannel } from "./email-channel.js";
 export function createChannelEmailFeature(options) {
     const channel = createEmailChannel(options);
     return defineFeature("channel-email", (r) => {
-        r.describe("Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.");
+        r.describe("Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.");
         r.uiHints({
             displayLabel: "Email Channel",
             category: "notifications",

package/dist/delivery/channel-context.js

@@ -92,6 +92,7 @@ export function buildChannelContext(db, registry, sseBroker, tenantId, secrets,
         sseBroker,
         tenantId,
         secrets,
+        config: tenantConfig,
         renderMail: createTemplateMailRenderer(db, registry, tenantId, tenantConfig),
         ...(filesForTenant !== undefined && {
             readAttachment: createEmailAttachmentReader(db, registry, tenantId, tenantConfig, filesForTenant),

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

@@ -6,6 +6,7 @@ import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import { type DeliveryChannel, type DeliveryService } from "./types.js";
+import { type UnsubscribeLinkConfig } from "./unsubscribe-link.js";
 export declare function redactedMessageOf(err: unknown): string;
 export type RateLimitConfig = {
     readonly redis: Redis;
@@ -28,6 +29,7 @@ export type DeliveryServiceOptions = {
     readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly log?: Logger;
+    readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 export declare function collectChannels(registry: Registry): DeliveryChannel[];
 export declare function createDeliveryService(options: DeliveryServiceOptions): DeliveryService;

package/dist/delivery/delivery-service.js

@@ -9,11 +9,12 @@ import { redactErrorText } from "../shared/index.js";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { appendAttemptEvent, logAttempt } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
-import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank, } from "./constants.js";
+import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank, EMAIL_CHANNEL_NAME, } from "./constants.js";
 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 { isDeliveryChannelPlugin, } from "./types.js";
+import { buildUnsubscribeUrl, unsubscribeLinkOrigin, } from "./unsubscribe-link.js";
 export function redactedMessageOf(err) {
     return redactErrorText(err instanceof Error ? err.message : String(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, } = options;
+    const { db, registry, sseBroker, channels, tenantUserIdsQuery, rateLimit, isChannelKilled, idempotencyRedis, jobRunner, secrets, 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
@@ -255,6 +256,31 @@ export function createDeliveryService(options) {
             });
         }
     }
+    // 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) {
+        if (!unsubscribeLinks || channelName !== EMAIL_CHANNEL_NAME)
+            return message;
+        if (registry.getAllNotifications().get(message.notificationType)?.unsubscribe !== true) {
+            return message;
+        }
+        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 unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
+            tenantId: channelCtx.tenantId,
+            notificationType: message.notificationType,
+            channel: channelName,
+            locale: message.locale,
+        });
+        return unsubscribeUrl === undefined
+            ? message
+            : { ...message, data: { ...message.data, unsubscribeUrl } };
+    }
     function buildMessage(notificationType, data, channelName, locale) {
         // Look up per-channel template from notification definition
         const notifDef = registry.getAllNotifications().get(notificationType);
@@ -435,7 +461,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message,
+                    message: await withUnsubscribeUrl(message, channel.name, { kind: "user", userId }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId: userId,
@@ -508,7 +534,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message,
+                    message: await withUnsubscribeUrl(message, channel.name, { kind: "address", address }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId,

package/dist/delivery/feature.js

@@ -19,7 +19,7 @@ export function createDeliveryFeature(options) {
     const resolvedAccess = options?.access ?? access.admin;
     const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
     return defineFeature("delivery", (r) => {
-        r.describe('The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app\'s `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message\'s `data.unsubscribeUrl` points at the unsubscribe route.');
+        r.describe("The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.");
         r.uiHints({
             displayLabel: "Notifications \u00b7 Dispatch Core",
             category: "notifications",

package/dist/delivery/handlers/unsubscribe-address.write.d.ts

@@ -1,4 +1,10 @@
 import * as z from "zod";
+export declare const unsubscribeAddressPayloadSchema: z.ZodObject<{
+    addressHash: z.ZodString;
+    notificationType: z.ZodString;
+    channel: z.ZodString;
+}, z.core.$strip>;
+export type UnsubscribeAddressPayload = z.infer<typeof unsubscribeAddressPayloadSchema>;
 export declare const unsubscribeAddressWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"unsubscribeAddress", z.ZodObject<{
     addressHash: z.ZodString;
     notificationType: z.ZodString;

package/dist/delivery/handlers/unsubscribe-address.write.js

@@ -3,13 +3,16 @@ import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { upsertAddressOptOut } from "../address-opt-out.js";
 import { currentNotificationType } from "../notification-type-aliases.js";
+// Also the payload an app job receives with `trigger: { on: DeliveryHandlers.unsubscribeAddress }`
+// after a committed address opt-out (the tenant is the job's `ctx.triggeredBy.tenantId`).
+export const unsubscribeAddressPayloadSchema = z.object({
+    addressHash: z.string().min(1),
+    notificationType: z.string().min(1),
+    channel: z.string().min(1),
+});
 export const unsubscribeAddressWrite = defineWriteHandler({
     name: "unsubscribeAddress",
-    schema: z.object({
-        addressHash: z.string().min(1),
-        notificationType: z.string().min(1),
-        channel: z.string().min(1),
-    }),
+    schema: unsubscribeAddressPayloadSchema,
     access: { roles: access.systemAdmin },
     // Only reachable via createUnsubscribeRoutes' POST dispatchSystemWrite, once
     // verify() has already proven the address-token signature — not a surface

package/dist/delivery/index.d.ts

@@ -9,8 +9,11 @@ export type { DeliveryStatusValue } from "./constants.js";
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, EMAIL_CHANNEL_NAME, } from "./constants.js";
 export { collectChannels, createDeliveryService, type DeliveryServiceOptions, type KillSwitchResolver, type RateLimitConfig, } from "./delivery-service.js";
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.js";
+export { type UnsubscribeAddressPayload, unsubscribeAddressPayloadSchema, } from "./handlers/unsubscribe-address.write.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing.js";
 export { type AttachmentOrigin, type ChannelContext, type ChannelMessage, type ChannelResult, type DeliveryChannel, type DeliveryChannelMode, type DeliveryChannelPlugin, type DeliveryLogEntry, type DeliveryService, isDeliveryChannelPlugin, type RenderedMessage, } from "./types.js";
 export { type AddressUnsubscribeTokenPayload, createUnsubscribeRoutes, DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, signAddressUnsubscribeToken, signUnsubscribeToken, type UnsubscribeRouteOptions, type UnsubscribeTokenPayload, } from "./unsubscribe.js";
+export type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
+export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/dist/delivery/index.js

@@ -8,8 +8,10 @@ export { chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget,
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, EMAIL_CHANNEL_NAME, } from "./constants.js";
 export { collectChannels, createDeliveryService, } from "./delivery-service.js";
 export { createDeliveryFeature } from "./feature.js";
+export { unsubscribeAddressPayloadSchema, } from "./handlers/unsubscribe-address.write.js";
 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, signAddressUnsubscribeToken, signUnsubscribeToken, } from "./unsubscribe.js";
+export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/dist/delivery/testing.d.ts

@@ -8,6 +8,7 @@ import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.js";
 import type { DeliveryService } from "./types.js";
+import type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
 export type CreateDeliveryTestContextOptions = {
     readonly tenantUserIdsQuery?: string;
     readonly rateLimit?: RateLimitConfig;
@@ -19,6 +20,7 @@ export type CreateDeliveryTestContextOptions = {
     readonly idempotencyRedis?: Redis;
     readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
     readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
+    readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 /**
  * Helper for setupTestStack: creates a DeliveryService + _notifyFactory for the test context.

package/dist/delivery/types.d.ts

@@ -1,6 +1,6 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { DeliveryErrorCode, NotifyDeliveryStatus, NotifyDispatched, NotifyJobDispatcher, NotifyOptions, NotifyPriority, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConfigAccessor, DeliveryErrorCode, NotifyDeliveryStatus, NotifyDispatched, NotifyJobDispatcher, NotifyOptions, NotifyPriority, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { MailPayload, RenderedTemplateRef } from "../renderer-foundation/index.js";
@@ -23,6 +23,7 @@ export type ChannelContext = {
     readonly sseBroker: SseBroker | undefined;
     readonly tenantId: TenantId;
     readonly secrets?: SecretsContext | undefined;
+    readonly config?: ConfigAccessor | undefined;
     readonly renderMail?: (payload: MailPayload) => Promise<RenderedMail>;
     readonly readAttachment?: (ref: EmailAttachmentRef, origin?: AttachmentOrigin) => Promise<{
         readonly content: Uint8Array;

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

@@ -0,0 +1,25 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ChannelContext } from "./types.js";
+/** Secret shared with `createUnsubscribeRoutes` plus the public origin the links point at. */
+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
+     *  fall back to `baseUrl`, so a missing tenant origin never fails a send. */
+    readonly tenantOrigin?: (ctx: ChannelContext) => Promise<string | null | undefined>;
+};
+export type UnsubscribeLinkRecipient = {
+    readonly kind: "user";
+    readonly userId: string;
+} | {
+    readonly kind: "address";
+    readonly address: string;
+};
+export declare function unsubscribeLinkOrigin(config: UnsubscribeLinkConfig, ctx: ChannelContext, onFallback: (reason: string) => void): Promise<string>;
+export declare function buildUnsubscribeUrl(config: UnsubscribeLinkConfig, origin: string, recipient: UnsubscribeLinkRecipient, scope: {
+    tenantId: TenantId;
+    notificationType: string;
+    channel: string;
+    locale: string | undefined;
+}): Promise<string | undefined>;

package/dist/delivery/unsubscribe-link.js

@@ -0,0 +1,40 @@
+import { publicOriginOf } from "@cosmicdrift/kumiko-framework/api";
+import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import { DELIVERY_UNSUBSCRIBE_PATH } from "./constants.js";
+import { signAddressUnsubscribeToken, signUnsubscribeToken } from "./unsubscribe.js";
+// https only, unless the app itself runs on plain http (local dev): a tenant origin must not
+// downgrade the link that carries the token.
+function isUsableTenantOrigin(origin, baseUrl) {
+    return (origin.startsWith("https://") || (baseUrl.startsWith("http://") && origin.startsWith("http://")));
+}
+export async function unsubscribeLinkOrigin(config, ctx, onFallback) {
+    if (config.tenantOrigin === undefined)
+        return config.baseUrl;
+    let resolved;
+    try {
+        resolved = await config.tenantOrigin(ctx);
+    }
+    catch (err) {
+        onFallback(`tenantOrigin threw (${err instanceof Error ? err.name : typeof err})`);
+        return config.baseUrl;
+    }
+    if (resolved === null || resolved === undefined)
+        return config.baseUrl;
+    const origin = publicOriginOf(resolved);
+    if (origin === undefined || !isUsableTenantOrigin(origin, config.baseUrl)) {
+        onFallback("tenantOrigin returned no usable https origin");
+        return config.baseUrl;
+    }
+    return origin;
+}
+// Undefined means "no link": without a blind-index key an address opt-out could never be
+// matched again, and a mail without a link is better than a failed send.
+export async function buildUnsubscribeUrl(config, origin, recipient, scope) {
+    if (recipient.kind === "address" && hashUnsubscribeAddress(recipient.address) === undefined) {
+        return undefined;
+    }
+    const token = recipient.kind === "user"
+        ? await signUnsubscribeToken({ ...scope, userId: recipient.userId }, config.secret)
+        : await signAddressUnsubscribeToken({ ...scope, address: recipient.address }, config.secret);
+    return `${origin}${DELIVERY_UNSUBSCRIBE_PATH}?token=${encodeURIComponent(token)}`;
+}

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

@@ -0,0 +1,11 @@
+export declare const UNSUBSCRIBE_PAGE_EN: {
+    readonly "mail.unsubscribe.confirmTitle": "Unsubscribe";
+    readonly "mail.unsubscribe.confirmQuestion": "Unsubscribe from these emails?";
+    readonly "mail.unsubscribe.confirmButton": "Unsubscribe";
+    readonly "mail.unsubscribe.doneTitle": "Unsubscribed";
+    readonly "mail.unsubscribe.doneMessage": "You have been unsubscribed.";
+    readonly "mail.unsubscribe.undoButton": "Undo";
+    readonly "mail.unsubscribe.resubscribedTitle": "Subscribed again";
+    readonly "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.";
+    readonly "mail.unsubscribe.failed": "That did not work. Please try again later.";
+};

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

@@ -0,0 +1,15 @@
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
+// The pages behind a mailed unsubscribe link speak the mail's language, so their texts live in
+// the mail translations: English here, other languages in the locale packages.
+export const UNSUBSCRIBE_PAGE_EN = {
+    "mail.unsubscribe.confirmTitle": "Unsubscribe",
+    "mail.unsubscribe.confirmQuestion": "Unsubscribe from these emails?",
+    "mail.unsubscribe.confirmButton": "Unsubscribe",
+    "mail.unsubscribe.doneTitle": "Unsubscribed",
+    "mail.unsubscribe.doneMessage": "You have been unsubscribed.",
+    "mail.unsubscribe.undoButton": "Undo",
+    "mail.unsubscribe.resubscribedTitle": "Subscribed again",
+    "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.",
+    "mail.unsubscribe.failed": "That did not work. Please try again later.",
+};
+registerMailTranslations("en", UNSUBSCRIBE_PAGE_EN);

package/dist/delivery/unsubscribe.d.ts

@@ -1,16 +1,19 @@
 import { type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import "./unsubscribe-page-strings.js";
 export type UnsubscribeTokenPayload = {
     readonly userId: string;
     readonly tenantId: TenantId;
     readonly notificationType: string;
     readonly channel: string;
+    readonly locale?: string | undefined;
 };
 export type AddressUnsubscribeTokenPayload = {
     readonly tenantId: TenantId;
     readonly address: string;
     readonly notificationType: string;
     readonly channel: string;
+    readonly locale?: string | undefined;
 };
 /**
  * `secret` must be a value dedicated to unsubscribe-token signing — do NOT

package/dist/delivery/unsubscribe.js

@@ -1,10 +1,18 @@
 import { ExtraRouteRejection, signatureRoute, } from "@cosmicdrift/kumiko-framework/api";
+import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
 import * as z from "zod";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { DELIVERY_RESUBSCRIBE_PATH, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, } from "./constants.js";
+import "./unsubscribe-page-strings.js";
+// The mail's locale, so the pages behind the link speak the mail's language. Optional: links
+// signed before the claim existed keep verifying and fall back to English.
+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.
 //
@@ -19,6 +27,7 @@ const unsubscribeJwtPayloadSchema = z.object({
     tenantId: z.string().min(1),
     notificationType: z.string().min(1),
     channel: z.string().min(1),
+    locale: localeClaimSchema,
 });
 // Address-token payload. `sub` and `addressHash` are the same value (the
 // subject claim IS the blind-index hash) — kept as two fields because the
@@ -31,6 +40,7 @@ const addressUnsubscribeJwtPayloadSchema = z.object({
     notificationType: z.string().min(1),
     channel: z.string().min(1),
     addressHash: z.string().min(1),
+    locale: localeClaimSchema,
 });
 const UNSUBSCRIBE_EXPIRY = "7d";
 const RESUBSCRIBE_EXPIRY = "1h";
@@ -42,6 +52,10 @@ function assertUnsubscribeSecret(secret, caller) {
         throw new Error(`${caller}: secret must be ≥${MIN_UNSUBSCRIBE_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`);
     }
 }
+// An unusable locale is left out instead of failing the send; the pages then fall back to English.
+function localeClaim(locale) {
+    return locale !== undefined && localeClaimSchema.safeParse(locale).success ? { locale } : {};
+}
 const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
     error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
 };
@@ -52,6 +66,7 @@ export async function signUnsubscribeToken(payload, secret) {
         tenantId: payload.tenantId,
         notificationType: payload.notificationType,
         channel: payload.channel,
+        ...localeClaim(payload.locale),
     })
         .setProtectedHeader({ alg: "HS256" })
         .setSubject(String(payload.userId))
@@ -80,6 +95,7 @@ export async function signAddressUnsubscribeToken(payload, secret) {
         channel: payload.channel,
         addressHash,
         kind: "address",
+        ...localeClaim(payload.locale),
     })
         .setProtectedHeader({ alg: "HS256" })
         .setSubject(addressHash)
@@ -104,6 +120,7 @@ async function signResubscribeToken(verified, encodedSecret) {
         tenantId: verified.tenantId,
         notificationType: verified.notificationType,
         channel: verified.channel,
+        ...localeClaim(verified.locale),
     };
     const jwt = verified.kind === "address"
         ? new jose.SignJWT({
@@ -154,6 +171,7 @@ async function verifyUnsubscribeToken(token, encodedSecret, purpose) {
                 addressHash: parsed.addressHash,
                 notificationType: parsed.notificationType,
                 channel: parsed.channel,
+                locale: parsed.locale,
             };
         }
         const userAttempt = unsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
@@ -169,6 +187,7 @@ async function verifyUnsubscribeToken(token, encodedSecret, purpose) {
             userId: parsed.sub,
             notificationType: parsed.notificationType,
             channel: parsed.channel,
+            locale: parsed.locale,
         };
     }
     catch (err) {
@@ -228,39 +247,50 @@ async function dispatchResubscribeWrite(verified, deps) {
         return "success";
     return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
 }
-function confirmationPage(token) {
+function pageLocale(locale) {
+    return resolveMailLocale(locale ?? "en");
+}
+function htmlPage(locale, title, bodyHtml) {
     return `<!doctype html>
-<html>
+<html lang="${escapeHtmlAttr(locale)}">
 <head>
 <meta charset="utf-8">
 <meta name="robots" content="noindex">
-<title>Unsubscribe</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtmlAttr(title)}</title>
 </head>
 <body>
-<p>Unsubscribe from these emails?</p>
-<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
-<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
-<button type="submit">Unsubscribe</button>
-</form>
+${bodyHtml}
 </body>
 </html>`;
 }
-function unsubscribedPage(resubscribeToken) {
-    return `<!doctype html>
-<html>
-<head>
-<meta charset="utf-8">
-<meta name="robots" content="noindex">
-<title>Unsubscribed</title>
-</head>
-<body>
-<p>You have been unsubscribed.</p>
+function confirmationPage(token, locale) {
+    const lang = pageLocale(locale);
+    return htmlPage(lang, mailT(lang, "mail.unsubscribe.confirmTitle"), `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmQuestion"))}</p>
+<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmButton"))}</button>
+</form>`);
+}
+function unsubscribedPage(resubscribeToken, locale) {
+    const lang = pageLocale(locale);
+    return htmlPage(lang, mailT(lang, "mail.unsubscribe.doneTitle"), `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.doneMessage"))}</p>
 <form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
 <input type="hidden" name="token" value="${escapeHtmlAttr(resubscribeToken)}">
-<button type="submit">Undo</button>
-</form>
-</body>
-</html>`;
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.undoButton"))}</button>
+</form>`);
+}
+function resubscribedPage(locale) {
+    const lang = pageLocale(locale);
+    return htmlPage(lang, mailT(lang, "mail.unsubscribe.resubscribedTitle"), `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.resubscribedMessage"))}</p>`);
+}
+function failedPage(locale) {
+    const lang = pageLocale(locale);
+    const message = mailT(lang, "mail.unsubscribe.failed");
+    return htmlPage(lang, message, `<p>${escapeHtmlAttr(message)}</p>`);
+}
+function isFormRequest(contentType) {
+    return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
 // One-click clients put the token in the query string; only the
 // confirmation-page form submits it in the body.
@@ -304,10 +334,10 @@ export function createUnsubscribeRoutes(options) {
             if (!token) {
                 throw new ExtraRouteRejection(400, UNSUBSCRIBE_TOKEN_INVALID_BODY, "missing unsubscribe token");
             }
-            await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
-            return { token };
+            const verified = await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
+            return { token, locale: verified.locale };
         },
-        handler: async (c, { token }) => c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
+        handler: async (c, { token, locale }) => c.html(confirmationPage(token, locale), 200, CONFIRMATION_PAGE_HEADERS),
     });
     const writeRoute = signatureRoute({
         method: "POST",
@@ -320,11 +350,9 @@ export function createUnsubscribeRoutes(options) {
             // (e.g. events-table missing, DB down) behind a misleading 400.
             const succeeded = await dispatchUnsubscribeWrite(verified, deps);
             if (!succeeded) {
-                return c.html("Unsubscribe failed", 500, { "Cache-Control": "no-store" });
+                return c.html(failedPage(verified.locale), 500, { "Cache-Control": "no-store" });
             }
-            return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret)), 200, {
-                "Cache-Control": "no-store",
-            });
+            return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret), verified.locale), 200, { "Cache-Control": "no-store" });
         },
     });
     // Undo direction: token only from the JSON/form body, never the query
@@ -337,6 +365,14 @@ export function createUnsubscribeRoutes(options) {
         verify: async (request) => verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
         handler: async (c, verified, deps) => {
             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"
+                    ? c.html(resubscribedPage(verified.locale), 200, { "Cache-Control": "no-store" })
+                    : c.html(failedPage(verified.locale), outcome === "limit_reached" ? 409 : 500, {
+                        "Cache-Control": "no-store",
+                    });
+            }
             if (outcome === "limit_reached") {
                 return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
                     "Cache-Control": "no-store",

package/dist/mail-foundation/feature.d.ts

@@ -1,5 +1,5 @@
 import { type EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
-import { type ConfigAccessor, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type ConfigAccessor, type Registry, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 export declare const MAIL_TRANSPORT_EXTENSION: "mailTransport";
 /**
  * Schmaler Surface-Type fuer Transport-Plugins — gespiegelt von
@@ -69,3 +69,18 @@ export declare const mailFoundationFeature: import("@cosmicdrift/kumiko-types/fe
  *   await transport.send({ to, subject, html });
  */
 export declare function createTransportForTenant(ctx: MailTransportContext, tenantId: string, handlerName?: string): Promise<EmailTransport>;
+/**
+ * Like createTransportForTenant, but an empty `provider` key means "this tenant has no
+ * mail provider" and yields null. Every other problem (unknown provider, plugin build
+ * failure) still throws, so a configured tenant never silently falls back.
+ */
+export declare function createTransportForTenantIfConfigured(ctx: MailTransportContext, tenantId: string, handlerName?: string): Promise<EmailTransport | null>;
+export type TenantMailTransportScope = {
+    readonly tenantId: TenantId;
+    readonly config?: ConfigAccessor | undefined;
+    readonly registry: Registry;
+    readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext | undefined;
+};
+/** The `tenantTransport` resolver for `createChannelEmailFeature`: the tenant's configured
+ *  provider, or null so the channel falls back to its app transport. */
+export declare function tenantMailTransport(scope: TenantMailTransportScope): Promise<EmailTransport | null>;