@cosmicdrift/kumiko-bundled-features 0.322.0 → 0.324.0

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

@@ -48,7 +48,14 @@ import { createTenantFeature } from "../../tenant/feature";
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 import { tenantEntity } from "../../tenant/schema/tenant";
 import {
+  addressOptOutAggregateIdForTests,
+  hashUnsubscribeAddress,
+  MAX_ADDRESS_OPT_OUT_GENERATIONS_FOR_TESTS,
+} from "../address-opt-out";
+import {
+  DELIVERY_RESUBSCRIBE_PATH,
   DELIVERY_UNSUBSCRIBE_PATH,
+  DeliveryErrors,
   DeliveryHandlers,
   DeliveryJobs,
   DeliveryQueries,
@@ -58,6 +65,7 @@ import { createDeliveryFeature } from "../feature";
 import { deliveryRenderJob, deliverySendJob } from "../jobs";
 import {
   deliveryAttemptsTable,
+  notificationAddressOptOutEntity,
   notificationAddressOptOutsTable,
   notificationPreferencesTable,
 } from "../tables";
@@ -86,6 +94,15 @@ function postUnsubscribe(token: string) {
   });
 }
 
+// Mirrors the unsubscribe-page's "Undo" button: JSON body, never the query.
+function postResubscribe(token: string) {
+  return stack.app.request(DELIVERY_RESUBSCRIBE_PATH, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ token }),
+  });
+}
+
 // Email test infrastructure
 const emailTransport = createInMemoryTransport();
 const testEmail = (userId: string | number) => `user-${userId}@test.com`;
@@ -2269,3 +2286,218 @@ describe("flow 19: address unsubscribe (route-based sends, no user account)", ()
     expect(rows).toHaveLength(1);
   });
 });
