@cosmicdrift/kumiko-bundled-features 0.313.0 → 0.315.0

package/src/delivery/unsubscribe.ts

@@ -1,10 +1,13 @@
-import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ExtraRouteDefinition,
+  ExtraRouteRejection,
+  signatureRoute,
+} from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { Hono } from "hono";
 import * as jose from "jose";
 import * as z from "zod";
-import { hashUnsubscribeAddress, upsertAddressOptOut } from "./address-opt-out";
-import { upsertPreference } from "./upsert-preference";
+import { hashUnsubscribeAddress } from "./address-opt-out";
+import { DELIVERY_UNSUBSCRIBE_PATH, 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.
@@ -49,22 +52,36 @@ export type AddressUnsubscribeTokenPayload = {
   readonly channel: string;
 };
 
+/**
+ * `secret` must be a value dedicated to unsubscribe-token signing — do NOT
+ * reuse the app's session `JWT_SECRET`. The app mounting `extraRoutes:
+ * [createUnsubscribeRoute({ secret })]` signs outgoing links with the same
+ * value via `signUnsubscribeToken` / `signAddressUnsubscribeToken`.
+ */
 export type UnsubscribeRouteOptions = {
-  readonly db: DbConnection;
-  readonly jwtSecret: string;
+  readonly secret: string;
 };
 
 const UNSUBSCRIBE_EXPIRY = "7d";
-// The route runs outside the dispatcher — no SessionUser, no JWT middleware.
-// Bill the event against the token-subject (the user owns their preference)
-// and attribute it as a system-role action. This mirrors the way jobs and
-// seeds attribute their out-of-band writes.
-const SYSTEM_ROLES = ["system"] as const;
+const MIN_UNSUBSCRIBE_SECRET_LENGTH = 32;
+
+function assertUnsubscribeSecret(secret: string, caller: string): void {
+  if (secret.length < MIN_UNSUBSCRIBE_SECRET_LENGTH) {
+    throw new Error(
+      `${caller}: secret must be ≥${MIN_UNSUBSCRIBE_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
+    );
+  }
+}
+
+const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
+  error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
+} as const;
 
 export async function signUnsubscribeToken(
   payload: UnsubscribeTokenPayload,
   secret: string,
 ): Promise<string> {
+  assertUnsubscribeSecret(secret, "signUnsubscribeToken");
   const encodedSecret = new TextEncoder().encode(secret);
   return new jose.SignJWT({
     tenantId: payload.tenantId,
@@ -90,6 +107,7 @@ export async function signAddressUnsubscribeToken(
   payload: AddressUnsubscribeTokenPayload,
   secret: string,
 ): Promise<string> {
+  assertUnsubscribeSecret(secret, "signAddressUnsubscribeToken");
   const addressHash = hashUnsubscribeAddress(payload.address);
   if (addressHash === undefined) {
     throw new Error(
@@ -118,67 +136,126 @@ export async function signAddressUnsubscribeToken(
   );
 }
 
-export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): Hono {
-  const { db, jwtSecret } = options;
-  const encodedSecret = new TextEncoder().encode(jwtSecret);
-  const app = new Hono();
-
-  app.get("/unsubscribe", async (c) => {
-    const token = c.req.query("token");
-    if (!token) {
-      return c.text("Missing token", 400);
+type VerifiedUnsubscribe =
+  | {
+      readonly kind: "address";
+      readonly tenantId: TenantId;
+      readonly addressHash: string;
+      readonly notificationType: string;
+      readonly channel: string;
     }
+  | {
+      readonly kind: "user";
+      readonly tenantId: TenantId;
+      readonly userId: string;
+      readonly notificationType: string;
+      readonly channel: string;
+    };
 
-    let verifiedPayload: jose.JWTPayload;
-    try {
-      ({ payload: verifiedPayload } = await jose.jwtVerify(token, encodedSecret, {
-        issuer: "kumiko:unsubscribe",
-      }));
-    } catch {
-      return c.text("Invalid or expired token", 400);
-    }
+export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): ExtraRouteDefinition {
+  assertUnsubscribeSecret(options.secret, "createUnsubscribeRoute");
+  const encodedSecret = new TextEncoder().encode(options.secret);
 
-    const addressAttempt = addressUnsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
-    if (addressAttempt.success) {
-      const parsed = addressAttempt.data;
-      if (parsed.sub !== parsed.addressHash) {
-        return c.text("Invalid or expired token", 400);
+  return signatureRoute<VerifiedUnsubscribe>({
+    method: "GET",
+    path: DELIVERY_UNSUBSCRIBE_PATH,
+    entry: "signature",
+    // Every throw here must become the same ExtraRouteRejection(400,
+    // unsubscribe_token_invalid) — anything else falls through to the
+    // framework's generic 401 extra_route_signature_invalid mapping, which
+    // would leak jose's internal error text into the response body.
+    verify: async ({ query }) => {
+      try {
+        const token = query["token"];
+        if (!token) {
+          throw new ExtraRouteRejection(
+            400,
+            UNSUBSCRIBE_TOKEN_INVALID_BODY,
+            "missing unsubscribe token",
+          );
+        }
+
+        const { payload: verifiedPayload } = await jose.jwtVerify(token, encodedSecret, {
+          issuer: "kumiko:unsubscribe",
+        });
+
+        const addressAttempt = addressUnsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
+        if (addressAttempt.success) {
+          const parsed = addressAttempt.data;
+          if (parsed.sub !== parsed.addressHash) {
+            throw new ExtraRouteRejection(
+              400,
+              UNSUBSCRIBE_TOKEN_INVALID_BODY,
+              "address token subject mismatch",
+            );
+          }
+          // @cast-boundary engine-bridge — string post-zod → branded TenantId
+          const tenantId = parsed.tenantId as TenantId;
+          return {
+            kind: "address",
+            tenantId,
+            addressHash: parsed.addressHash,
+            notificationType: parsed.notificationType,
+            channel: parsed.channel,
+          };
+        }
+
+        const userAttempt = unsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
+        if (!userAttempt.success) {
+          throw new ExtraRouteRejection(
+            400,
+            UNSUBSCRIBE_TOKEN_INVALID_BODY,
+            "unsubscribe token payload matched neither schema",
+          );
+        }
+        const parsed = userAttempt.data;
+        // @cast-boundary engine-bridge — string post-zod → branded TenantId
+        const tenantId = parsed.tenantId as TenantId;
+        return {
+          kind: "user",
+          tenantId,
+          userId: parsed.sub,
+          notificationType: parsed.notificationType,
+          channel: parsed.channel,
+        };
+      } catch (err) {
+        if (err instanceof ExtraRouteRejection) throw err;
+        throw new ExtraRouteRejection(
+          400,
+          UNSUBSCRIBE_TOKEN_INVALID_BODY,
+          "unsubscribe token verification failed",
+        );
       }
-      // @cast-boundary engine-bridge — string post-zod → branded TenantId
-      const tenantId = parsed.tenantId as TenantId;
-      const actor = { id: parsed.addressHash, tenantId, roles: SYSTEM_ROLES };
-      const tdb = createTenantDb(db, tenantId, "system");
-      await upsertAddressOptOut(tdb, actor, {
-        tenantId,
-        addressHash: parsed.addressHash,
-        notificationType: parsed.notificationType,
-        channel: parsed.channel,
+    },
+    handler: async (c, verified, deps) => {
+      const payload =
+        verified.kind === "address"
+          ? {
+              addressHash: verified.addressHash,
+              notificationType: verified.notificationType,
+              channel: verified.channel,
+            }
+          : {
+              userId: verified.userId,
+              notificationType: verified.notificationType,
+              channel: verified.channel,
+            };
+
+      // Token-verify passed — everything below is a legitimate write. Don't
+      // swallow write-errors as "invalid token", that would mask real bugs
+      // (e.g. events-table missing, DB down) behind a misleading 400.
+      const dispatched = await deps.dispatchSystemWrite({
+        handlerQn:
+          verified.kind === "address"
+            ? DeliveryHandlers.unsubscribeAddress
+            : DeliveryHandlers.unsubscribeUser,
+        tenantId: verified.tenantId,
+        payload,
       });
+      if (!dispatched.isSuccess) {
+        return c.text("Unsubscribe failed", 500);
+      }
       return c.text("You have been unsubscribed.", 200);
-    }
-
-    const userAttempt = unsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
-    if (!userAttempt.success) {
-      return c.text("Invalid or expired token", 400);
-    }
-    const parsed = userAttempt.data;
-    // @cast-boundary engine-bridge — string post-zod → branded TenantId
-    const tenantId = parsed.tenantId as TenantId;
-
-    // Token-verify passed — everything below is a legitimate write. Don't
-    // swallow write-errors as "invalid token", that would mask real bugs
-    // (e.g. events-table missing, DB down) behind a misleading 400.
-    const actor = { id: parsed.sub, tenantId, roles: SYSTEM_ROLES };
-    const tdb = createTenantDb(db, tenantId, "system");
-    await upsertPreference(tdb, actor, {
-      tenantId,
-      userId: parsed.sub,
-      notificationType: parsed.notificationType,
-      channel: parsed.channel,
-      enabled: false,
-    });
-    return c.text("You have been unsubscribed.", 200);
+    },
   });
-
-  return app;
 }

package/src/delivery/upsert-preference.ts

@@ -5,14 +5,18 @@
 // concurrent requests — typical case: a user clicks the same "unsubscribe"
 // email link three times in a second.
 //
-// The fix: try the optimistic path (lookup + create|update), and on a
-// unique-index-violation race from a parallel create, re-lookup and fall
-// through to update. Worst case: one extra roundtrip for the loser of
-// the race. Happy path: same number of queries as the pre-ES upsert.
+// The fix: the aggregate id is deterministic (tenant+user+type+channel), so
+// concurrent first-time clicks collide at the event-store append itself
+// (expectedVersion 0, confined to a savepoint) instead of racing past two
+// independent creates and leaving an orphaned `created` event behind. The
+// loser's create() comes back as a `version_conflict` failure; re-lookup and
+// fall through to update, or no-op if the winner already set the target
+// `enabled` state.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 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 { notificationPreferenceEntity, notificationPreferencesTable } from "./tables";
 
 const executor = createEventStoreExecutor(
@@ -21,11 +25,15 @@ const executor = createEventStoreExecutor(
   { entityName: "notification-preference" },
 );
 
-// Konkretes Lookup-Result-Shape — nur die zwei Felder die der upsert
+// Konkretes Lookup-Result-Shape — nur die Felder die der upsert
 // tatsächlich für den Update-Path braucht. Vermeidet `row["x"] as T` index-
 // access casts; der Generic-Param am fetchOne macht den Cast zentralisiert
 // im Helper (db-row-boundary), nicht 4× pro Callsite.
-type PreferenceLookupRow = { readonly id: string; readonly version: number };
+type PreferenceLookupRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly enabled: boolean;
+};
 
 // @wrapper-known semantic-alias
 async function lookup(
@@ -51,11 +59,25 @@ export type UpsertPreferenceInput = {
   readonly enabled: boolean;
 };
 
+// One row per (tenant, user, type, channel): folding the tuple into the
+// aggregate id means two concurrent first-time clicks collide on the same
+// stream at append instead of racing two independent creates.
+function preferenceAggregateId(
+  tenantId: TenantId,
+  userId: string,
+  notificationType: string,
+  channel: string,
+): string {
+  return generateDeterministicId(
+    "delivery:notification-preference",
+    `${tenantId}|${userId}|${notificationType}|${channel}`,
+  );
+}
+
 /**
  * Idempotent "set-this-preference-to-enabled-state" against the preferences
  * aggregate stream. Emits either `.created` (first time) or `.updated`
- * (subsequent) and catches the race-induced unique-index violation as a
- * fallback to update.
+ * (subsequent) and converges a concurrent create-race onto the winner's row.
  */
 export async function upsertPreference(
   db: TenantDb,
@@ -71,6 +93,7 @@ export async function upsertPreference(
   );
 
   if (existing) {
+    if (existing.enabled === input.enabled) return { isSuccess: true, data: input };
     const result = await executor.update(
       {
         id: existing.id,
@@ -84,57 +107,48 @@ export async function upsertPreference(
     return { isSuccess: true, data: input };
   }
 
-  try {
-    const result = await executor.create(
-      {
-        userId: input.userId,
-        notificationType: input.notificationType,
-        channel: input.channel,
-        enabled: input.enabled,
-      },
-      actor,
-      db,
-    );
-    if (!result.isSuccess) return result;
-    return { isSuccess: true, data: input };
-  } catch (err) {
-    // Race-fallback: another request beat us to the insert between our
-    // lookup and the executor.create. The unique-index on
-    // (tenant, user, type, channel) fires Postgres error 23505. Only that
-    // specific error triggers the retry; DB-disconnect or any other
-    // failure must bubble up unchanged so callers see the real cause.
-    if (!isUniqueViolation(err)) throw err;
-    const afterRace = await lookup(
-      db,
-      input.tenantId,
-      input.userId,
-      input.notificationType,
-      input.channel,
-    );
-    if (!afterRace) throw err;
-    const result = await executor.update(
-      {
-        id: afterRace.id,
-        version: afterRace.version,
-        changes: { enabled: input.enabled },
-      },
-      actor,
-      db,
-    );
-    if (!result.isSuccess) return result;
-    return { isSuccess: true, data: input };
-  }
-}
+  const id = preferenceAggregateId(
+    input.tenantId,
+    input.userId,
+    input.notificationType,
+    input.channel,
+  );
+  const created = await executor.create(
+    {
+      id,
+      userId: input.userId,
+      notificationType: input.notificationType,
+      channel: input.channel,
+      enabled: input.enabled,
+    },
+    actor,
+    db,
+  );
+  if (created.isSuccess) return { isSuccess: true, data: input };
+  if (created.error.code !== "version_conflict") return created;
 
-// Narrow detection for Postgres "duplicate key violates unique constraint"
-// (SQLSTATE 23505). Drivers wrap the DB error in varying envelopes; we
-// check the `code` field plus a string-match fallback so the match survives
-// minor driver-version shifts without drifting wide.
-export function isUniqueViolation(err: unknown): boolean {
-  if (typeof err !== "object" || err === null) return false;
-  const e = err as { code?: unknown; cause?: { code?: unknown }; message?: unknown }; // @cast-boundary error-details
-  if (e.code === "23505") return true;
-  if (e.cause && typeof e.cause === "object" && e.cause.code === "23505") return true;
-  if (typeof e.message === "string" && e.message.includes("23505")) return true;
-  return false;
+  // Race-fallback: another request's create already won this deterministic
+  // id between our lookup and this create. Re-lookup and converge onto its
+  // row — no-op if it already set the target `enabled`, since relooking the
+  // same version and updating would version_conflict all but one loser.
+  const afterRace = await lookup(
+    db,
+    input.tenantId,
+    input.userId,
+    input.notificationType,
+    input.channel,
+  );
+  if (!afterRace) return created;
+  if (afterRace.enabled === input.enabled) return { isSuccess: true, data: input };
+  const result = await executor.update(
+    {
+      id: afterRace.id,
+      version: afterRace.version,
+      changes: { enabled: input.enabled },
+    },
+    actor,
+    db,
+  );
+  if (!result.isSuccess) return result;
+  return { isSuccess: true, data: input };
 }

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

@@ -122,6 +122,7 @@ const pngBytes = new Uint8Array([
 ]);
 const textBytes = new TextEncoder().encode("plain text, not a supported mime type");
 const oversizedPdfBytes = new Uint8Array(PROVIDER_A_MAX_BYTES + 100);
+oversizedPdfBytes.set(new TextEncoder().encode("%PDF-1.4"));
 // Real ZIP local-file-header signature — validateFileContent content-verifies
 // docx uploads against it independent of options.accept.
 const docxBytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, ...Array(32).fill(0)]);

package/src/file-derivatives/__tests__/public-variant-cross-tenant.integration.test.ts

@@ -73,7 +73,8 @@ async function uploadImage(
 ): Promise<string> {
   const token = await stack.jwt.sign(asUser);
   const fd = new FormData();
-  fd.append("file", new File([Buffer.from([1, 2, 3])], "img.jpg", { type: "image/jpeg" }));
+  const jpegBytes = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, ...Array(10).fill(0)]);
+  fd.append("file", new File([Buffer.from(jpegBytes)], "img.jpg", { type: "image/jpeg" }));
   fd.append("entityType", "gadget");
   fd.append("entityId", entityId);
   fd.append("fieldName", "img");

package/src/file-derivatives/__tests__/public-variant-predicate-args.integration.test.ts

@@ -98,7 +98,8 @@ beforeEach(async () => {
 async function uploadGadgetImage(): Promise<string> {
   const token = await stack.jwt.sign(user);
   const fd = new FormData();
-  fd.append("file", new File([Buffer.from([1, 2, 3])], "img.jpg", { type: "image/jpeg" }));
+  const jpegBytes = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, ...Array(10).fill(0)]);
+  fd.append("file", new File([Buffer.from(jpegBytes)], "img.jpg", { type: "image/jpeg" }));
   fd.append("entityType", "gadget");
   fd.append("entityId", ENTITY_ID);
   fd.append("fieldName", "img");

package/src/file-derivatives/__tests__/public-variant-route.integration.test.ts

@@ -158,7 +158,10 @@ async function uploadFile(
   // extension, not the declared part Content-Type — so the extension must
   // match `mimeType` for the upload to actually carry it through.
   const extension = mimeType.split("/")[1]?.split("+")[0] ?? "bin";
-  fd.append("file", new File([Buffer.from([1, 2, 3])], `img.${extension}`, { type: mimeType }));
+  // Real JPEG magic bytes so validateFileContent doesn't 400 the default
+  // image/jpeg uploads; svg has no signature so this covers both cases.
+  const jpegBytes = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, ...Array(10).fill(0)]);
+  fd.append("file", new File([Buffer.from(jpegBytes)], `img.${extension}`, { type: mimeType }));
   fd.append("entityType", attach.entityType);
   fd.append("entityId", attach.entityId);
   fd.append("fieldName", fieldName);

package/src/shared/index.ts

@@ -16,6 +16,7 @@ export { entitiesOf } from "./entities-of";
 export { isWithinGracePeriod } from "./grace-period";
 export { hasWhereRule } from "./has-where-rule";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+export { isTenantDb } from "./is-tenant-db";
 export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter";
 export { mapWithConcurrency } from "./map-with-concurrency";
 export { joinRowParentIsVisible, parentRowIsVisible } from "./parent-visibility";

package/src/shared/is-tenant-db.ts

@@ -0,0 +1,9 @@
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+
+// Structural probe: a TenantDb and a raw DbRunner both expose fetchOne/selectMany,
+// so the shape alone can't tell them apart — `unsafeRaw` only exists on TenantDb.
+// Shared so retention/compliance-profile resolvers that accept either (bulk cron
+// vs. per-hook TenantDb) branch through one predicate instead of duplicating it.
+export function isTenantDb(db: DbRunner | TenantDb): db is TenantDb {
+  return typeof (db as Partial<TenantDb>).unsafeRaw === "function";
+}

package/src/user-data-rights/__tests__/file-storage-unification.integration.test.ts

@@ -141,7 +141,11 @@ describe("#608 unified file-storage :: route upload + GDPR erasure hit one store
     await seed.seedMembership(userId, TENANT_SYSTEM);
     const uploader: SessionUser = { id: userId, tenantId: TENANT_SYSTEM, roles: ["Member"] };
 
-    const res = await uploadAs(uploader, "secret.pdf", new Uint8Array([10, 20, 30, 40]));
+    const res = await uploadAs(
+      uploader,
+      "secret.pdf",
+      new TextEncoder().encode("%PDF-1.4 minimal"),
+    );
     expect(res.status).toBe(201);
     const { storageKey } = (await res.json()) as { storageKey: string };