@cosmicdrift/kumiko-samples 0.352.0 → 0.354.0

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -1,5 +1,6 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { runInSavepointIfSupported } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   computeBlindIndex,
   configuredBlindIndexKey,
@@ -31,8 +32,10 @@ import {
   type WriteFailure,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
-import { append } from "@cosmicdrift/kumiko-framework/event-store";
-import { assertIrreversibleOperationAllowed } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  appendDomainEventCore,
+  assertIrreversibleOperationAllowed,
+} from "@cosmicdrift/kumiko-framework/pipeline";
 import { purgeSearchDocumentsForSubject } from "@cosmicdrift/kumiko-framework/search";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
@@ -46,6 +49,7 @@ import {
 } from "../../user-data-rights/index.js";
 import {
   CRYPTO_SHREDDING_AGGREGATE_TYPE,
+  CRYPTO_SHREDDING_FEATURE_NAME,
   RECORD_ENTITY_NOT_REGISTERED,
   SUBJECT_FORGET_DENIED_EVENT_NAME,
   SUBJECT_FORGOTTEN_EVENT_NAME,
@@ -65,6 +69,9 @@ export const subjectForgottenSchema = z.object({
   subjectKey: z.string().min(1),
   reason: z.string().min(10),
   forgottenBy: z.string().min(1),
+  // Error code or name of a failed derived-data sweep, never its message (which
+  // can name the subject). Present only when the handler failed after the erase.
+  cleanupError: z.string().min(1).optional(),
 });
 
 export const subjectForgetDeniedSchema = z.object({
@@ -234,16 +241,8 @@ async function appendDenialAuditEvent(
       }),
     );
   }
-  const eventDef = ctx.registry.getEvent(SUBJECT_FORGET_DENIED_EVENT_NAME);
-  if (!eventDef) {
-    return writeFailure(
-      new InternalError({
-        message: `[crypto-shredding] event "${SUBJECT_FORGET_DENIED_EVENT_NAME}" is not registered.`,
-      }),
-    );
-  }
   const blindIndexKey = configuredBlindIndexKey();
