@cosmicdrift/kumiko-bundled-features 0.321.0 → 0.323.0

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: {

package/src/delivery/unsubscribe.ts

@@ -10,7 +10,12 @@ import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import * as jose from "jose";
 import * as z from "zod";
 import { hashUnsubscribeAddress } from "./address-opt-out";
-import { DELIVERY_UNSUBSCRIBE_PATH, DeliveryHandlers } from "./constants";
+import {
+  DELIVERY_RESUBSCRIBE_PATH,
+  DELIVERY_UNSUBSCRIBE_PATH,
+  DeliveryErrors,
+  DeliveryHandlers,
+} from "./constants";
 
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
@@ -130,11 +135,10 @@ export async function signAddressUnsubscribeToken(
       .setSubject(addressHash)
       .setIssuer("kumiko:unsubscribe")
       .setIssuedAt()
-      // No expiry, unlike the user token above: a leaked address token can
-      // only opt that one address out of one notificationType/channel, and
-      // an unsubscribe link mailed out today must keep working indefinitely
-      // — there is no signed-in flow for a no-account address to re-subscribe
-      // or request a fresh link from.
+      // No expiry, unlike the user token above: this same token also signs
+      // the resubscribe (undo) direction, and an unsubscribe link mailed out
+      // today must keep working indefinitely — there's no signed-in flow for
+      // a no-account address to request a fresh link from.
       .sign(encodedSecret)
   );
 }
@@ -262,6 +266,50 @@ async function dispatchUnsubscribeWrite(
   return dispatched.isSuccess;
 }
 