+
+// --- Flow 20: resubscribe endpoint (undo direction of unsubscribe) ---
+
+describe("flow 20: resubscribe endpoint", () => {
+  const ADDRESS_BIDX_KEY = Buffer.alloc(32, 3).toString("base64");
+
+  beforeAll(() => {
+    configureBlindIndexKey(ADDRESS_BIDX_KEY);
+  });
+
+  afterAll(() => {
+    resetBlindIndexKeyForTests();
+  });
+
+  test("address token: unsubscribe → resubscribe → unsubscribe again → resubscribe (id generations)", async () => {
+    const address = "flow20-address@test.com";
+    const notificationType = "app:notify:address-resub-20a";
+
+    const token = await signAddressUnsubscribeToken(
+      { tenantId: admin.tenantId, address, notificationType, channel: "email" },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    const unsubRes = await postUnsubscribe(token);
+    expect(unsubRes.status).toBe(200);
+    expect(
+      await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId: admin.tenantId,
+        notificationType,
+        channel: "email",
+      }),
+    ).toHaveLength(1);
+
+    const resubRes = await postResubscribe(token);
+    expect(resubRes.status).toBe(200);
+    const resubBody = (await resubRes.json()) as { isSuccess?: boolean };
+    expect(resubBody.isSuccess).toBe(true);
+    expect(
+      await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId: admin.tenantId,
+        notificationType,
+        channel: "email",
+      }),
+    ).toHaveLength(0);
+
+    // Opting out again must land on a fresh generation — the first
+    // generation's stream was hard-deleted by the resubscribe above.
+    const unsubRes2 = await postUnsubscribe(token);
+    expect(unsubRes2.status).toBe(200);
+    expect(
+      await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId: admin.tenantId,
+        notificationType,
+        channel: "email",
+      }),
+    ).toHaveLength(1);
+
+    const resubRes2 = await postResubscribe(token);
+    expect(resubRes2.status).toBe(200);
+    expect(
+      await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId: admin.tenantId,
+        notificationType,
+        channel: "email",
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("address token: resubscribe at the last generation is refused with 409, opt-out survives, unsubscribe still works", async () => {
+    const address = "flow20-generation-cap@test.com";
+    const notificationType = "app:notify:address-resub-20-cap";
+    const channel = "email";
+    const addressHash = hashUnsubscribeAddress(address);
+    if (!addressHash) throw new Error("blind-index key not configured for this test");
+
+    // Seed directly at the last generation instead of looping resubscribe
+    // 99 times — same executor.create seed pattern production code itself
+    // uses (see ticketExecutor() above), not a raw table write.
+    const lastGenerationId = addressOptOutAggregateIdForTests(
+      admin.tenantId,
+      addressHash,
+      notificationType,
+      channel,
+      MAX_ADDRESS_OPT_OUT_GENERATIONS_FOR_TESTS - 1,
+    );
+    const optOutExecutor = createEventStoreExecutor(
+      notificationAddressOptOutsTable,
+      notificationAddressOptOutEntity,
+      { entityName: "notification-address-opt-out" },
+    );
+    const tenantDb = createTenantDb(db, admin.tenantId);
+    const seeded = await optOutExecutor.create(
+      { id: lastGenerationId, addressHash, notificationType, channel },
+      admin,
+      tenantDb,
+    );
+    expect(seeded.isSuccess).toBe(true);
+
+    const token = await signAddressUnsubscribeToken(
+      { tenantId: admin.tenantId, address, notificationType, channel },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    const resubRes = await postResubscribe(token);
+    expect(resubRes.status).toBe(409);
+    const resubBody = (await resubRes.json()) as { error?: { code?: string } };
+    expect(resubBody.error?.code).toBe(DeliveryErrors.resubscribeLimitReached);
+
+    expect(
+      await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId: admin.tenantId,
+        notificationType,
+        channel,
+      }),
+    ).toHaveLength(1);
+
+    const unsubRes = await postUnsubscribe(token);
+    expect(unsubRes.status).toBe(200);
+    expect(
+      await selectMany(db, notificationAddressOptOutsTable, {
+        tenantId: admin.tenantId,
+        notificationType,
+        channel,
+      }),
+    ).toHaveLength(1);
+  });
+
+  test("address token: resubscribe without a prior opt-out is a no-op 200", async () => {
+    const address = "flow20-no-prior-optout@test.com";
+    const notificationType = "app:notify:address-resub-20b";
+
+    const token = await signAddressUnsubscribeToken(
+      { tenantId: admin.tenantId, address, notificationType, channel: "email" },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    const res = await postResubscribe(token);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess?: boolean };
+    expect(body.isSuccess).toBe(true);
+  });
+
+  test("user token: resubscribe re-enables the preference", async () => {
+    const token = await signUnsubscribeToken(
+      {
+        userId: user2.id,
+        tenantId: user2.tenantId,
+        notificationType: "app:notify:user-resub-20c",
+        channel: "inApp",
+      },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    await postUnsubscribe(token);
+    const disabled = await selectMany(db, notificationPreferencesTable, {
+      userId: user2.id,
+      notificationType: "app:notify:user-resub-20c",
+      channel: "inApp",
+    });
+    expect(disabled[0]?.["enabled"]).toBe(false);
+
+    const res = await postResubscribe(token);
+    expect(res.status).toBe(200);
+    const enabled = await selectMany(db, notificationPreferencesTable, {
+      userId: user2.id,
+      notificationType: "app:notify:user-resub-20c",
+      channel: "inApp",
+    });
+    expect(enabled[0]?.["enabled"]).toBe(true);
+  });
+
+  test("invalid token returns 400 unsubscribe_token_invalid", async () => {
+    const res = await postResubscribe("invalid-jwt-token");
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error?: { code?: string } };
+    expect(body.error?.code).toBe("unsubscribe_token_invalid");
+  });
+
+  test("token only in the query string is rejected (no query fallback, unlike unsubscribe)", async () => {
+    const token = await signUnsubscribeToken(
+      {
+        userId: user2.id,
+        tenantId: user2.tenantId,
+        notificationType: "app:notify:user-resub-20d",
+        channel: "inApp",
+      },
+      UNSUBSCRIBE_SECRET,
+    );
+
+    const res = await stack.app.request(`${DELIVERY_RESUBSCRIBE_PATH}?token=${token}`, {
+      method: "POST",
+    });
+    expect(res.status).toBe(400);
+  });
+
+  test("normal user cannot dispatch the resubscribe write handlers directly", async () => {
+    const addressError = await stack.http.writeErr(
+      DeliveryHandlers.resubscribeAddress,
+      {
+        addressHash: "x".repeat(32),
+        notificationType: "app:notify:direct-resub",
+        channel: "email",
+      },
+      user1,
+    );
+    expect(addressError.code).toBe("access_denied");
+
+    const userError = await stack.http.writeErr(
+      DeliveryHandlers.resubscribeUser,
+      { userId: user2.id, notificationType: "app:notify:direct-resub", channel: "email" },
+      user1,
+    );
+    expect(userError.code).toBe("access_denied");
+  });
+});

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