-  const payload = subjectForgetDeniedSchema.parse({
+  const payload: z.infer<typeof subjectForgetDeniedSchema> = {
     // The denial lands in the REQUESTING actor's own tenant-scoped stream —
     // it must never materialise the foreign subject's identifiers there. A
     // plaintext subjectKey/aggregateId would survive as a permanent record
@@ -260,31 +259,132 @@ async function appendDenialAuditEvent(
     forgottenBy: event.user.id,
     actorTenantId: event.user.tenantId,
     denial: denialCode,
-  });
-  const reqCtx = requestContext.get();
-  // This event is the only proof the denial happened. Skipping
-  // runProjectionsForEvent here is fine — nothing projects
-  // crypto-shredding:event:forget-denied.
-  await append(denialAuditRunner, {
-    aggregateId: generateId(),
-    aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
-    // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw
-    // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event (fw#2452).
-    tenantId: event.user.tenantId,
-    expectedVersion: 0,
-    type: SUBJECT_FORGET_DENIED_EVENT_NAME,
-    eventVersion: eventDef.version,
-    payload,
-    metadata: {
-      userId: event.user.id,
-      ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
-      ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
-      ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
+  };
+  await appendDomainEventCore(
+    {
+      registry: ctx.registry,
+      db: denialAuditRunner,
+      // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw
+      // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event (fw#2452).
+      tenantId: event.user.tenantId,
+      userId: String(event.user.id),
+      callSiteLabel: "forget-subject denial audit",
+      callerFeature: CRYPTO_SHREDDING_FEATURE_NAME,
     },
-  });
+    {
+      // Fresh stream per denial: no version to read, nothing to conflict with.
+      aggregateId: generateId(),
+      aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+      type: SUBJECT_FORGET_DENIED_EVENT_NAME,
+      payload,
+    },
+  );
   return null;
 }
 
+// Name or driver code of the error, never its message: a message can carry the
+// subject key or row values and would land in a permanent audit event.
+function sweepErrorLabel(err: unknown): string {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = err.code;
+    if (typeof code === "string" && code.length > 0) return code;
+  }
+  return err instanceof Error && err.name.length > 0 ? err.name : "UnknownError";
+}
+
+// The key is already erased when this runs, so a failing sweep must not skip the
+// audit event: the failure is returned as a label for the event instead of thrown.
+// The savepoint keeps a database error from aborting the handler transaction.
+async function sweepDerivedSubjectData(
+  ctx: HandlerContext,
+  subject: SubjectId,
+  subjectKey: string,
+  crossTenantRunner: DbRunner,
+): Promise<string | undefined> {
+  try {
+    await runInSavepointIfSupported(crossTenantRunner, async (crossTenantSubjectRunner) => {
+      // Blind-index sweep (#818): nulls bidx columns now so the deterministic
+      // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
+      await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
+
+      // Derived search index still holds plaintext (#1610) — purge next to the
+      // blind-index sweep. No adapter → no-op (apps without search).
+      if (ctx.searchAdapter) {
+        await purgeSearchDocumentsForSubject(
+          crossTenantSubjectRunner,
+          ctx.registry.features,
+          ctx.searchAdapter,
+          subjectKey,
+          subject,
+        );
+      }
+    });
+    return undefined;
+  } catch (err) {
+    return sweepErrorLabel(err);
+  }
+}
+
+// Graceful fail: email-subscribers and other non-user entities may use
+// user-style subject keys without having an actual user row — the key erase is
+// the important part for GDPR compliance; the lifecycle update is best-effort for
+// real users. The savepoint confines the failure so the handler transaction
+// stays usable for the audit event.
+async function closeUserLoginDoorBestEffort(
+  ctx: HandlerContext,
+  userId: string,
+  lifecycleRunner: DbRunner,
+): Promise<void> {
+  try {
+    await runInSavepointIfSupported(lifecycleRunner, async (userLifecycleRunner) => {
+      await updateUserLifecycle(userLifecycleRunner, userId, { status: USER_STATUS.Deleted });
+      if (ctx.registry.features.has("personal-access-tokens")) {
+        await revokeAllPatTokensForUser(userLifecycleRunner, userId);
+      }
+    });
+  } catch {
+    // skip: no user row for this subject key (e.g. email subscribers); key erase and sweeps already ran.
+  }
+}
+
+// Through the outside-transaction db when available, so the audit event commits
+// even though the handler may fail afterwards (sweep error) and roll back its own
+// transaction. Without that source the event stays in the handler transaction.
+async function appendSubjectForgotten(
+  ctx: HandlerContext,
+  event: WriteEvent<z.infer<typeof forgetSubjectSchema>>,
+  aggregateId: string,
+  payload: z.infer<typeof subjectForgottenSchema>,
+  outsideRunner: DbRunner | undefined,
+): Promise<void> {
+  if (!outsideRunner) {
+    await ctx.unsafeAppendEvent({
+      aggregateId,
+      aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+      type: SUBJECT_FORGOTTEN_EVENT_NAME,
+      payload,
+    });
+  } else {
+    await appendDomainEventCore(
+      {
+        registry: ctx.registry,
+        db: outsideRunner,
+        // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw bypasses TenantDb's scoping (fw#2452).
+        tenantId: event.user.tenantId,
+        userId: String(event.user.id),
+        callSiteLabel: "forget-subject audit",
+        callerFeature: CRYPTO_SHREDDING_FEATURE_NAME,
+      },
+      {
+        aggregateId,
+        aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+        type: SUBJECT_FORGOTTEN_EVENT_NAME,
+        payload,
+      },
+    );
+  }
+}
+
 // Manual crypto-shred for a DPO / platform operator: erases the subject's
 // DEK immediately (all its PII ciphertext becomes unreadable, reads render
 // "[[erased]]") and appends the audit event. Forget is final — the adapter
