@cosmicdrift/kumiko-samples 0.366.0 → 0.367.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.366.0",
+  "version": "0.367.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.366.0",
+  "version": "0.367.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Email channel can send through the tenant's own mail provider",
+    "detail": "EmailChannelOptions gets tenantTransport, a resolver called per send with the delivery channel context. mail-foundation exports tenantMailTransport for it: a tenant with a provider configured sends through its own transport, a broken provider fails the send, a tenant without a provider uses the app transport. The transport is built per send and never cached, and the tenant comes from the server-side delivery context only. ChannelContext now carries the tenant's config accessor as config. Without tenantTransport nothing changes."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -164,7 +164,11 @@ async function resolveAttachments(
 }
 
 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 },
@@ -172,7 +176,7 @@ export type EmailChannelOptions = {
 };
 
 export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
-  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)
@@ -209,6 +213,11 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     };
   }
 
+  async function transportFor(ctx: ChannelContext): Promise<EmailTransport> {
+    if (tenantTransport === undefined) return transport;
+    return (await tenantTransport(ctx)) ?? transport;
+  }
+
   return {
     name: EMAIL_CHANNEL_NAME,
     mode: "queued",
@@ -251,7 +260,8 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
         return { status: "failed", error: "send_failed", address };
       }
       const resolvedAttachments = resolution.attachments;