@@ -2,7 +2,9 @@ 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 { ConflictError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
+import { DeliveryErrors } from "./public-names";
 import { notificationAddressOptOutEntity, notificationAddressOptOutsTable } from "./tables";
 
 const executor = createEventStoreExecutor(
@@ -49,22 +51,56 @@ async function lookup(
 // preferenceAggregateId in upsert-preference.ts — concurrent first-time
 // opt-outs collide on the same stream at append, not on the projection's
 // unique index.
+//
+// `generation` picks a distinct deterministic id for the same business key —
+// needed because removeAddressOptOut() hard-deletes the row (no softDelete on
+// this entity, see tables.ts), which leaves generation 0's stream in a
+// deleted state forever (event-store streams are immutable once deleted).
+// A later opt-out for the same address/type/channel must land on a fresh
+// stream instead of colliding with the dead one. Generation 0 keeps the
+// unsuffixed id for backwards-compatibility with rows written before
+// resubscribe existed.
 function addressOptOutAggregateId(
   tenantId: TenantId,
   addressHash: string,
   notificationType: string,
   channel: string,
+  generation: number,
 ): string {
+  const base = `${tenantId}|${addressHash}|${notificationType}|${channel}`;
   return generateDeterministicId(
     "delivery:notification-address-opt-out",
-    `${tenantId}|${addressHash}|${notificationType}|${channel}`,
+    generation === 0 ? base : `${base}|g${generation}`,
   );
 }
 
+// Hard-cap on generation retries — a version_conflict with no row means the
+// stream at that generation was deleted by a previous resubscribe; this
+// bounds the opt-out/resubscribe ping-pong instead of looping forever on a
+// pathological retry storm.
+const MAX_ADDRESS_OPT_OUT_GENERATIONS = 100;
+
+// Test-only: lets integration tests seed a row at an arbitrary generation
+// (e.g. the last one, to exercise removeAddressOptOut's limit) via the same
+// executor.create seed pattern production code uses, instead of looping
+// upsertAddressOptOut 100 times or writing the table directly.
+export function addressOptOutAggregateIdForTests(
+  tenantId: TenantId,
+  addressHash: string,
+  notificationType: string,
+  channel: string,
+  generation: number,
+): string {
+  return addressOptOutAggregateId(tenantId, addressHash, notificationType, channel, generation);
+}
+
+export const MAX_ADDRESS_OPT_OUT_GENERATIONS_FOR_TESTS = MAX_ADDRESS_OPT_OUT_GENERATIONS;
+
 /**
  * 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.
+ * second row or fail the second click. Resubscribing (removeAddressOptOut)
+ * hard-deletes the row, so a later opt-out probes forward through
+ * generations until it finds one whose stream isn't already dead.
  */
 export async function upsertAddressOptOut(
   db: TenantDb,
@@ -80,36 +116,89 @@ export async function upsertAddressOptOut(
   );
   if (existing) return { isSuccess: true, data: input };
 
-  const id = addressOptOutAggregateId(
+  let lastFailure: WriteResult<UpsertAddressOptOutInput> | undefined;
+  for (let generation = 0; generation < MAX_ADDRESS_OPT_OUT_GENERATIONS; generation++) {
+    const id = addressOptOutAggregateId(
+      input.tenantId,
+      input.addressHash,
+      input.notificationType,
+      input.channel,
+      generation,
+    );
+    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 };
+    if (created.error.code !== "version_conflict") return created;
+
+    // Race-fallback: another request's create already won this generation's
+    // id between our lookup and this create — the existing row already IS
+    // the opt-out, so the race loser just reports success too.
+    const afterRace = await lookup(
+      db,
+      input.tenantId,
+      input.addressHash,
+      input.notificationType,
+      input.channel,
+    );
+    if (afterRace) return { isSuccess: true, data: input };
+
+    // No row after the conflict: this generation's stream was deleted by a
+    // prior resubscribe. Try the next generation instead of failing.
+    lastFailure = created;
+  }
+  return lastFailure ?? { isSuccess: true, data: input };
+}
+
+/**
+ * Resubscribe: hard-deletes the opt-out row so `isAddressOptedOut` reports
+ * false again. Idempotent — no row means the address was never (or is no
+ * longer) opted out, which is already the desired end state.
+ *
+ * Refuses to delete the row sitting at the last available id generation:
+ * unsubscribe must always succeed, and once every generation below the cap
+ * is dead, only a live row at the last generation still guarantees that
+ * (upsertAddressOptOut's existing-row check, no generation loop needed).
+ */
+export async function removeAddressOptOut(
+  db: TenantDb,
+  actor: SessionUser,
+  input: UpsertAddressOptOutInput,
+): Promise<WriteResult<UpsertAddressOptOutInput>> {
+  const existing = await lookup(
+    db,
     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,
+  if (!existing) return { isSuccess: true, data: input };
+
+  const lastGenerationId = addressOptOutAggregateId(
     input.tenantId,
     input.addressHash,
     input.notificationType,
     input.channel,
+    MAX_ADDRESS_OPT_OUT_GENERATIONS - 1,
   );
-  if (!afterRace) return created;
+  if (existing.id === lastGenerationId) {
+    return writeFailure(
+      new ConflictError({
+        message: "resubscribe limit reached: this address must stay opted out",
+        i18nKey: "delivery.errors.resubscribeLimitReached",
+        details: { reason: DeliveryErrors.resubscribeLimitReached },
+      }),
+    );
+  }
+
+  const deleted = await executor.delete({ id: existing.id }, actor, db);
+  if (!deleted.isSuccess) return deleted;
   return { isSuccess: true, data: input };
 }

package/src/delivery/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "New POST /api/delivery/resubscribe route undoes an unsubscribe/opt-out",
+    "detail": "createUnsubscribeRoutes now also mounts POST /api/delivery/resubscribe (JSON {token} or form body only, never the query string, to stay safe against mail-client link prefetchers). It accepts the same signed tokens as the unsubscribe routes and re-enables the preference (signed-in user) or removes the address opt-out (no-account recipient). A resubscribed address opt-out is hard-deleted; a later re-opt-out for the same address/type/channel lands on a fresh event-stream generation instead of reviving the deleted one.",
+    "migration": "No action needed: the route is additive and mounted automatically wherever createUnsubscribeRoutes({ secret }) already runs. Sign resubscribe links with the same signUnsubscribeToken/signAddressUnsubscribeToken used for unsubscribe links."
+  },
   {
     "version": "0.321.0",
     "type": "breaking",

package/src/delivery/constants.ts

@@ -10,6 +10,7 @@ export {
   DELIVERY_ATTEMPT_EVENT,
   DELIVERY_FEATURE,
   DELIVERY_LOG_SCREEN_ID,
+  DELIVERY_RESUBSCRIBE_PATH,
   DELIVERY_STATUS_CELL_COMPONENT,
   DELIVERY_UNSUBSCRIBE_PATH,
   DeliveryErrors,

package/src/delivery/feature.ts

@@ -17,6 +17,8 @@ import {
 import { deliveryAttemptSchema } from "./events";
 import { logQuery } from "./handlers/log.query";
 import { preferencesQuery } from "./handlers/preferences.query";
+import { resubscribeAddressWrite } from "./handlers/resubscribe-address.write";
+import { resubscribeUserWrite } from "./handlers/resubscribe-user.write";
 import { setPreferenceWrite } from "./handlers/set-preference.write";
 import { unsubscribeAddressWrite } from "./handlers/unsubscribe-address.write";
 import { unsubscribeUserWrite } from "./handlers/unsubscribe-user.write";
@@ -44,7 +46,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. Unsubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe`: `GET ?token=` renders a confirmation page (no write), `POST` performs the opt-out (RFC 8058 one-click, token from the form body or query) — 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 this 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). It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.",
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",
@@ -152,6 +154,8 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
       setPreference: r.writeHandler(setPreferenceWrite),
       unsubscribeAddress: r.writeHandler(unsubscribeAddressWrite),
       unsubscribeUser: r.writeHandler(unsubscribeUserWrite),
+      resubscribeAddress: r.writeHandler(resubscribeAddressWrite),
+      resubscribeUser: r.writeHandler(resubscribeUserWrite),
     };
 
     const queries = {

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

@@ -0,0 +1,42 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { removeAddressOptOut } from "../address-opt-out";
+
+export const resubscribeAddressWrite = defineWriteHandler({
+  name: "resubscribeAddress",
+  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 createUnsubscribeRoutes' POST /resubscribe
+  // dispatchSystemWrite, once verify() has already proven the address-token
+  // signature — not a surface for the agent tool-picker to offer directly.
+  // risk: "high" — hard-deletes the opt-out row (see removeAddressOptOut,
+  // the entity has no softDelete).
+  agent: { expose: false, risk: "high" },
+  description:
+    "Removes a no-account address opt-out for one notificationType/channel combination; dispatched by the signed resubscribe 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: "resubscribeAddress: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(tenantId);
+
+    const result = await removeAddressOptOut(db, event.user, {
+      tenantId,
+      addressHash,
+      notificationType,
+      channel,
+    });
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: { notificationType, channel } };
+  },
+});

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

@@ -0,0 +1,41 @@
+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 resubscribeUserWrite = defineWriteHandler({
+  name: "resubscribeUser",
+  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 createUnsubscribeRoutes' POST /resubscribe
+  // dispatchSystemWrite, once verify() has already proven the user-token
+  // signature — not a surface for the agent tool-picker to offer directly.
+  agent: { expose: false },
+  description:
+    "Re-enables one notification type and channel combination for the userId carried in a verified unsubscribe token; dispatched by the signed resubscribe route, not meant for UI callers.",
+  handler: async (event, ctx) => {
+    const { userId, notificationType, channel } = event.payload;
+    const { tenantId } = event.user;
+
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "resubscribeUser: 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: true,
+    });
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: { notificationType, channel } };
+  },
+});

package/src/delivery/public-names.ts

@@ -7,12 +7,21 @@ export const DeliveryHandlers = {
   setPreference: "delivery:write:set-preference",
   unsubscribeAddress: "delivery:write:unsubscribe-address",
   unsubscribeUser: "delivery:write:unsubscribe-user",
+  resubscribeAddress: "delivery:write:resubscribe-address",
+  resubscribeUser: "delivery:write:resubscribe-user",
 } as const;
 
 // Fixed so links mailed out today keep working — the unsubscribe route is
 // mounted at this exact path via `extraRoutes: [...createUnsubscribeRoutes(...)]`.
 export const DELIVERY_UNSUBSCRIBE_PATH = "/api/delivery/unsubscribe" as const;
 
+// Mounted alongside the unsubscribe route by the same
+// `createUnsubscribeRoutes(...)` call — same token, same verify() path, the
+// undo direction. Token is taken from the JSON/form body only, never the
+// query, so a mail-client link prefetcher can't accidentally resubscribe
+// someone.
+export const DELIVERY_RESUBSCRIBE_PATH = "/api/delivery/resubscribe" as const;
+
 export const DeliveryQueries = {
   log: "delivery:query:log",
   preferences: "delivery:query:preferences",
@@ -28,6 +37,10 @@ export const DELIVERY_STATUS_CELL_COMPONENT = "DeliveryStatusCell" as const;
 export const DeliveryErrors = {
   noRecipient: "delivery_no_recipient",
   channelFailed: "delivery_channel_failed",
+  // removeAddressOptOut refuses to delete the opt-out row at the last
+  // available id generation, so an address can always still unsubscribe
+  // (see MAX_ADDRESS_OPT_OUT_GENERATIONS in address-opt-out.ts).
+  resubscribeLimitReached: "resubscribe_limit_reached",
 } as const;
 
 export const DeliveryStatus = {

package/src/delivery/tables.ts

@@ -110,8 +110,11 @@ export const notificationPreferencesTable = pgTable(
 // `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).
+// A row's mere existence is the opt-out; there is no `enabled` toggle to flip.
+// Resubscribing (removeAddressOptOut) hard-deletes the row instead — the
+// entity has no softDelete, and a later re-opt-out for the same address
+// picks the next id generation (see addressOptOutAggregateId) since the
+// deleted stream can't be revived.
 export const notificationAddressOptOutEntity = createEntity({
   table: "read_notification_address_opt_outs",
   fields: {