@cosmicdrift/kumiko-bundled-features 0.313.0 → 0.315.0

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

@@ -47,7 +47,12 @@ import { TenantQueries } from "../../tenant/constants";
 import { createTenantFeature } from "../../tenant/feature";
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 import { tenantEntity } from "../../tenant/schema/tenant";
-import { DeliveryHandlers, DeliveryJobs, DeliveryQueries } from "../constants";
+import {
+  DELIVERY_UNSUBSCRIBE_PATH,
+  DeliveryHandlers,
+  DeliveryJobs,
+  DeliveryQueries,
+} from "../constants";
 import { collectChannels, createDeliveryService } from "../delivery-service";
 import { createDeliveryFeature } from "../feature";
 import { deliveryRenderJob, deliverySendJob } from "../jobs";
@@ -69,7 +74,7 @@ import {
 let stack: TestStack;
 let db: DbConnection;
 let deliveryService: DeliveryService;
-const JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
+const UNSUBSCRIBE_SECRET = "test-stack-unsubscribe-secret-32-chars-min!!";
 
 // Email test infrastructure
 const emailTransport = createInMemoryTransport();
@@ -368,12 +373,10 @@ beforeAll(async () => {
       deliveryService = ctx.deliveryService;
       return ctx;
     },
+    extraRoutes: [createUnsubscribeRoute({ secret: UNSUBSCRIBE_SECRET })],
   });
   db = stack.db;
 
-  // Mount unsubscribe route BEFORE any requests (Hono router locks after first match)
-  stack.app.route("/delivery", createUnsubscribeRoute({ db, jwtSecret: JWT_SECRET }));
-
   // deliveryAttemptsTable is auto-pushed by setupTestStack as MSP-projection-table;
   // notificationPreferencesTable is an ES-entity, so it still needs explicit
   // push here (entity-tables are not auto-provisioned — only projection ones).
@@ -798,10 +801,10 @@ describe("flow 7: unsubscribe endpoint", () => {
         notificationType: "app:notify:announcement",
         channel: "inApp",
       },
-      JWT_SECRET,
+      UNSUBSCRIBE_SECRET,
     );
 