-      await transport.send(
+      const sendTransport = await transportFor(ctx);
+      await sendTransport.send(
         guardEmailMessage({
           to: address,
           subject,

package/packages/bundled-features/src/channel-email/feature.ts

@@ -10,7 +10,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
 
   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.",
+      "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",

package/packages/bundled-features/src/delivery/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Delivery signs unsubscribe links itself",
+    "detail": "r.notification(name, { unsubscribe: true }) makes delivery put a signed data.unsubscribeUrl into every email of that notification when the service has unsubscribeLinks. User recipients get a user token, route recipients an address token (only with a blind-index key, otherwise no link). The token is scoped to tenant, notification and channel; a link the caller passes in data.unsubscribeUrl wins. runProdApp option unsubscribe: { secret } mounts createUnsubscribeRoutes and wires the links; the base URL comes from auth.publicOrigin, auth.mail.baseUrl or APP_BASE_URL, and without one boot warns and no link is added."
+  },
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Unsubscribe links use the tenant's host and the mail's language, apps learn about address opt-outs",
+    "detail": "unsubscribeLinks and the runProdApp option unsubscribe take tenantOrigin, an app callback that returns the sending tenant's own origin (subdomain or custom domain) per send; null, a throw or a non-https value fall back to the app origin and never fail the send. The signed token now carries the mail's locale (notify option locale), so the confirmation, result and undo pages render in that language; tokens without it keep working and show English. A form post to the resubscribe route now answers with an HTML page, JSON callers are unchanged. After a committed address opt-out an app job declared with trigger on DeliveryHandlers.unsubscribeAddress receives addressHash, notificationType and channel (unsubscribeAddressPayloadSchema) with the tenant in ctx.triggeredBy.tenantId; hashUnsubscribeAddress(email) matches it to the app's own subscriber. UNSUBSCRIBE_PAGE_EN exports the English page texts, German and Spanish come with the locale packages."
+  },
   {
     "version": "0.366.0",
     "type": "improvement",

package/packages/bundled-features/src/delivery/channel-context.ts

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

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -37,6 +37,7 @@ import {
   DeliveryJobs,
   deliveryIdempotencyRedisKey,
   deliveryPriorityRank,
+  EMAIL_CHANNEL_NAME,
 } from "./constants.js";
 import {
   type AddressOptOutKey,
@@ -55,6 +56,12 @@ import {
   isDeliveryChannelPlugin,
   type RenderedMessage,
 } from "./types.js";
+import {
+  buildUnsubscribeUrl,
+  type UnsubscribeLinkConfig,
+  type UnsubscribeLinkRecipient,
+  unsubscribeLinkOrigin,
+} from "./unsubscribe-link.js";
 
 export function redactedMessageOf(err: unknown): string {
   return redactErrorText(err instanceof Error ? err.message : String(err));
@@ -97,6 +104,9 @@ export type DeliveryServiceOptions = {
   // absent means an unattributed warn log (see fallbackEscapeHatchReporter).
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly log?: Logger;
+  // Signs `data.unsubscribeUrl` for email notifications declared with `unsubscribe: true`.
+  // The secret must be the one `createUnsubscribeRoutes` verifies with.
+  readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 
 // Build channel list from registry extension usages
@@ -128,6 +138,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantConfigFor,
     escapeHatchAuditSink,
     log,
+    unsubscribeLinks,
   } = options;
   const idemRedis = idempotencyRedis ?? rateLimit?.redis;
   const logError = createFallbackLogger("delivery", log);
@@ -454,6 +465,37 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
   }
 
+  // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
+  // context, never from the notification data.
+  async function withUnsubscribeUrl(
+    message: ChannelMessage,
+    channelName: string,
+    recipient: UnsubscribeLinkRecipient,
+    channelCtx: ChannelContext,
+  ): Promise<ChannelMessage> {
+    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: string,
     data: Readonly<Record<string, unknown>> | undefined,
@@ -744,7 +786,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           run,
           channel,
           address,
-          message,
+          message: await withUnsubscribeUrl(
+            message,
+            channel.name,
+            { kind: "user", userId },
+            channelCtx,
+          ),
           channelCtx,
           tenantId,
           recipientId: userId,
@@ -842,7 +889,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           run,
           channel,
           address,
-          message,
+          message: await withUnsubscribeUrl(
+            message,
+            channel.name,
+            { kind: "address", address },
+            channelCtx,
+          ),
           channelCtx,
           tenantId,
           recipientId,

package/packages/bundled-features/src/delivery/feature.ts

@@ -61,7 +61,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
   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.',
+      "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",

package/packages/bundled-features/src/delivery/handlers/unsubscribe-address.write.ts

@@ -4,13 +4,18 @@ 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 type UnsubscribeAddressPayload = z.infer<typeof unsubscribeAddressPayloadSchema>;
+
 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/packages/bundled-features/src/delivery/index.ts

@@ -63,6 +63,10 @@ export {
   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,
@@ -94,3 +98,5 @@ export {
   type UnsubscribeRouteOptions,
   type UnsubscribeTokenPayload,
 } from "./unsubscribe.js";
+export type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
+export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/packages/bundled-features/src/delivery/testing.ts

@@ -15,6 +15,7 @@ import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.js"
 import { collectChannels, createDeliveryService } from "./delivery-service.js";
 import { createDeliveryNotifyFactory } from "./notify-factory.js";
 import type { DeliveryService } from "./types.js";
+import type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
 
 export type CreateDeliveryTestContextOptions = {
   readonly tenantUserIdsQuery?: string;
@@ -27,6 +28,7 @@ export type CreateDeliveryTestContextOptions = {
   readonly idempotencyRedis?: Redis;
   readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
   readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
+  readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 
 /**

package/packages/bundled-features/src/delivery/types.ts

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  ConfigAccessor,
   DeliveryErrorCode,
   NotifyDeliveryStatus,
   NotifyDispatched,
@@ -39,6 +40,9 @@ export type ChannelContext = {
   // Chat channels read their per-tenant webhook URL / bot token from it.
   // Absent when no secrets feature/KEK is wired.
   readonly secrets?: SecretsContext | undefined;
+  // The tenant's own config accessor, built server-side for this tenantId. Absent when the
+  // delivery service has no tenantConfigFor and the job context carries no config.
+  readonly config?: ConfigAccessor | undefined;
   // Renders a stored mail template, the tenant's own or the system fallback.
   readonly renderMail?: (payload: MailPayload) => Promise<RenderedMail>;
   // Reads the bytes behind an attachment ref at send time. Absent when no file storage is wired.

package/packages/bundled-features/src/delivery/unsubscribe-link.ts

@@ -0,0 +1,73 @@
+import { publicOriginOf } from "@cosmicdrift/kumiko-framework/api";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import { DELIVERY_UNSUBSCRIBE_PATH } from "./constants.js";
+import type { ChannelContext } from "./types.js";
+import { signAddressUnsubscribeToken, signUnsubscribeToken } from "./unsubscribe.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 };
+
+// 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: string, baseUrl: string): boolean {
+  return (
+    origin.startsWith("https://") || (baseUrl.startsWith("http://") && origin.startsWith("http://"))
+  );
+}
+
+export async function unsubscribeLinkOrigin(
+  config: UnsubscribeLinkConfig,
+  ctx: ChannelContext,
+  onFallback: (reason: string) => void,
+): Promise<string> {
+  if (config.tenantOrigin === undefined) return config.baseUrl;
+  let resolved: string | null | undefined;
+  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: UnsubscribeLinkConfig,
+  origin: string,
+  recipient: UnsubscribeLinkRecipient,
+  scope: {
+    tenantId: TenantId;
+    notificationType: string;
+    channel: string;
+    locale: string | undefined;
+  },
+): Promise<string | undefined> {
+  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/packages/bundled-features/src/delivery/unsubscribe-page-strings.ts

@@ -0,0 +1,17 @@
+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.",
+} as const;
+
+registerMailTranslations("en", UNSUBSCRIBE_PAGE_EN);