@@ -306,7 +406,7 @@ export const forgetSubjectWrite = defineWriteHandler({
   escapeHatch: {
     grants: ["unsafeRaw"],
     reason:
-      "denial audit append names the prober's own tenant stream on the outside-transaction db; " +
+      "the denial and SUBJECT_FORGOTTEN audit appends name the caller's own tenant stream on the outside-transaction db; " +
       "the tenant-scope and retention checks run against the subject's tenant, not necessarily the caller's; " +
       "the blind-index sweep and search purge address the subject across tenants; the user " +
       "lifecycle update and PAT revoke run on the SYSTEM user stream.",
@@ -377,22 +477,12 @@ export const forgetSubjectWrite = defineWriteHandler({
       eraseReason: event.payload.reason,
     });
 
-    // Blind-index sweep (#818): nulls bidx columns now so the deterministic
-    // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
-    const crossTenantSubjectRunner = ctx.db.unsafeRaw();
-    await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
-
-    // Derived search index still holds plaintext (#1610) — purge next to the
-    // blind-index sweep. No adapter → no-op (apps without search).
-    if (ctx.searchAdapter) {
-      await purgeSearchDocumentsForSubject(
-        crossTenantSubjectRunner,
-        ctx.registry.features,
-        ctx.searchAdapter,
-        subjectKey,
-        subject,
-      );
-    }
+    const cleanupError = await sweepDerivedSubjectData(
+      ctx,
+      subject,
+      subjectKey,
+      ctx.db.unsafeRaw(),
+    );
 
     // User subject: close the login door. DEK-erase makes the passwordHash
     // ciphertext unreadable, but status + PATs are standalone credentials —
@@ -409,33 +499,28 @@ export const forgetSubjectWrite = defineWriteHandler({
     // crash recovery is safe. User-feature guard: without the user feature
     // read_users doesn't exist (crypto-only stack). Tenant subjects have no
     // credentials.
-    // Graceful fail: email-subscribers and other non-user entities may use
-    // user-style subject keys without having an actual user row — the key
-    // erase above is the important part for GDPR compliance; the lifecycle
-    // update is best-effort for real users.
     if (raw.kind === "user" && ctx.registry.features.has("user")) {
-      try {
-        const userLifecycleRunner = ctx.db.unsafeRaw();
-        await updateUserLifecycle(userLifecycleRunner, raw.userId, { status: USER_STATUS.Deleted });
-        if (ctx.registry.features.has("personal-access-tokens")) {
-          await revokeAllPatTokensForUser(userLifecycleRunner, raw.userId);
-        }
-      } catch {
-        // User row may not exist (e.g. email subscribers with user-style
-        // subject keys). Key erase + blind-index sweep above already ran.
-      }
+      await closeUserLoginDoorBestEffort(ctx, raw.userId, ctx.db.unsafeRaw());
     }
 
-    await ctx.unsafeAppendEvent({
-      aggregateId: subjectAggregateId(raw),
-      aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
-      type: SUBJECT_FORGOTTEN_EVENT_NAME,
-      payload: {
+    await appendSubjectForgotten(
+      ctx,
+      event,
+      subjectAggregateId(raw),
+      {
         subjectKey,
         reason: event.payload.reason,
         forgottenBy: event.user.id,
+        ...(cleanupError !== undefined && { cleanupError }),
       },
-    });
+      ctx.dbOutsideTransaction?.unsafeRaw(),
+    );
+
+    if (cleanupError !== undefined) {
+      throw new InternalError({
+        message: `[crypto-shredding] forget-subject erased the key but a derived-data sweep failed (${cleanupError}); retry to finish the cleanup.`,
+      });
+    }
 
     return { isSuccess: true as const, data: { subjectKey } };
   },

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "POST /resubscribe requires the undo token from the POST /unsubscribe response",
+    "migration": "Clients that called the resubscribe route with the unsubscribe token must send the undo token instead: read it from the hidden token field of the page POST /unsubscribe returns (aud kumiko:resubscribe, valid for 1 hour). The unsubscribe token is rejected on /resubscribe with 400, and the undo token is rejected on /unsubscribe."
+  },
   {
     "version": "0.352.0",
     "type": "breaking",

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

@@ -1,23 +1,29 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { notificationAddressOptOutsTable } from "../../tables.js";
+
+export type AddressOptOutKey = string;
+
+export function addressOptOutKey(addressHash: string, channel: string): AddressOptOutKey {
+  return `${addressHash}|${channel}`;
+}
 
 // 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(
+// carries one concrete notificationType/channel pair. One query covers every
+// recipient of a notify() call.
+export async function selectOptedOutAddresses(
   db: DbConnection,
   tenantId: TenantId,
-  addressHash: string,
   notificationType: string,
-  channel: string,
-): Promise<boolean> {
-  const rows = await unsafeReadRetrying<{ readonly id: string }>(
+  addressHashes: readonly string[],
+): Promise<ReadonlySet<AddressOptOutKey>> {
+  if (addressHashes.length === 0) return new Set();
+  const rows = await selectMany<{ readonly addressHash: string; readonly channel: 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],
+    notificationAddressOptOutsTable,
+    { tenantId, notificationType, addressHash: { in: addressHashes } },
   );
-  return rows.length > 0;
+  return new Set(rows.map((row) => addressOptOutKey(row.addressHash, row.channel)));
 }

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

@@ -22,7 +22,11 @@ import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { appendAttemptEvent, logAttempt } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
 import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryPriorityRank } from "./constants.js";
-import { isAddressOptedOut } from "./db/queries/address-opt-outs.js";
+import {
+  type AddressOptOutKey,
+  addressOptOutKey,
+  selectOptedOutAddresses,
+} from "./db/queries/address-opt-outs.js";
 import { selectNotificationPreferences } from "./db/queries/preferences.js";
 import {
   type ChannelContext,
@@ -411,16 +415,74 @@ 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(
+  // no blind-index key configured means no hash, so nothing to look up. One
+  // query per notify() call, not per recipient and channel.
+  async function loadSuppressedAddresses(
+    tenantId: TenantId,
+    notificationType: string,
+    priority: NotifyPriority,
+    addresses: Iterable<string>,
+  ): Promise<ReadonlySet<AddressOptOutKey>> {
+    // Critical priority skips address opt-outs, same rule as user preferences.
+    if (priority === "critical") return new Set();
+    const addressHashes = new Set<string>();
+    for (const address of addresses) {
+      const addressHash = hashUnsubscribeAddress(address);
+      if (addressHash !== undefined) addressHashes.add(addressHash);
+    }
+    return selectOptedOutAddresses(db, tenantId, notificationType, [...addressHashes]);
+  }
+
+  function isAddressSuppressed(
+    suppressed: ReadonlySet<AddressOptOutKey>,
     address: string,
+    channelName: string,
+  ): boolean {
+    const addressHash = hashUnsubscribeAddress(address);
+    return addressHash !== undefined && suppressed.has(addressOptOutKey(addressHash, channelName));
+  }
+
+  const recipientChannelKey = (userId: string, channelName: string) => `${userId}|${channelName}`;
+
+  async function isChannelDeliverable(
+    userId: 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);
+    if (isChannelKilled && (await isChannelKilled(tenantId, channelName))) return false;
+    return isChannelEnabled(userId, tenantId, notificationType, channelName);
+  }
+
+  // Resolves every user's channel addresses up front so the opt-out lookup can
+  // cover them all at once. A resolve that throws stays out of the map: the
+  // delivery loop resolves it again and reports channel_error as before.
+  // Channels the kill switch or the user's preferences disable are never resolved
+  // here: resolve may have side effects and deliverToUser skips those channels.
+  async function prefetchUserAddresses(
+    userIds: readonly string[],
+    tenantId: TenantId,
+    notificationType: string,
+  ): Promise<Map<string, string | null>> {
+    const addresses = new Map<string, string | null>();
+    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    for (const userId of userIds) {
+      for (const channel of channels) {
+        if (!channel.resolve) continue;
+        try {
+          if (!(await isChannelDeliverable(userId, tenantId, notificationType, channel.name))) {
+            continue;
+          }
+          addresses.set(
+            recipientChannelKey(userId, channel.name),
+            await channel.resolve(userId, channelCtx),
+          );
+        } catch {
+          // skip: re-resolved (and logged) by deliverToUser
+        }
+      }
+    }
+    return addresses;
   }
 
   // Check if user has disabled this notification+channel combo.
@@ -466,6 +528,8 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantId: TenantId,
     priority: NotifyPriority,
     run: NotifyRun,
+    prefetchedAddresses: ReadonlyMap<string, string | null>,
+    suppressed: ReadonlySet<AddressOptOutKey>,
   ): Promise<void> {
     const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
 
@@ -530,7 +594,10 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       }
 
       try {
-        const address = await channel.resolve(userId, channelCtx);
+        const prefetchKey = recipientChannelKey(userId, channel.name);
+        const address = prefetchedAddresses.has(prefetchKey)
+          ? prefetchedAddresses.get(prefetchKey)
+          : await channel.resolve(userId, channelCtx);
         if (!address) {
           await logDelivery(run, {
             tenantId,
@@ -545,10 +612,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           continue;
         }
 
-        if (
-          priority !== "critical" &&
-          (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
-        ) {
+        if (priority !== "critical" && isAddressSuppressed(suppressed, address, channel.name)) {
           await logDelivery(run, {
             tenantId,
             notificationType,
@@ -602,6 +666,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     run: NotifyRun,
   ): Promise<void> {
     const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    const suppressed = await loadSuppressedAddresses(
+      tenantId,
+      notificationType,
+      priority,
+      Object.values(route),
+    );
 
     // Direct routing skips preferences (no user account) but NOT rate limit
     // — direct sends can still be abused (webhook replays, test harnesses).
@@ -612,10 +682,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
       // Address opt-out (critical priority skips it, same rule as user
       // preferences).
-      if (
-        priority !== "critical" &&
-        (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
-      ) {
+      if (priority !== "critical" && isAddressSuppressed(suppressed, address, channel.name)) {
         await logDelivery(run, {
           tenantId,
           notificationType,
@@ -729,8 +796,28 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           userIds = to;
         }
 
+        const prefetchedAddresses =
+          priority === "critical"
+            ? new Map<string, string | null>()
+            : await prefetchUserAddresses(userIds, tenantId, notificationType);
+        const suppressed = await loadSuppressedAddresses(
+          tenantId,
+          notificationType,
+          priority,
+          [...prefetchedAddresses.values()].filter((address): address is string => !!address),
+        );
+
         for (const userId of userIds) {
-          await deliverToUser(userId, notificationType, data, tenantId, priority, run);
+          await deliverToUser(
+            userId,
+            notificationType,
+            data,
+            tenantId,
+            priority,
+            run,
+            prefetchedAddresses,
+            suppressed,
+          );
         }
       }
       return { deliveries: run.deliveries };

package/packages/bundled-features/src/delivery/public-names.ts

@@ -11,7 +11,7 @@ export const DeliveryHandlers = {
   resubscribeUser: "delivery:write:resubscribe-user",
 } as const;
 
-// Fixed so links mailed out today keep working — the unsubscribe route is
+// Stable path: links signed against it keep working. The unsubscribe route is
 // mounted at this exact path via `extraRoutes: [...createUnsubscribeRoutes(...)]`.
 export const DELIVERY_UNSUBSCRIBE_PATH = "/api/delivery/unsubscribe" as const;