+// "limit_reached" is a distinct outcome, not a generic failure: it's the
+// address-side generation cap (removeAddressOptOut) refusing to delete the
+// opt-out row so unsubscribe always still works — the route answers 409,
+// not the 500 a real write failure gets.
+type ResubscribeOutcome = "success" | "limit_reached" | "failed";
+
+function isResubscribeLimitReached(error: { readonly details?: unknown }): boolean {
+  const details = error.details;
+  return (
+    typeof details === "object" &&
+    details !== null &&
+    (details as { reason?: unknown }).reason === DeliveryErrors.resubscribeLimitReached
+  );
+}
+
+async function dispatchResubscribeWrite(
+  verified: VerifiedUnsubscribe,
+  deps: SignatureExtraRouteDeps,
+): Promise<ResubscribeOutcome> {
+  const payload =
+    verified.kind === "address"
+      ? {
+          addressHash: verified.addressHash,
+          notificationType: verified.notificationType,
+          channel: verified.channel,
+        }
+      : {
+          userId: verified.userId,
+          notificationType: verified.notificationType,
+          channel: verified.channel,
+        };
+
+  const dispatched = await deps.dispatchSystemWrite({
+    handlerQn:
+      verified.kind === "address"
+        ? DeliveryHandlers.resubscribeAddress
+        : DeliveryHandlers.resubscribeUser,
+    tenantId: verified.tenantId,
+    payload,
+  });
+  if (dispatched.isSuccess) return "success";
+  return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
+}
+
 function confirmationPage(token: string): string {
   return `<!doctype html>
 <html>
@@ -291,6 +339,30 @@ function tokenFromPostRequest(request: SignatureExtraRouteVerifyRequest): string
   return request.query["token"];
 }
 
+// Resubscribe is deliberately NOT reachable via the query string — a mail
+// client's link prefetcher (or a scanner) following an unsubscribe link
+// eagerly is the exact threat model unsubscribe's one-click POST body
+// convention is built to avoid; resubscribe carries the same risk in
+// reverse (a prefetch that undoes a real opt-out) and gets no query-param
+// fallback at all.
+function tokenFromResubscribeRequest(
+  request: SignatureExtraRouteVerifyRequest,
+): string | undefined {
+  const contentType = request.headers["content-type"];
+  if (contentType?.includes("application/x-www-form-urlencoded")) {
+    return new URLSearchParams(request.rawBody).get("token") ?? undefined;
+  }
+  if (contentType?.includes("application/json")) {
+    try {
+      const parsed = JSON.parse(request.rawBody) as { token?: unknown };
+      return typeof parsed.token === "string" ? parsed.token : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
 // GET renders a confirmation page without writing; POST performs the opt-out.
 export function createUnsubscribeRoutes(
   options: UnsubscribeRouteOptions,
@@ -335,5 +407,30 @@ export function createUnsubscribeRoutes(
     },
   });
 
-  return [confirmRoute, writeRoute];
+  // Undo direction: token only from the JSON/form body, never the query
+  // (see tokenFromResubscribeRequest) — no GET confirmation-page variant,
+  // this is a one-shot POST from the unsubscribe-page's "Undo" button.
+  const resubscribeRoute = signatureRoute<VerifiedUnsubscribe>({
+    method: "POST",
+    path: DELIVERY_RESUBSCRIBE_PATH,
+    entry: "signature",
+    verify: async (request) =>
+      verifyUnsubscribeToken(tokenFromResubscribeRequest(request), encodedSecret),
+    handler: async (c, verified, deps) => {
+      const outcome = await dispatchResubscribeWrite(verified, deps);
+      if (outcome === "limit_reached") {
+        return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
+          "Cache-Control": "no-store",
+        });
+      }
+      if (outcome === "failed") {
+        return c.json({ error: { code: "resubscribe_failed" } }, 500, {
+          "Cache-Control": "no-store",
+        });
+      }
+      return c.json({ isSuccess: true }, 200, { "Cache-Control": "no-store" });
+    },
+  });
+
+  return [confirmRoute, writeRoute, resubscribeRoute];
 }

package/src/document-ingest-foundation/__tests__/feature.integration.test.ts

@@ -6,6 +6,12 @@
 // hardcoded allowlist/cap — there is none anymore.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  buildAgentManifest,
+  buildToolCatalog,
+  dispatchToolCall,
+  toolNameForQn,
+} from "@cosmicdrift/kumiko-bundled-features/agent-tools";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -27,6 +33,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createConfigFeature } from "../../config";
 import { createTenantFeature } from "../../tenant/feature";
@@ -136,6 +143,22 @@ const documentExtractExecutorForSeed = createEventStoreExecutor(
   { entityName: "document-extract" },
 );
 
+// A mid-risk agent tool (not the raw HTTP DELETE route) appends fileRef.deleted under a real
+// entryHandler, proving the forget-extract-with-file-ref consumer stays ungated regardless.
+const AGENT_DELETE_FILEREF_QN = "agent-tools-test-delete-fileref:write:delete-fileref-mid";
+
+const agentDeleteFileRefFeature = defineFeature("agent-tools-test-delete-fileref", (r) => {
+  r.writeHandler(
+    "delete-fileref-mid",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => fileRefExecutor.delete({ id: event.payload.id }, event.user, ctx.db),
+    {
+      access: { roles: ["Admin"] },
+      description: "Soft-delete a fileRef (mid risk, default agent exposure).",
+    },
+  );
+});
+
 beforeAll(async () => {
   provider = createInMemoryFileProvider();
   stack = await setupTestStack({
@@ -147,6 +170,7 @@ beforeAll(async () => {
       documentIngestFoundationFeature,
       testProviderAFeature,
       testProviderBFeature,
+      agentDeleteFileRefFeature,
     ],
     files: { storageProvider: provider },
     // Distinct prefix: avoids sharing a BullMQ queue namespace with any other
@@ -579,6 +603,54 @@ describe("fileRef.restored → re-ingest", () => {
   });
 });
 
+// Regression proof for the deferred-context exception on assertIrreversibleOperationAllowed:
+// the consumer (separate dispatcher pass, no entryHandler) still forgets the extract cleanly.
+describe("fileRef soft-delete via a mid-risk agent tool", () => {
+  test("dispatchToolCall delete succeeds, the consumer forgets the extract without a gate error, restore re-ingests", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+    });
+
+    const manifest = buildAgentManifest(stack.registry, { locale: "en", roles: admin.roles });
+    const catalog = buildToolCatalog(stack.registry, manifest, { mode: "edit" });
+    const deleteResult = await dispatchToolCall({
+      dispatcher: stack.dispatcher,
+      user: admin,
+      toolName: toolNameForQn(AGENT_DELETE_FILEREF_QN),
+      input: { id: fileRefId },
+      dispatchTable: catalog.dispatchTable,
+      runId: "run-delete-fileref",
+      toolCallId: `call-delete-fileref-${fileRefId}`,
+    });
+    expect(deleteResult.ok).toBe(true);
+
+    await stack.eventDispatcher?.runOnce();
+
+    const consumerRows = await asRawClient(stack.db).unsafe(
+      `SELECT status, last_error FROM kumiko_event_consumers WHERE name = $1`,
+      ["document-ingest-foundation:projection:forget-extract-with-file-ref"],
+    );
+    const consumer = (consumerRows as { status: string; last_error: string | null }[])[0];
+    expect(consumer?.last_error).toBeNull();
+    expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(0);
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const restoreResult = await fileRefExecutor.restore({ id: fileRefId }, user, tdb);
+    if (!restoreResult.isSuccess) {
+      throw new Error(`restore failed: ${restoreResult.error.message}`);
+    }
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+    });
+  });
+});
+
 describe("orphan extract guard", () => {
   const testMeta = {
     provider: PROVIDER_A_NAME,

package/src/tenant/__tests__/members-facet-i18n.test.ts

@@ -6,6 +6,7 @@
 // so adding a facet option without translating it fails here rather than in
 // production.
 import { describe, expect, test } from "bun:test";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { localeEsBundle } from "@cosmicdrift/kumiko-locale-es";
 import { MEMBERS_SCREEN_ID } from "../constants";
@@ -67,7 +68,7 @@ describe("members status filter labels are localized in every shipped locale (fw
       const label = translations[key]?.["en"];
       expect(label).toBeString();
       expect(label).not.toBe(key);
-      expect((label ?? "").trim()).not.toBe("");
+      expect((label === undefined ? "" : translationValueOtherText(label)).trim()).not.toBe("");
     }
   });
 
@@ -77,7 +78,7 @@ describe("members status filter labels are localized in every shipped locale (fw
       const label = translations[key]?.["en"];
       expect(label).toBeString();
       expect(label).not.toBe(key);
-      expect((label ?? "").trim()).not.toBe("");
+      expect((label === undefined ? "" : translationValueOtherText(label)).trim()).not.toBe("");
     }
   });
 

package/src/tenant-settings/__tests__/settings-hub-i18n.test.ts

@@ -14,20 +14,16 @@
 import { describe, expect, test } from "bun:test";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import { buildConfigFeatureSchema, createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { localeEsBundle } from "@cosmicdrift/kumiko-locale-es";
-import { translationsByLocaleFromKeys } from "@cosmicdrift/kumiko-renderer";
+import { type TranslationsByKey, translationsByLocaleFromKeys } from "@cosmicdrift/kumiko-renderer";
 import { createTenantSettingsFeature } from "../feature";
 
-function translate(
-  translations: Readonly<Record<string, Readonly<Record<string, string>> | undefined>>,
-  key: string,
-  locale = "en",
-): string {
-  const byLocale = translationsByLocaleFromKeys(
-    translations as Record<string, Readonly<Record<string, string>>>,
-  );
-  return byLocale[locale]?.[key] ?? key;
+function translate(translations: TranslationsByKey, key: string, locale = "en"): string {
+  const byLocale = translationsByLocaleFromKeys(translations);
+  const value = byLocale[locale]?.[key];
+  return value === undefined ? key : translationValueOtherText(value);
 }
 
 function settingsHubLabelKeys(): readonly string[] {

package/src/user-data-rights/__tests__/run-forget-cleanup.integration.test.ts

@@ -15,10 +15,10 @@
 // Unit-Test pinned (policy-to-strategy.test.ts), nicht hier. Hier nur
 // der end-to-end-Default-Pfad (delete).
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
@@ -29,10 +29,15 @@ import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
   type TestStack,
+  TestUsers,
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { resetTestTables, seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  resetPiiSubjectKmsForTests,
+  resetTestTables,
+  seedRow,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
@@ -1092,3 +1097,35 @@ describe("runForgetCleanup :: crypto-shredding (subject key erase)", () => {
     expect(alice?.email).toBe("alice.erase-fail@example.com");
   });
 });
+
+// The manual operator trigger (agent.risk "high") must erase a real subject key
+// through configuredPiiSubjectKms(), not a directly-injected args.kms that bypasses the wrapper.
+describe("run-forget-cleanup write handler (manual, risk high) via configuredPiiSubjectKms", () => {
+  afterEach(() => {
+    resetPiiSubjectKmsForTests();
+  });
+
+  test("erases the subject key through the gated KMS wrapper", async () => {
+    await seedUser(ALICE_ID, {
+      status: USER_STATUS.DeletionRequested,
+      gracePeriodEnd: instantFromOffsetMs(-60 * 1000),
+    });
+    await seedMembership(ALICE_ID, TENANT_A);
+
+    const kms = new InMemoryKmsAdapter();
+    await kms.createKey({ kind: "user", userId: ALICE_ID });
+    configurePiiSubjectKms(kms);
+
+    await stack.http.writeOk(
+      "user-data-rights:write:run-forget-cleanup",
+      {},
+      TestUsers.systemAdmin,
+    );
+
+    const aliceRow = await fetchUser(ALICE_ID);
+    expect(aliceRow?.status).toBe(USER_STATUS.Deleted);
+    await expect(kms.getKey({ kind: "user", userId: ALICE_ID })).rejects.toThrow(
+      "Subject key erased",
+    );
+  });
+});

package/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -31,7 +31,9 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
     name: "run-forget-cleanup",
     schema: z.object({}),
     access: { roles: access.privileged },
-    agent: { expose: false },
+    // Cascades into per-user forget hooks that hard-purge (executor.forget)
+    // records without softDelete — an agent must never be able to trigger it.
+    agent: { expose: false, risk: "high" },
     escapeHatch: {
       reason: RUN_FORGET_CLEANUP_REASON,
     },