@cosmicdrift/kumiko-bundled-features 0.311.0 → 0.313.0

package/src/delivery/delivery-service.ts

@@ -14,9 +14,11 @@ import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipelin
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
+import { hashUnsubscribeAddress } from "./address-opt-out";
 import { appendAttemptEvent, logAttempt } from "./attempt-log";
 import { buildChannelContext } from "./channel-context";
 import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryPriorityRank } from "./constants";
+import { isAddressOptedOut } from "./db/queries/address-opt-outs";
 import { selectNotificationPreferences } from "./db/queries/preferences";
 import {
   type ChannelContext,
@@ -479,6 +481,36 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       const message = buildMessage(notificationType, data, channel.name);
       if (!address) continue;
 
+      // Address opt-out (critical priority skips it, same rule as user
+      // preferences). No blind-index key configured → no hash → nothing to
+      // look up, skip the check instead of failing the send.
+      if (priority !== "critical") {
+        const addressHash = hashUnsubscribeAddress(address);
+        if (addressHash !== undefined) {
+          const optedOut = await isAddressOptedOut(
+            db,
+            tenantId,
+            addressHash,
+            notificationType,
+            channel.name,
+          );
+          if (optedOut) {
+            await logDelivery({
+              tenantId,
+              notificationType,
+              channel: channel.name,
+              recipientId,
+              // The recipient withdrew — suppressed attempts must not keep recording the address.
+              recipientAddress: null,
+              status: "skipped",
+              error: "unsubscribed",
+              priority,
+            });
+            continue;
+          }
+        }
+      }
+
       if (rateLimit) {
         const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
         if (!allowed) {

package/src/delivery/feature.ts

@@ -23,6 +23,8 @@ import { deliveryRenderJob, deliverySendJob } from "./jobs";
 import {
   deliveryAttemptsTable,
   deliveryAttemptsTableMeta,
+  notificationAddressOptOutEntity,
+  notificationAddressOptOutsTable,
   notificationPreferenceEntity,
   notificationPreferencesTable,
 } from "./tables";
@@ -40,7 +42,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
   const resolvedAccess = options?.access ?? access.admin;
   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). It stores per-user channel preferences in the `notification-preference` entity, 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.",
+      "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). 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.",
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",
@@ -56,6 +58,12 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     r.entity("notification-preference", notificationPreferenceEntity, {
       table: notificationPreferencesTable,
     });
+    // Same ride-along reason as notification-preference above: the
+    // (tenant,addressHash,type,channel) uniqueIndex lives only on the
+    // physical table.
+    r.entity("notification-address-opt-out", notificationAddressOptOutEntity, {
+      table: notificationAddressOptOutsTable,
+    });
     r.storeTable(deliveryAttemptsTableMeta, {
       reason: "read_side.delivery_attempt_log",
     });

package/src/delivery/index.ts

@@ -1,3 +1,4 @@
+export { hashUnsubscribeAddress } from "./address-opt-out";
 export type { DeliveryStatusValue } from "./constants";
 export {
   DELIVERY_CHANNEL_EXTENSION,
@@ -19,6 +20,8 @@ export {
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature";
 export {
   deliveryAttemptsTable,
+  notificationAddressOptOutEntity,
+  notificationAddressOptOutsTable,
   notificationPreferenceEntity,
   notificationPreferencesTable,
 } from "./tables";
@@ -38,7 +41,9 @@ export {
   type RendererInput,
 } from "./types";
 export {
+  type AddressUnsubscribeTokenPayload,
   createUnsubscribeRoute,
+  signAddressUnsubscribeToken,
   signUnsubscribeToken,
   type UnsubscribeRouteOptions,
   type UnsubscribeTokenPayload,

package/src/delivery/tables.ts

@@ -105,3 +105,40 @@ export const notificationPreferencesTable = pgTable(
     ),
   ],
 );
+
+// Opt-out for a recipient ADDRESS that has no user account (direct sends via
+// `ctx.notify(type, { route: { email } })`). addressHash is a keyed HMAC
+// (computeBlindIndex over the normalized address) — the plaintext address
+// never reaches this entity or the token that unsubscribes it.
+// A row's mere existence is the opt-out; there is no `enabled` toggle to flip
+// back (re-subscribing a no-account address has no signed-in flow to do it from).
+export const notificationAddressOptOutEntity = createEntity({
+  table: "read_notification_address_opt_outs",
+  fields: {
+    addressHash: createTextField({ required: true, personal: false, reason: "keyed_hash" }),
+    notificationType: createTextField({
+      required: true,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    channel: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+  },
+});
+
+export const notificationAddressOptOutsTable = pgTable(
+  "read_notification_address_opt_outs",
+  {
+    ...buildBaseColumns(false, "uuid"),
+    addressHash: text("address_hash").notNull(),
+    notificationType: text("notification_type").notNull(),
+    channel: text("channel").notNull(),
+  },
+  (table) => [
+    uniqueIndex("read_notification_address_opt_outs_unique").on(
+      table.tenantId,
+      table.addressHash,
+      table.notificationType,
+      table.channel,
+    ),
+  ],
+);

package/src/delivery/unsubscribe.ts

@@ -3,17 +3,38 @@ import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Hono } from "hono";
 import * as jose from "jose";
 import * as z from "zod";
+import { hashUnsubscribeAddress, upsertAddressOptOut } from "./address-opt-out";
 import { upsertPreference } from "./upsert-preference";
 
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+//
+// `kind` is explicitly typed as "absent or undefined, nothing else" here
+// (not bare `.optional()`, which would also accept any other value on an
+// unrelated key) so an address-token payload — which always carries
+// `kind: "address"` — fails this schema instead of silently parsing with
+// `addressHash` mistaken for a userId.
 const unsubscribeJwtPayloadSchema = z.object({
+  kind: z.undefined().optional(),
   sub: z.string().min(1),
   tenantId: z.string().min(1),
   notificationType: z.string().min(1),
   channel: z.string().min(1),
 });
 
+// Address-token payload. `sub` and `addressHash` are the same value (the
+// subject claim IS the blind-index hash) — kept as two fields because the
+// subject claim is jose's own mechanism while `addressHash` is what the
+// route actually writes; the handler cross-checks them below.
+const addressUnsubscribeJwtPayloadSchema = z.object({
+  kind: z.literal("address"),
+  sub: z.string().min(1),
+  tenantId: z.string().min(1),
+  notificationType: z.string().min(1),
+  channel: z.string().min(1),
+  addressHash: z.string().min(1),
+});
+
 export type UnsubscribeTokenPayload = {
   readonly userId: string;
   readonly tenantId: TenantId;
@@ -21,6 +42,13 @@ export type UnsubscribeTokenPayload = {
   readonly channel: string;
 };
 
+export type AddressUnsubscribeTokenPayload = {
+  readonly tenantId: TenantId;
+  readonly address: string;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
 export type UnsubscribeRouteOptions = {
   readonly db: DbConnection;
   readonly jwtSecret: string;
@@ -51,6 +79,45 @@ export async function signUnsubscribeToken(
     .sign(encodedSecret);
 }
 
+/**
+ * Signs an unsubscribe link for a recipient ADDRESS with no user account
+ * (direct sends via `ctx.notify(type, { route: { email } })`). Throws when
+ * no blind-index key is configured — fail closed, since without a key the
+ * opt-out row this token later writes could never be matched against a
+ * future send (the hash wouldn't be reproducible).
+ */
+export async function signAddressUnsubscribeToken(
+  payload: AddressUnsubscribeTokenPayload,
+  secret: string,
+): Promise<string> {
+  const addressHash = hashUnsubscribeAddress(payload.address);
+  if (addressHash === undefined) {
+    throw new Error(
+      "signAddressUnsubscribeToken requires a configured blind-index key (configureBlindIndexKey)",
+    );
+  }
+  const encodedSecret = new TextEncoder().encode(secret);
+  return (
+    new jose.SignJWT({
+      tenantId: payload.tenantId,
+      notificationType: payload.notificationType,
+      channel: payload.channel,
+      addressHash,
+      kind: "address",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setSubject(addressHash)
+      .setIssuer("kumiko:unsubscribe")
+      .setIssuedAt()
+      // No expiry, unlike the user token above: a leaked address token can
+      // only opt that one address out of one notificationType/channel, and
+      // an unsubscribe link mailed out today must keep working indefinitely
+      // — there is no signed-in flow for a no-account address to re-subscribe
+      // or request a fresh link from.
+      .sign(encodedSecret)
+  );
+}
+
 export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): Hono {
   const { db, jwtSecret } = options;
   const encodedSecret = new TextEncoder().encode(jwtSecret);
@@ -62,34 +129,52 @@ export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): Hono {
       return c.text("Missing token", 400);
     }
 
-    let userId: string;
-    let tenantId: TenantId;
-    let notificationType: string;
-    let channel: string;
+    let verifiedPayload: jose.JWTPayload;
     try {
-      const { payload } = await jose.jwtVerify(token, encodedSecret, {
+      ({ payload: verifiedPayload } = await jose.jwtVerify(token, encodedSecret, {
         issuer: "kumiko:unsubscribe",
-      });
-      const parsed = unsubscribeJwtPayloadSchema.parse(payload);
-      userId = parsed.sub;
-      // @cast-boundary engine-bridge — string post-zod → branded TenantId
-      tenantId = parsed.tenantId as TenantId;
-      notificationType = parsed.notificationType;
-      channel = parsed.channel;
+      }));
     } catch {
       return c.text("Invalid or expired token", 400);
     }
 
+    const addressAttempt = addressUnsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
+    if (addressAttempt.success) {
+      const parsed = addressAttempt.data;
+      if (parsed.sub !== parsed.addressHash) {
+        return c.text("Invalid or expired token", 400);
+      }
+      // @cast-boundary engine-bridge — string post-zod → branded TenantId
+      const tenantId = parsed.tenantId as TenantId;
+      const actor = { id: parsed.addressHash, tenantId, roles: SYSTEM_ROLES };
+      const tdb = createTenantDb(db, tenantId, "system");
+      await upsertAddressOptOut(tdb, actor, {
+        tenantId,
+        addressHash: parsed.addressHash,
+        notificationType: parsed.notificationType,
+        channel: parsed.channel,
+      });
+      return c.text("You have been unsubscribed.", 200);
+    }
+
+    const userAttempt = unsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
+    if (!userAttempt.success) {
+      return c.text("Invalid or expired token", 400);
+    }
+    const parsed = userAttempt.data;
+    // @cast-boundary engine-bridge — string post-zod → branded TenantId
+    const tenantId = parsed.tenantId as TenantId;
+
     // Token-verify passed — everything below is a legitimate write. Don't
     // swallow write-errors as "invalid token", that would mask real bugs
     // (e.g. events-table missing, DB down) behind a misleading 400.
-    const actor = { id: userId, tenantId, roles: SYSTEM_ROLES };
+    const actor = { id: parsed.sub, tenantId, roles: SYSTEM_ROLES };
     const tdb = createTenantDb(db, tenantId, "system");
     await upsertPreference(tdb, actor, {
       tenantId,
-      userId,
-      notificationType,
-      channel,
+      userId: parsed.sub,
+      notificationType: parsed.notificationType,
+      channel: parsed.channel,
       enabled: false,
     });
     return c.text("You have been unsubscribed.", 200);

package/src/delivery/upsert-preference.ts

@@ -130,7 +130,7 @@ export async function upsertPreference(
 // (SQLSTATE 23505). Drivers wrap the DB error in varying envelopes; we
 // check the `code` field plus a string-match fallback so the match survives
 // minor driver-version shifts without drifting wide.
-function isUniqueViolation(err: unknown): boolean {
+export function isUniqueViolation(err: unknown): boolean {
   if (typeof err !== "object" || err === null) return false;
   const e = err as { code?: unknown; cause?: { code?: unknown }; message?: unknown }; // @cast-boundary error-details
   if (e.code === "23505") return true;