-    const res = await stack.app.request(`/delivery/unsubscribe?token=${token}`);
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`);
     expect(res.status).toBe(200);
     const text = await res.text();
     expect(text).toContain("unsubscribed");
@@ -819,14 +822,100 @@ describe("flow 7: unsubscribe endpoint", () => {
     expect(pref?.["enabled"]).toBe(false);
   });
 
+  test("preference row belongs to the token's userId, not the dispatching system user", async () => {
+    const token = await signUnsubscribeToken(
+      {
+        userId: user1.id,
+        tenantId: user1.tenantId,
+        notificationType: "app:notify:flow7-actor-check",
+        channel: "inApp",
+      },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`);
+    expect(res.status).toBe(200);
+
+    const rows = await selectMany(db, notificationPreferencesTable, {
+      userId: user1.id,
+      notificationType: "app:notify:flow7-actor-check",
+      channel: "inApp",
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["enabled"]).toBe(false);
+  });
+
   test("invalid token returns 400", async () => {
-    const res = await stack.app.request("/delivery/unsubscribe?token=invalid-jwt-token");
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=invalid-jwt-token`);
     expect(res.status).toBe(400);
   });
 
   test("missing token returns 400", async () => {
-    const res = await stack.app.request("/delivery/unsubscribe");
+    const res = await stack.app.request(DELIVERY_UNSUBSCRIBE_PATH);
+    expect(res.status).toBe(400);
+  });
+
+  test("normal user cannot dispatch the unsubscribe write handlers directly", async () => {
+    const error = await stack.http.writeErr(
+      DeliveryHandlers.unsubscribeAddress,
+      { addressHash: "x".repeat(32), notificationType: "app:notify:direct-call", channel: "email" },
+      user1,
+    );
+    expect(error.code).toBe("access_denied");
+
+    const rows = await selectMany(db, notificationAddressOptOutsTable, {
+      notificationType: "app:notify:direct-call",
+      channel: "email",
+    });
+    expect(rows).toHaveLength(0);
+
+    const userError = await stack.http.writeErr(
+      DeliveryHandlers.unsubscribeUser,
+      { userId: user2.id, notificationType: "app:notify:direct-call", channel: "email" },
+      user1,
+    );
+    expect(userError.code).toBe("access_denied");
+
+    const preferenceRows = await selectMany(db, notificationPreferencesTable, {
+      userId: user2.id,
+      notificationType: "app:notify:direct-call",
+    });
+    expect(preferenceRows).toHaveLength(0);
+  });
+
+  test("wrong issuer is rejected with the generic invalid-token code, not a jose error text", async () => {
+    const tamperedIssuer = await new jose.SignJWT({
+      tenantId: user2.tenantId,
+      notificationType: "app:notify:wrong-issuer",
+      channel: "inApp",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setSubject(user2.id)
+      .setIssuer("not-kumiko:unsubscribe")
+      .setIssuedAt()
+      .sign(new TextEncoder().encode(UNSUBSCRIBE_SECRET));
+
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${tamperedIssuer}`);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error?: { code?: string; message?: string } };
+    expect(body.error?.code).toBe("unsubscribe_token_invalid");
+    expect(JSON.stringify(body)).not.toContain("signature verification failed");
+    expect(JSON.stringify(body)).not.toContain("claim");
+
+    const rows = await selectMany(db, notificationPreferencesTable, {
+      userId: user2.id,
+      notificationType: "app:notify:wrong-issuer",
+      channel: "inApp",
+    });
+    expect(rows).toHaveLength(0);
+  });
+
+  test("a real stack session JWT is rejected at the unsubscribe route", async () => {
+    const sessionToken = await stack.jwt.sign(user1);
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${sessionToken}`);
     expect(res.status).toBe(400);
+    const body = (await res.json()) as { error?: { code?: string } };
+    expect(body.error?.code).toBe("unsubscribe_token_invalid");
   });
 });
 
@@ -1481,10 +1570,10 @@ describe("flow 16: repeated unsubscribe clicks are idempotent", () => {
         notificationType: "app:notify:concurrent-unsub",
         channel: "email",
       },
-      JWT_SECRET,
+      UNSUBSCRIBE_SECRET,
     );
 
-    const url = `/delivery/unsubscribe?token=${token}`;
+    const url = `${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`;
     const results = await Promise.all([
       stack.app.request(url),
       stack.app.request(url),
@@ -1873,14 +1962,14 @@ describe("flow 19: address unsubscribe (route-based sends, no user account)", ()
         notificationType: "app:notify:address-unsub-19a",
         channel: "email",
       },
-      JWT_SECRET,
+      UNSUBSCRIBE_SECRET,
     );
-    const res = await stack.app.request(`/delivery/unsubscribe?token=${token}`);
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?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}`);
+    const res2 = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`);
     expect(res2.status).toBe(200);
     const optOutRows = await selectMany(db, notificationAddressOptOutsTable, {
       notificationType: "app:notify:address-unsub-19a",
@@ -1946,7 +2035,7 @@ describe("flow 19: address unsubscribe (route-based sends, no user account)", ()
       FOREIGN_JWT_SECRET,
     );
 
-    const res = await stack.app.request(`/delivery/unsubscribe?token=${forgedToken}`);
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${forgedToken}`);
     expect(res.status).toBe(400);
 
     const rows = await selectMany(db, notificationAddressOptOutsTable, {
@@ -1965,7 +2054,7 @@ describe("flow 19: address unsubscribe (route-based sends, no user account)", ()
         notificationType: "app:notify:address-unsub-19d",
         channel: "email",
       },
-      JWT_SECRET,
+      UNSUBSCRIBE_SECRET,
     );
 
     const payload = jose.decodeJwt(token);
@@ -1986,9 +2075,9 @@ describe("flow 19: address unsubscribe (route-based sends, no user account)", ()
         notificationType: "app:notify:address-unsub-19e",
         channel: "email",
       },
-      JWT_SECRET,
+      UNSUBSCRIBE_SECRET,
     );
-    const res = await stack.app.request(`/delivery/unsubscribe?token=${token}`);
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`);
     expect(res.status).toBe(200);
 
     await deliveryService.notify(
@@ -2016,11 +2105,92 @@ describe("flow 19: address unsubscribe (route-based sends, no user account)", ()
             notificationType: "app:notify:address-unsub-19f",
             channel: "email",
           },
-          JWT_SECRET,
+          UNSUBSCRIBE_SECRET,
         ),
       ).rejects.toThrow(/blind-index key/);
     } finally {
       configureBlindIndexKey(ADDRESS_BIDX_KEY);
     }
   });
+
+  // #3275: deliverToUser must also honor an address opt-out, not just
+  // deliverDirect's route-based sends — the two paths shared the same
+  // isAddressSuppressed check as of this change.
+  test("account send is suppressed when the resolved address has an opt-out row (#3275)", async () => {
+    await stack.redis.redis.del(RATE_KEY_EMAIL);
+    const notificationType = "app:notify:account-unsub-20";
+    const address = testEmail(user1.id);
+
+    const token = await signAddressUnsubscribeToken(
+      { tenantId: user1.tenantId, address, notificationType, channel: "email" },
+      UNSUBSCRIBE_SECRET,
+    );
+    const res = await stack.app.request(`${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`);
+    expect(res.status).toBe(200);
+
+    emailTransport.sent.length = 0;
+    stack.events.reset();
+
+    await stack.http.writeOk(
+      "app:write:send-notification",
+      { notificationType, toUserId: user1.id, title: "Konto-Unsub", body: "X" },
+      admin,
+    );
+
+    expect(emailTransport.sent.some((e) => e.to === address)).toBe(false);
+    const emailLogs = await selectMany(db, deliveryAttemptsTable, {
+      notificationType,
+      recipientId: user1.id,
+      channel: "email",
+    });
+    expect(emailLogs.some((l) => l["status"] === "skipped" && l["error"] === "unsubscribed")).toBe(
+      true,
+    );
+    expect(emailLogs.every((l) => l["recipientAddress"] !== address)).toBe(true);
+
+    // inApp is unaffected — the opt-out is per-channel.
+    const inAppNotifs = stack.events.sse.filter((e) => e.type === "channel-in-app:event:delivered");
+    expect(inAppNotifs.some((e) => e.data["userId"] === user1.id)).toBe(true);
+
+    // Critical priority still gets delivered, same rule as the direct-route path.
+    emailTransport.sent.length = 0;
+    await deliveryService.notify(
+      notificationType,
+      { to: user1.id, data: { title: "Critical", body: "X" }, priority: "critical" },
+      admin,
+      admin.tenantId,
+    );
+    expect(emailTransport.sent.some((e) => e.to === address)).toBe(true);
+  });
+
+  // Address-path counterpart to flow 16 — same deterministic-aggregate-id
+  // race, but through upsertAddressOptOut's create-or-noop instead of
+  // upsertPreference's create-or-update.
+  test("clicking the same address unsubscribe link three times concurrently does not error", async () => {
+    const address = "flow19-concurrent@test.com";
+    const notificationType = "app:notify:address-unsub-concurrent";
+
+    const token = await signAddressUnsubscribeToken(
+      { tenantId: admin.tenantId, address, notificationType, channel: "email" },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    const url = `${DELIVERY_UNSUBSCRIBE_PATH}?token=${token}`;
+    const results = await Promise.all([
+      stack.app.request(url),
+      stack.app.request(url),
+      stack.app.request(url),
+    ]);
+
+    for (const res of results) {
+      expect(res.status).toBe(200);
+    }
+
+    const rows = await selectMany(db, notificationAddressOptOutsTable, {
+      tenantId: admin.tenantId,
+      notificationType,
+      channel: "email",
+    });
+    expect(rows).toHaveLength(1);
+  });
 });

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

@@ -2,8 +2,8 @@ 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 { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
 import { notificationAddressOptOutEntity, notificationAddressOptOutsTable } from "./tables";
-import { isUniqueViolation } from "./upsert-preference";
 
 const executor = createEventStoreExecutor(
   notificationAddressOptOutsTable,
@@ -45,6 +45,22 @@ async function lookup(
   });
 }
 
+// One row per (tenant, addressHash, type, channel): mirrors
+// preferenceAggregateId in upsert-preference.ts — concurrent first-time
+// opt-outs collide on the same stream at append, not on the projection's
+// unique index.
+function addressOptOutAggregateId(
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+): string {
+  return generateDeterministicId(
+    "delivery:notification-address-opt-out",
+    `${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
@@ -64,24 +80,36 @@ export async function upsertAddressOptOut(
   );
   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 };
-  }
+  const id = addressOptOutAggregateId(
+    input.tenantId,
+    input.addressHash,
+    input.notificationType,
+    input.channel,
+  );
+  const created = await executor.create(
+    {
+      id,
+      addressHash: input.addressHash,
+      notificationType: input.notificationType,
+      channel: input.channel,
+    },
+    actor,
+    db,
+  );
+  if (created.isSuccess) return { isSuccess: true, data: input };
+  // Race-fallback: another request's create already won this deterministic
+  // id between our lookup and this create — the existing row already IS the
+  // opt-out, so the race loser just reports success too.
+  if (created.error.code !== "version_conflict") return created;
+  // A conflict without a row means the stream exists but its row is gone —
+  // report that instead of a silent "unsubscribed" that never persisted.
+  const afterRace = await lookup(
+    db,
+    input.tenantId,
+    input.addressHash,
+    input.notificationType,
+    input.channel,
+  );
+  if (!afterRace) return created;
+  return { isSuccess: true, data: input };
 }

