@cosmicdrift/kumiko-bundled-features 0.312.0 → 0.313.0

package/src/data-retention/run-retention-cleanup.ts

@@ -39,16 +39,27 @@
 // einzelnen Page — sonst verstopfen erledigte Rows das batchLimit-Fenster.
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  isSelfPiiField,
+  type KmsAdapter,
+  resolveSubjectForField,
+  type SubjectId,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import {
   createEventStoreExecutor,
   createTenantDb,
   type DbRunner,
+  nullBlindIndexesForSubject,
   type TenantDb,
   type WhereObject,
 } from "@cosmicdrift/kumiko-framework/db";
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   createSystemUser,
+  type EntityDefinition,
   type EntityId,
   type Registry,
   type SessionUser,
@@ -59,6 +70,7 @@ import {
   fileRefEntity,
   fileRefsTable,
 } from "@cosmicdrift/kumiko-framework/files";
+import { runInSubTransaction } from "../shared";
 import { computeCutoff, type Instant } from "./keep-for";
 import type { RetentionPresetKey } from "./presets";
 import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant";
@@ -92,6 +104,11 @@ export interface RunRetentionCleanupArgs {
    *  Missing while fileRefs are due → the row stays (skipped "missing_file_storage"),
    *  fail-closed instead of orphaning bytes. */
   readonly files?: FileContext;
+  /** KMS for erasing a hardDeleted row's own subject key (Refs #2057). Defaults
+   *  to configuredPiiSubjectKms() (same fallback as run-forget-cleanup.ts);
+   *  undefined/no-KMS-configured skips erasure entirely — the row is still
+   *  hard-deleted, only crypto-shredding of its DEK is not attempted. */
+  readonly kms?: KmsAdapter;
 }
 
 export interface RetentionCleanupSkip {
@@ -131,6 +148,110 @@ async function purgeMatchingRows(
   return count;
 }
 
+// --- hardDelete crypto-shredding (Refs #2057) ---
+//
+// recordOwned/self-pii resolution (subject-resolver.ts) only ever reads
+// `row.id` for these two kinds — resolveRecordSubject uses opts.entityName +
+// row.id, resolveSelfPiiSubject uses row.id alone — so a `{ id }`-shaped row
+// (purgeMatchingRows's hardDelete select) is enough; the with-files path's
+// full row works the same way.
+//
+// userOwned/tenantOwned are explicitly excluded: hardDelete only destroys
+// THIS row's own data, but the owning user's/tenant's key may still protect
+// OTHER live rows that reference the same subject — erasing it here would
+// be a silent cross-row data-loss bug, not a retention fix.
+function collectHardDeleteEraseSubjects(
+  entity: EntityDefinition,
+  entityName: string,
+  tenantId: TenantId,
+  row: Record<string, unknown>,
+): readonly SubjectId[] {
+  const subjectsByKey = new Map<string, SubjectId>();
+  for (const fieldName of collectPiiSubjectFields(entity)) {
+    const field = entity.fields[fieldName];
+    if (!field) continue;
+    const isRecordOwned = "recordOwned" in field && field.recordOwned === true;
+    const isUserOwned = "userOwned" in field && field.userOwned !== undefined;
+    const isTenantOwned = "tenantOwned" in field && field.tenantOwned === true;
+    if (isUserOwned || isTenantOwned) continue; // never erase — see header comment
+    if (!isRecordOwned && !isSelfPiiField(field)) continue;
+    const subject = resolveSubjectForField(entity, fieldName, row, { tenantId, entityName });
+    if (subject) subjectsByKey.set(subjectIdToKey(subject), subject);
+  }
+  return Array.from(subjectsByKey.values());
+}
+
+// Erases the row's own recordOwned/self-pii subject key(s) + sweeps their
+// blind indexes. Called from INSIDE the same sub-transaction as the row's forget
+// (see forgetRowAndEraseKeys) — an eraseKey throw rolls the forget back too,
+// same crash-safety contract as run-forget-cleanup.ts:477-503 (eraseKey is
+// contractually idempotent per KmsAdapter, so a retried run re-erases safely).
+async function eraseHardDeletedRowKeys(args: {
+  readonly kms: KmsAdapter | undefined;
+  readonly tx: DbRunner;
+  readonly registry: Registry;
+  readonly entity: EntityDefinition;
+  readonly entityName: string;
+  readonly tenantId: TenantId;
+  readonly row: Record<string, unknown>;
+}): Promise<void> {
+  // skip: no KMS adapter, so there are no per-subject keys to erase
+  if (!args.kms) return;
+  const subjects = collectHardDeleteEraseSubjects(
+    args.entity,
+    args.entityName,
+    args.tenantId,
+    args.row,
+  );
+  for (const subject of subjects) {
+    await args.kms.eraseKey(subject, {
+      requestId: `data-retention:hardDelete:${args.entityName}:${String(args.row["id"])}`,
+      eraseReason: "data-retention:hardDelete",
+    });
+    await nullBlindIndexesForSubject(args.tx, args.registry.features, subjectIdToKey(subject));
+  }
+}
+
+// Shared by both hardDelete paths (purgeMatchingRows's op below and
+// purgeHardDeleteRowWithFiles) so the erase-after-forget ordering can't be
+// forgotten on either one. Wraps the executor's own forget() (which already
+// opens its own nested savepoints) in one sub-transaction that also covers
+// eraseKey + the blind-index sweep — a KMS failure rolls the whole row back,
+// not just the forget. The retention job hands in a pool connection, so this
+// must open a real BEGIN there; a savepoint-if-supported helper would run
+// unconfined and leave the row gone with its key still live.
+async function forgetRowAndEraseKeys(args: {
+  readonly db: DbRunner;
+  readonly executor: ReturnType<typeof createEventStoreExecutor>;
+  readonly entity: EntityDefinition;
+  readonly entityName: string;
+  readonly tenantId: TenantId;
+  readonly systemUser: SessionUser;
+  readonly row: Record<string, unknown>;
+  readonly kms: KmsAdapter | undefined;
+  readonly registry: Registry;
+}): Promise<{ readonly isSuccess: boolean }> {
+  return runInSubTransaction(args.db, async (sp) => {
+    const tdb = createTenantDb(sp, args.tenantId, "system");
+    const result = await args.executor.forget(
+      { id: args.row["id"] as EntityId },
+      args.systemUser,
+      tdb,
+    );
+    if (!result.isSuccess) return { isSuccess: false };
+    await eraseHardDeletedRowKeys({
+      kms: args.kms,
+      tx: sp,
+      registry: args.registry,
+      entity: args.entity,
+      entityName: args.entityName,
+      tenantId: args.tenantId,
+      row: args.row,
+    });
+    return { isSuccess: true };
+  });
+}
+
 // --- hardDelete + file-fields (kumiko-framework#3089) ---
 
 type FileFieldPlan = {
@@ -240,6 +361,7 @@ async function purgeHardDeleteRowWithFiles(args: {
   readonly tableHasTenantId: boolean;
   readonly tenantId: TenantId;
   readonly entityName: string;
+  readonly entity: EntityDefinition;
   readonly row: Record<string, unknown>;
   readonly plan: FileFieldPlan;
   readonly files: FileContext | undefined;
@@ -247,9 +369,23 @@ async function purgeHardDeleteRowWithFiles(args: {
   readonly fileRefExecutor: ReturnType<typeof createEventStoreExecutor>;
   readonly systemUser: SessionUser;
   readonly tdb: TenantDb;
+  readonly kms: KmsAdapter | undefined;
+  readonly registry: Registry;
   readonly onSkip: (reason: "missing_file_storage" | "file_delete_failed") => void;
 }): Promise<boolean> {
   const rowId = String(args.row["id"]);
+  const forgetEntityRow = () =>
+    forgetRowAndEraseKeys({
+      db: args.db,
+      executor: args.entityExecutor,
+      entity: args.entity,
+      entityName: args.entityName,
+      tenantId: args.tenantId,
+      systemUser: args.systemUser,
+      row: args.row,
+      kms: args.kms,
+      registry: args.registry,
+    });
   const fileRefIds = await collectFileRefIds(
     args.db,
     args.tenantId,
@@ -258,13 +394,7 @@ async function purgeHardDeleteRowWithFiles(args: {
     args.plan,
   );
   if (fileRefIds.length === 0) {
-    return (
-      await args.entityExecutor.forget(
-        { id: args.row["id"] as EntityId },
-        args.systemUser,
-        args.tdb,
-      )
-    ).isSuccess;
+    return (await forgetEntityRow()).isSuccess;
   }
 
   const fileRefRows = await selectMany<Record<string, unknown>>(args.db, fileRefsTable, {
@@ -289,13 +419,7 @@ async function purgeHardDeleteRowWithFiles(args: {
   }
 
   if (toDelete.length === 0) {
-    return (
-      await args.entityExecutor.forget(
-        { id: args.row["id"] as EntityId },
-        args.systemUser,
-        args.tdb,
-      )
-    ).isSuccess;
+    return (await forgetEntityRow()).isSuccess;
   }
 
   if (!args.files) {
@@ -339,9 +463,7 @@ async function purgeHardDeleteRowWithFiles(args: {
     }
   }
 
-  return (
-    await args.entityExecutor.forget({ id: args.row["id"] as EntityId }, args.systemUser, args.tdb)
-  ).isSuccess;
+  return (await forgetEntityRow()).isSuccess;
 }
 
 // hardDelete page for an entity WITH file/image/files/images fields — loads
@@ -356,12 +478,15 @@ async function purgeHardDeleteRowsWithFiles(args: {
   readonly batchLimit: number;
   readonly tenantId: TenantId;
   readonly entityName: string;
+  readonly entity: EntityDefinition;
   readonly plan: FileFieldPlan;
   readonly files: FileContext | undefined;
   readonly entityExecutor: ReturnType<typeof createEventStoreExecutor>;
   readonly fileRefExecutor: ReturnType<typeof createEventStoreExecutor>;
   readonly systemUser: SessionUser;
   readonly tdb: TenantDb;
+  readonly kms: KmsAdapter | undefined;
+  readonly registry: Registry;
   readonly skipped: RetentionCleanupSkip[];
 }): Promise<number> {
   const rows = await selectMany<Record<string, unknown>>(args.db, args.table, args.where, {
@@ -383,6 +508,7 @@ async function purgeHardDeleteRowsWithFiles(args: {
       tableHasTenantId: args.tableHasTenantId,
       tenantId: args.tenantId,
       entityName: args.entityName,
+      entity: args.entity,
       row,
       plan: args.plan,
       files: args.files,
@@ -390,6 +516,8 @@ async function purgeHardDeleteRowsWithFiles(args: {
       fileRefExecutor: args.fileRefExecutor,
       systemUser: args.systemUser,
       tdb: args.tdb,
+      kms: args.kms,
+      registry: args.registry,
       onSkip,
     });
     if (ok) count++;
@@ -461,6 +589,7 @@ export async function runRetentionCleanup(
 ): Promise<RunRetentionCleanupResult> {
   const { db, registry, tenantId, tenantPreset, now } = args;
   const batchLimit = args.batchLimit ?? DEFAULT_BATCH_LIMIT;
+  const kms = args.kms ?? configuredPiiSubjectKms();
 
   let hardDeleted = 0;
   let softDeleted = 0;
@@ -531,7 +660,17 @@ export async function runRetentionCleanup(
         const filePlan = planFileFields(entity.fields);
         if (filePlan.singleFields.length === 0 && filePlan.multiFields.length === 0) {
           hardDeleted += await purgeMatchingRows(db, proj.table, where, batchLimit, (id) =>
-            executor.forget({ id }, systemUser, tdb),
+            forgetRowAndEraseKeys({
+              db,
+              executor,
+              entity,
+              entityName,
+              tenantId,
+              systemUser,
+              row: { id },
+              kms,
+              registry,
+            }),
           );
           break;
         }
@@ -546,12 +685,15 @@ export async function runRetentionCleanup(
           batchLimit,
           tenantId,
           entityName,
+          entity,
           plan: filePlan,
           files: args.files,
           entityExecutor: executor,
           fileRefExecutor,
           systemUser,
           tdb,
+          kms,
+          registry,
           skipped,
         });
         break;

package/src/delivery/__tests__/delivery.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configureBlindIndexKey } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildEntityTable,
@@ -26,7 +27,8 @@ import {
   testTenantId,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { resetBlindIndexKeyForTests, waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import * as jose from "jose";
 import * as z from "zod";
 import { createChannelEmailFeature } from "../../channel-email/feature";
 import { createInMemoryTransport, type EmailMessage } from "../../channel-email/types";
@@ -49,10 +51,18 @@ import { DeliveryHandlers, DeliveryJobs, DeliveryQueries } from "../constants";
 import { collectChannels, createDeliveryService } from "../delivery-service";
 import { createDeliveryFeature } from "../feature";
 import { deliveryRenderJob, deliverySendJob } from "../jobs";
-import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
+import {
+  deliveryAttemptsTable,
+  notificationAddressOptOutsTable,
+  notificationPreferencesTable,
+} from "../tables";
 import { createDeliveryTestContext } from "../testing";
 import type { DeliveryService } from "../types";
-import { createUnsubscribeRoute, signUnsubscribeToken } from "../unsubscribe";
+import {
+  createUnsubscribeRoute,
+  signAddressUnsubscribeToken,
+  signUnsubscribeToken,
+} from "../unsubscribe";
 
 // --- Setup ---
 
@@ -371,6 +381,7 @@ beforeAll(async () => {
     configValuesTable,
     tenantMembershipsTable,
     notificationPreferencesTable,
+    notificationAddressOptOutsTable,
     inAppMessagesTable,
     ticketTable,
   });
@@ -1821,3 +1832,195 @@ describe("flow 18: priority → job priority mapping", () => {
     expect(normal as number).toBeLessThan(low as number);
   });
 });
+
+// --- Flow 19: address unsubscribe — recipient with no user account ---
+
+describe("flow 19: address unsubscribe (route-based sends, no user account)", () => {
+  const ADDRESS_BIDX_KEY = Buffer.alloc(32, 3).toString("base64");
+  const FOREIGN_JWT_SECRET = "not-the-real-stack-secret-32-characters!";
+
+  beforeAll(() => {
+    configureBlindIndexKey(ADDRESS_BIDX_KEY);
+  });
+
+  afterAll(() => {
+    resetBlindIndexKeyForTests();
+  });
+
+  test("unsubscribe link opts the address out; same type/channel is skipped afterwards", async () => {
+    const address = "flow19-recipient@test.com";
+
+    await deliveryService.notify(
+      "app:notify:address-unsub-19a",
+      { route: { email: address }, data: { title: "X", body: "X" } },
+      admin,
+      admin.tenantId,
+    );
+    const sentBefore = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:address-unsub-19a",
+      recipientAddress: address,
+    });
+    expect(sentBefore.every((l) => l["status"] === "sent")).toBe(true);
+    expect(sentBefore.length).toBeGreaterThan(0);
+
+    // Sign with a mixed-case, padded variant of the same address — proves
+    // normalization (trim + lowercase) happens before hashing, not just
+    // exact string matches.
+    const token = await signAddressUnsubscribeToken(
+      {
+        tenantId: admin.tenantId,
+        address: `  ${address.toUpperCase()}  `,
+        notificationType: "app:notify:address-unsub-19a",
+        channel: "email",
+      },
+      JWT_SECRET,
+    );
+    const res = await stack.app.request(`/delivery/unsubscribe?token=${token}`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("unsubscribed");
+
+    // Clicking twice must stay a no-op (one row, no crash).
+    const res2 = await stack.app.request(`/delivery/unsubscribe?token=${token}`);
+    expect(res2.status).toBe(200);
+    const optOutRows = await selectMany(db, notificationAddressOptOutsTable, {
+      notificationType: "app:notify:address-unsub-19a",
+      channel: "email",
+    });
+    expect(optOutRows).toHaveLength(1);
+
+    await deliveryService.notify(
+      "app:notify:address-unsub-19a",
+      { route: { email: address }, data: { title: "Second", body: "Second" } },
+      admin,
+      admin.tenantId,
+    );
+    const skipped = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:address-unsub-19a",
+      status: "skipped",
+      error: "unsubscribed",
+    });
+    expect(skipped.length).toBeGreaterThanOrEqual(1);
+    expect(skipped.every((l) => l["recipientAddress"] === null)).toBe(true);
+
+    // A different notificationType for the same address is unaffected.
+    await deliveryService.notify(
+      "app:notify:address-unsub-19b",
+      { route: { email: address }, data: { title: "Other type", body: "X" } },
+      admin,
+      admin.tenantId,
+    );
+    const otherTypeLogs = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:address-unsub-19b",
+      recipientAddress: address,
+    });
+    expect(otherTypeLogs.some((l) => l["status"] === "sent")).toBe(true);
+
+    // Critical priority is never suppressed, same rule as user preferences.
+    await deliveryService.notify(
+      "app:notify:address-unsub-19a",
+      {
+        route: { email: address },
+        data: { title: "Critical", body: "X" },
+        priority: "critical",
+      },
+      admin,
+      admin.tenantId,
+    );
+    const criticalLogs = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:address-unsub-19a",
+      recipientAddress: address,
+      priority: "critical",
+    });
+    expect(criticalLogs.some((l) => l["status"] === "sent")).toBe(true);
+  });
+
+  test("tampered token (wrong secret) is rejected and creates no opt-out row", async () => {
+    const address = "flow19-tampered@test.com";
+    const forgedToken = await signAddressUnsubscribeToken(
+      {
+        tenantId: admin.tenantId,
+        address,
+        notificationType: "app:notify:address-unsub-19c",
+        channel: "email",
+      },
+      FOREIGN_JWT_SECRET,
+    );
+
+    const res = await stack.app.request(`/delivery/unsubscribe?token=${forgedToken}`);
+    expect(res.status).toBe(400);
+
+    const rows = await selectMany(db, notificationAddressOptOutsTable, {
+      notificationType: "app:notify:address-unsub-19c",
+      channel: "email",
+    });
+    expect(rows).toHaveLength(0);
+  });
+
+  test("signed token payload carries the address hash, never the plaintext address", async () => {
+    const address = "flow19-no-plaintext@test.com";
+    const token = await signAddressUnsubscribeToken(
+      {
+        tenantId: admin.tenantId,
+        address,
+        notificationType: "app:notify:address-unsub-19d",
+        channel: "email",
+      },
+      JWT_SECRET,
+    );
+
+    const payload = jose.decodeJwt(token);
+    expect(payload["kind"]).toBe("address");
+    expect(typeof payload["addressHash"]).toBe("string");
+    expect(payload["addressHash"]).not.toBe(address);
+    expect(JSON.stringify(payload)).not.toContain(address);
+  });
+
+  test("opt-out is tenant-scoped: the same address in another tenant is unaffected", async () => {
+    const address = "flow19-cross-tenant@test.com";
+    const otherTenantId = testTenantId(915777);
+
+    const token = await signAddressUnsubscribeToken(
+      {
+        tenantId: admin.tenantId,
+        address,
+        notificationType: "app:notify:address-unsub-19e",
+        channel: "email",
+      },
+      JWT_SECRET,
+    );
+    const res = await stack.app.request(`/delivery/unsubscribe?token=${token}`);
+    expect(res.status).toBe(200);
+
+    await deliveryService.notify(
+      "app:notify:address-unsub-19e",
+      { route: { email: address }, data: { title: "X", body: "X" } },
+      admin,
+      otherTenantId,
+    );
+    const otherTenantLogs = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:address-unsub-19e",
+      recipientAddress: address,
+      tenantId: otherTenantId,
+    });
+    expect(otherTenantLogs.some((l) => l["status"] === "sent")).toBe(true);
+  });
+
+  test("signAddressUnsubscribeToken throws when no blind-index key is configured", async () => {
+    resetBlindIndexKeyForTests();
+    try {
+      await expect(
+        signAddressUnsubscribeToken(
+          {
+            tenantId: admin.tenantId,
+            address: "no-key-configured@test.com",
+            notificationType: "app:notify:address-unsub-19f",
+            channel: "email",
+          },
+          JWT_SECRET,
+        ),
+      ).rejects.toThrow(/blind-index key/);
+    } finally {
+      configureBlindIndexKey(ADDRESS_BIDX_KEY);
+    }
+  });
+});

package/src/delivery/address-opt-out.ts

@@ -0,0 +1,87 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { computeBlindIndex, configuredBlindIndexKey } from "@cosmicdrift/kumiko-framework/crypto";
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { notificationAddressOptOutEntity, notificationAddressOptOutsTable } from "./tables";
+import { isUniqueViolation } from "./upsert-preference";
+
+const executor = createEventStoreExecutor(
+  notificationAddressOptOutsTable,
+  notificationAddressOptOutEntity,
+  { entityName: "notification-address-opt-out" },
+);
+
+// Keyed hash of a recipient address that never had a user account — the
+// plaintext address must never reach the opt-out row or the unsubscribe token.
+// Undefined when no blind-index key is configured: there is nothing to
+// compare against, so callers must treat that as "can't tell".
+export function hashUnsubscribeAddress(address: string): string | undefined {
+  const key = configuredBlindIndexKey();
+  if (key === undefined) return undefined;
+  return computeBlindIndex(key, address.trim().toLowerCase());
+}
+
+export type UpsertAddressOptOutInput = {
+  readonly tenantId: TenantId;
+  readonly addressHash: string;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
+type OptOutLookupRow = { readonly id: string };
+
+async function lookup(
+  db: TenantDb,
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+): Promise<OptOutLookupRow | undefined> {
+  return fetchOne<OptOutLookupRow>(db, notificationAddressOptOutsTable, {
+    tenantId,
+    addressHash,
+    notificationType,
+    channel,
+  });
+}
+
+/**
+ * Create-or-noop: opting the same address out twice must not produce a
+ * second row or fail the second click. There is no update path — unlike
+ * user preferences an address opt-out has no `enabled` flag to flip back.
+ */
+export async function upsertAddressOptOut(
+  db: TenantDb,
+  actor: SessionUser,
+  input: UpsertAddressOptOutInput,
+): Promise<WriteResult<UpsertAddressOptOutInput>> {
+  const existing = await lookup(
+    db,
+    input.tenantId,
+    input.addressHash,
+    input.notificationType,
+    input.channel,
+  );
+  if (existing) return { isSuccess: true, data: input };
+
+  try {
+    const result = await executor.create(
+      {
+        addressHash: input.addressHash,
+        notificationType: input.notificationType,
+        channel: input.channel,
+      },
+      actor,
+      db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: input };
+  } catch (err) {
+    // Race-fallback mirrors upsertPreference: another request created the
+    // row between our lookup and executor.create. Nothing to update to —
+    // the existing row already IS the opt-out, so the race loser just
+    // reports success too.
+    if (!isUniqueViolation(err)) throw err;
+    return { isSuccess: true, data: input };
+  }
+}

package/src/delivery/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.313.0",
+    "type": "breaking",
+    "title": "delivery direct sends to a route address can now be unsubscribed via a signed link",
+    "detail": "ctx.notify(type, { route: { email } }) direct sends had no unsubscribe\npath: only sends to a user account with a notification-preference row\ncould opt out, so a recipient with no account could never stop the mail.\nAdded hashUnsubscribeAddress (keyed blind-index hash of the trimmed,\nlowercased address — the plaintext address never reaches the token or\nthe opt-out table), signAddressUnsubscribeToken (HS256 JWT, issuer\n\"kumiko:unsubscribe\", no expiry — a leaked link can only opt one\naddress out of one notificationType/channel, and there is no signed-in\nflow to request a fresh one), and a new notification-address-opt-out\nevent-sourced entity/table. createUnsubscribeRoute now accepts both the\nexisting user token and the new address token on the same route; the\nexisting signUnsubscribeToken and its JWT shape are unchanged. deliverDirect\nnow skips a channel (logDelivery status \"skipped\", error \"unsubscribed\", recipientAddress null)\nwhen the destination address has an opt-out row for that tenant/\nnotificationType/channel, unless priority is \"critical\" — the same rule\nuser-preference suppression already follows. The lookup is skipped\nentirely when no blind-index key is configured.",
+    "migration": "Run `kumiko migrate generate` to add the notification address opt-out table."
+  },
   {
     "version": "0.296.0",
     "type": "breaking",

package/src/delivery/db/queries/address-opt-outs.ts

@@ -0,0 +1,23 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// Exact match only — unlike notification-preferences there is no wildcard
+// ("*") semantics for address opt-outs, the token that creates a row always
+// carries one concrete notificationType/channel pair.
+export async function isAddressOptedOut(
+  db: DbConnection,
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+): Promise<boolean> {
+  const rows = await unsafeReadRetrying<{ readonly id: string }>(
+    db,
+    `SELECT id FROM read_notification_address_opt_outs
+     WHERE tenant_id = $1 AND address_hash = $2 AND notification_type = $3 AND channel = $4
+     LIMIT 1`,
+    [tenantId, addressHash, notificationType, channel],
+  );
+  return rows.length > 0;
+}