package/src/delivery/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.315.0",
+    "type": "fix",
+    "title": "delivery honors an address opt-out on sends to a user account",
+    "detail": "`deliverToUser` only checked the user's notification preferences, so an\naddress that had been opted out via an address unsubscribe token still got\nmail once it belonged to a user account. It now runs the same check\n`deliverDirect` already applied: when the resolved channel address has a\n`notification-address-opt-out` row for that tenant, notificationType and\nchannel, the attempt is logged as `skipped` / `unsubscribed` with\n`recipientAddress: null`. Critical priority still bypasses it\n(kumiko-framework#3275)."
+  },
+  {
+    "version": "0.315.0",
+    "type": "improvement",
+    "title": "Delivery unsubscribe route is now mountable via extraRoutes",
+    "detail": "`createUnsubscribeRoute` previously returned a raw Hono app that needed a\n`DbConnection` (`{ db, jwtSecret }`) and had to be mounted by hand with\n`stack.app.route(...)`, bypassing the framework's request pipeline. It now\nreturns an `ExtraRouteDefinition` built via `signatureRoute`, taking only\n`{ secret }`, and mounts at the fixed path `GET /api/delivery/unsubscribe?token=`\n(exported as `DELIVERY_UNSUBSCRIBE_PATH`). Mount it with\n`extraRoutes: [createUnsubscribeRoute({ secret: env.UNSUBSCRIBE_SECRET })]`.\n`signUnsubscribeToken` / `signAddressUnsubscribeToken` must sign with the\nsame secret. The secret must be at least 32 characters and must NOT reuse\nthe app's session `JWT_SECRET` — all three entry points fail fast on a\nshort secret.\nThe write itself now goes through two new SystemAdmin-only handlers,\n`delivery:write:unsubscribe-address` and `delivery:write:unsubscribe-user`,\ndispatched via `dispatchSystemWrite` once the route's `verify()` has proven\nthe token's authenticity. An invalid or expired token always responds 400\nwith `{ error: { code: \"unsubscribe_token_invalid\" } }`, never leaking the\nunderlying JWT-library error text.\nNew notification-preference and notification-address-opt-out rows get a\ndeterministic aggregate id derived from (tenant, user or address hash,\nnotificationType, channel), so concurrent clicks on the same link collide\nat the event-store append and converge on one row instead of failing with\na unique or version conflict. Existing rows keep their ids."
+  },
   {
     "version": "0.313.0",
     "type": "breaking",

package/src/delivery/constants.ts

@@ -11,6 +11,7 @@ export {
   DELIVERY_FEATURE,
   DELIVERY_LOG_SCREEN_ID,
   DELIVERY_STATUS_CELL_COMPONENT,
+  DELIVERY_UNSUBSCRIBE_PATH,
   DeliveryErrors,
   DeliveryHandlers,
   DeliveryJobNames,

package/src/delivery/delivery-service.ts

@@ -321,6 +321,20 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     };
   }
 
+  // Shared by deliverToUser (resolved account address) and deliverDirect (a
+  // route address with no user account) — same suppression rule either way:
+  // no blind-index key configured means no hash, so nothing to look up.
+  async function isAddressSuppressed(
+    address: string,
+    tenantId: TenantId,
+    notificationType: string,
+    channelName: string,
+  ): Promise<boolean> {
+    const addressHash = hashUnsubscribeAddress(address);
+    if (addressHash === undefined) return false;
+    return isAddressOptedOut(db, tenantId, addressHash, notificationType, channelName);
+  }
+
   // Check if user has disabled this notification+channel combo.
   // Specificity order: exact > any wildcard. When only wildcards match and they
   // disagree, "disabled wins" — the user has asked to be opted out somewhere,
@@ -439,6 +453,23 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           continue;
         }
 
+        if (
+          priority !== "critical" &&
+          (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
+        ) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId: userId,
+            recipientAddress: null,
+            status: "skipped",
+            error: "unsubscribed",
+            priority,
+          });
+          continue;
+        }
+
         await deliverViaChannel({
           channel,
           address,
@@ -482,33 +513,23 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       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;
-          }
-        }
+      // preferences).
+      if (
+        priority !== "critical" &&
+        (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
+      ) {
+        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) {

package/src/delivery/feature.ts

@@ -18,6 +18,8 @@ import { deliveryAttemptSchema } from "./events";
 import { logQuery } from "./handlers/log.query";
 import { preferencesQuery } from "./handlers/preferences.query";
 import { setPreferenceWrite } from "./handlers/set-preference.write";
+import { unsubscribeAddressWrite } from "./handlers/unsubscribe-address.write";
+import { unsubscribeUserWrite } from "./handlers/unsubscribe-user.write";
 import { DELIVERY_I18N } from "./i18n";
 import { deliveryRenderJob, deliverySendJob } from "./jobs";
 import {
@@ -42,7 +44,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, 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.",
+      "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. Unsubscribe links are served by `createUnsubscribeRoute({ secret })` mounted via the app's `extraRoutes` at `GET /api/delivery/unsubscribe?token=`; sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret.",
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",
@@ -148,6 +150,8 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
 
     const handlers = {
       setPreference: r.writeHandler(setPreferenceWrite),
+      unsubscribeAddress: r.writeHandler(unsubscribeAddressWrite),
+      unsubscribeUser: r.writeHandler(unsubscribeUserWrite),
     };
 
     const queries = {

package/src/delivery/handlers/unsubscribe-address.write.ts

@@ -0,0 +1,40 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { upsertAddressOptOut } from "../address-opt-out";
+
+export const unsubscribeAddressWrite = defineWriteHandler({
+  name: "unsubscribeAddress",
+  schema: z.object({
+    addressHash: z.string().min(1),
+    notificationType: z.string().min(1),
+    channel: z.string().min(1),
+  }),
+  access: { roles: access.systemAdmin },
+  // Only reachable via createUnsubscribeRoute's dispatchSystemWrite, once
+  // verify() has already proven the address-token signature — not a surface
+  // for the agent tool-picker to offer a user directly.
+  agent: { expose: false },
+  description:
+    "Records a no-account address opt-out for one notificationType/channel combination; dispatched by the signed unsubscribe route, not meant for UI callers.",
+  handler: async (event, ctx) => {
+    const { addressHash, notificationType, channel } = event.payload;
+    const { tenantId } = event.user;
+
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "unsubscribeAddress: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(tenantId);
+
+    const result = await upsertAddressOptOut(db, event.user, {
+      tenantId,
+      addressHash,
+      notificationType,
+      channel,
+    });
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: { notificationType, channel } };
+  },
+});

package/src/delivery/handlers/unsubscribe-user.write.ts

@@ -0,0 +1,43 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { upsertPreference } from "../upsert-preference";
+
+export const unsubscribeUserWrite = defineWriteHandler({
+  name: "unsubscribeUser",
+  schema: z.object({
+    userId: z.string().min(1),
+    notificationType: z.string().min(1),
+    channel: z.string().min(1),
+  }),
+  access: { roles: access.systemAdmin },
+  // Only reachable via createUnsubscribeRoute's dispatchSystemWrite, once
+  // verify() has already proven the user-token signature — not a surface for
+  // the agent tool-picker to offer a user directly.
+  agent: { expose: false },
+  description:
+    "Disables one notification type and channel combination for the userId carried in a verified unsubscribe token; dispatched by the signed unsubscribe route, not meant for UI callers.",
+  handler: async (event, ctx) => {
+    // userId comes from the payload, not event.user.id — the caller here is
+    // the system user dispatchSystemWrite runs as, not the user unsubscribing.
+    const { userId, notificationType, channel } = event.payload;
+    const { tenantId } = event.user;
+
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "unsubscribeUser: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(tenantId);
+
+    const result = await upsertPreference(db, event.user, {
+      tenantId,
+      userId,
+      notificationType,
+      channel,
+      enabled: false,
+    });
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: { notificationType, channel } };
+  },
+});

package/src/delivery/index.ts

@@ -4,6 +4,7 @@ export {
   DELIVERY_CHANNEL_EXTENSION,
   DELIVERY_FEATURE,
   DELIVERY_LOG_SCREEN_ID,
+  DELIVERY_UNSUBSCRIBE_PATH,
   DeliveryErrors,
   DeliveryHandlers,
   DeliveryJobs,

package/src/delivery/public-names.ts

@@ -5,8 +5,14 @@ export const DELIVERY_FEATURE = "delivery" as const;
 
 export const DeliveryHandlers = {
   setPreference: "delivery:write:set-preference",
+  unsubscribeAddress: "delivery:write:unsubscribe-address",
+  unsubscribeUser: "delivery:write:unsubscribe-user",
 } as const;
 
+// Fixed so links mailed out today keep working — the unsubscribe route is
+// mounted at this exact path via `extraRoutes: [createUnsubscribeRoute(...)]`.
+export const DELIVERY_UNSUBSCRIBE_PATH = "/api/delivery/unsubscribe" as const;
+
 export const DeliveryQueries = {
   log: "delivery:query:log",
   preferences: "delivery:query:preferences",