@cosmicdrift/kumiko-bundled-features 0.312.0 → 0.313.0

package/src/delivery/delivery-service.ts

@@ -14,9 +14,11 @@ import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipelin
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
+import { hashUnsubscribeAddress } from "./address-opt-out";
 import { appendAttemptEvent, logAttempt } from "./attempt-log";
 import { buildChannelContext } from "./channel-context";
 import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryPriorityRank } from "./constants";
+import { isAddressOptedOut } from "./db/queries/address-opt-outs";
 import { selectNotificationPreferences } from "./db/queries/preferences";
 import {
   type ChannelContext,
@@ -479,6 +481,36 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       const message = buildMessage(notificationType, data, channel.name);
       if (!address) continue;
 
+      // Address opt-out (critical priority skips it, same rule as user
+      // preferences). No blind-index key configured → no hash → nothing to
+      // look up, skip the check instead of failing the send.
+      if (priority !== "critical") {
+        const addressHash = hashUnsubscribeAddress(address);
+        if (addressHash !== undefined) {
+          const optedOut = await isAddressOptedOut(
+            db,
+            tenantId,
+            addressHash,
+            notificationType,
+            channel.name,
+          );
+          if (optedOut) {
+            await logDelivery({
+              tenantId,
+              notificationType,
+              channel: channel.name,
+              recipientId,
+              // The recipient withdrew — suppressed attempts must not keep recording the address.
+              recipientAddress: null,
+              status: "skipped",
+              error: "unsubscribed",
+              priority,
+            });
+            continue;
+          }
+        }
+      }
+
       if (rateLimit) {
         const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
         if (!allowed) {

package/src/delivery/feature.ts

@@ -23,6 +23,8 @@ import { deliveryRenderJob, deliverySendJob } from "./jobs";
 import {
   deliveryAttemptsTable,
   deliveryAttemptsTableMeta,
+  notificationAddressOptOutEntity,
+  notificationAddressOptOutsTable,
   notificationPreferenceEntity,
   notificationPreferencesTable,
 } from "./tables";
@@ -40,7 +42,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, logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
+      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",
@@ -56,6 +58,12 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     r.entity("notification-preference", notificationPreferenceEntity, {
       table: notificationPreferencesTable,
     });
+    // Same ride-along reason as notification-preference above: the
+    // (tenant,addressHash,type,channel) uniqueIndex lives only on the
+    // physical table.
+    r.entity("notification-address-opt-out", notificationAddressOptOutEntity, {
+      table: notificationAddressOptOutsTable,
+    });
     r.storeTable(deliveryAttemptsTableMeta, {
       reason: "read_side.delivery_attempt_log",
     });

package/src/delivery/index.ts

@@ -1,3 +1,4 @@
+export { hashUnsubscribeAddress } from "./address-opt-out";
 export type { DeliveryStatusValue } from "./constants";
 export {
   DELIVERY_CHANNEL_EXTENSION,
@@ -19,6 +20,8 @@ export {
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature";
 export {
   deliveryAttemptsTable,
+  notificationAddressOptOutEntity,
+  notificationAddressOptOutsTable,
   notificationPreferenceEntity,
   notificationPreferencesTable,
 } from "./tables";
@@ -38,7 +41,9 @@ export {
   type RendererInput,
 } from "./types";
 export {
+  type AddressUnsubscribeTokenPayload,
   createUnsubscribeRoute,
+  signAddressUnsubscribeToken,
   signUnsubscribeToken,
   type UnsubscribeRouteOptions,
   type UnsubscribeTokenPayload,

package/src/delivery/tables.ts

@@ -105,3 +105,40 @@ export const notificationPreferencesTable = pgTable(
     ),
   ],
 );
+
+// Opt-out for a recipient ADDRESS that has no user account (direct sends via
+// `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).
+export const notificationAddressOptOutEntity = createEntity({
+  table: "read_notification_address_opt_outs",
+  fields: {
+    addressHash: createTextField({ required: true, personal: false, reason: "keyed_hash" }),
+    notificationType: createTextField({
+      required: true,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    channel: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+  },
+});
+
+export const notificationAddressOptOutsTable = pgTable(
+  "read_notification_address_opt_outs",
+  {
+    ...buildBaseColumns(false, "uuid"),
+    addressHash: text("address_hash").notNull(),
+    notificationType: text("notification_type").notNull(),
+    channel: text("channel").notNull(),
+  },
+  (table) => [
+    uniqueIndex("read_notification_address_opt_outs_unique").on(
+      table.tenantId,
+      table.addressHash,
+      table.notificationType,
+      table.channel,
+    ),
+  ],
+);

package/src/delivery/unsubscribe.ts

@@ -3,17 +3,38 @@ 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";
 
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+//
+// `kind` is explicitly typed as "absent or undefined, nothing else" here
+// (not bare `.optional()`, which would also accept any other value on an
+// unrelated key) so an address-token payload — which always carries
+// `kind: "address"` — fails this schema instead of silently parsing with
+// `addressHash` mistaken for a userId.
 const unsubscribeJwtPayloadSchema = z.object({
+  kind: z.undefined().optional(),
   sub: z.string().min(1),
   tenantId: z.string().min(1),
   notificationType: z.string().min(1),
   channel: z.string().min(1),
 });
 
+// Address-token payload. `sub` and `addressHash` are the same value (the
+// subject claim IS the blind-index hash) — kept as two fields because the
+// subject claim is jose's own mechanism while `addressHash` is what the
+// route actually writes; the handler cross-checks them below.
+const addressUnsubscribeJwtPayloadSchema = z.object({
+  kind: z.literal("address"),
+  sub: z.string().min(1),
+  tenantId: z.string().min(1),
+  notificationType: z.string().min(1),
+  channel: z.string().min(1),
+  addressHash: z.string().min(1),
+});
+
 export type UnsubscribeTokenPayload = {
   readonly userId: string;
   readonly tenantId: TenantId;
@@ -21,6 +42,13 @@ export type UnsubscribeTokenPayload = {
   readonly channel: string;
 };
 
+export type AddressUnsubscribeTokenPayload = {
+  readonly tenantId: TenantId;
+  readonly address: string;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
 export type UnsubscribeRouteOptions = {
   readonly db: DbConnection;
   readonly jwtSecret: string;
@@ -51,6 +79,45 @@ export async function signUnsubscribeToken(
     .sign(encodedSecret);
 }
 
+/**
+ * Signs an unsubscribe link for a recipient ADDRESS with no user account
+ * (direct sends via `ctx.notify(type, { route: { email } })`). Throws when
+ * no blind-index key is configured — fail closed, since without a key the
+ * opt-out row this token later writes could never be matched against a
+ * future send (the hash wouldn't be reproducible).
+ */
+export async function signAddressUnsubscribeToken(
+  payload: AddressUnsubscribeTokenPayload,
+  secret: string,
+): Promise<string> {
+  const addressHash = hashUnsubscribeAddress(payload.address);
+  if (addressHash === undefined) {
+    throw new Error(
+      "signAddressUnsubscribeToken requires a configured blind-index key (configureBlindIndexKey)",
+    );
+  }
+  const encodedSecret = new TextEncoder().encode(secret);
+  return (
+    new jose.SignJWT({
+      tenantId: payload.tenantId,
+      notificationType: payload.notificationType,
+      channel: payload.channel,
+      addressHash,
+      kind: "address",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .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.
+      .sign(encodedSecret)
+  );
+}
+
 export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): Hono {
   const { db, jwtSecret } = options;
   const encodedSecret = new TextEncoder().encode(jwtSecret);
@@ -62,34 +129,52 @@ export function createUnsubscribeRoute(options: UnsubscribeRouteOptions): Hono {
       return c.text("Missing token", 400);
     }
 
-    let userId: string;
-    let tenantId: TenantId;
-    let notificationType: string;
-    let channel: string;
+    let verifiedPayload: jose.JWTPayload;
     try {
-      const { payload } = await jose.jwtVerify(token, encodedSecret, {
+      ({ payload: verifiedPayload } = await jose.jwtVerify(token, encodedSecret, {
         issuer: "kumiko:unsubscribe",
-      });
-      const parsed = unsubscribeJwtPayloadSchema.parse(payload);
-      userId = parsed.sub;
-      // @cast-boundary engine-bridge — string post-zod → branded TenantId
-      tenantId = parsed.tenantId as TenantId;
-      notificationType = parsed.notificationType;
-      channel = parsed.channel;
+      }));
     } catch {
       return c.text("Invalid or expired token", 400);
     }
 
+    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);
+      }
+      // @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,
+      });
+      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: userId, tenantId, roles: SYSTEM_ROLES };
+    const actor = { id: parsed.sub, tenantId, roles: SYSTEM_ROLES };
     const tdb = createTenantDb(db, tenantId, "system");
     await upsertPreference(tdb, actor, {
       tenantId,
-      userId,
-      notificationType,
-      channel,
+      userId: parsed.sub,
+      notificationType: parsed.notificationType,
+      channel: parsed.channel,
       enabled: false,
     });
     return c.text("You have been unsubscribed.", 200);

package/src/delivery/upsert-preference.ts

@@ -130,7 +130,7 @@ export async function upsertPreference(
 // (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.
-function isUniqueViolation(err: unknown): boolean {
+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;

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

@@ -22,6 +22,7 @@ import {
   createTestUser,
   setupTestStack,
   type TestStack,
+  TestUsers,
   testTenantId,
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
@@ -31,6 +32,7 @@ import {
 import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { createConfigFeature } from "../../config";
 import { fileFoundationFeature } from "../../file-foundation";
+import { createTenantFeature, TenantHandlers } from "../../tenant";
 import { createFileDerivativesFeature } from "../feature";
 import type { DerivativePublicPredicateArgs } from "../handlers/public-variant.query";
 import { PUBLIC_VARIANT_BY_FILE_REF_QN } from "../handlers/public-variant-by-file-ref.query";
@@ -94,6 +96,7 @@ describe("file-derivatives :: publicTenantResolution 'fileRef' — cross-tenant
     stack = await setupTestStack({
       features: [
         createConfigFeature(),
+        createTenantFeature(),
         fileFoundationFeature,
         createFilesFeature(),
         createFileDerivativesFeature({
@@ -104,6 +107,16 @@ describe("file-derivatives :: publicTenantResolution 'fileRef' — cross-tenant
       ],
       files: { storageProvider: createInMemoryFileProvider() },
     });
+    await stack.http.writeOk(
+      TenantHandlers.create,
+      { id: TENANT_A, key: "cross-tenant-a", name: "Cross Tenant A" },
+      TestUsers.systemAdmin,
+    );
+    await stack.http.writeOk(
+      TenantHandlers.create,
+      { id: TENANT_B, key: "cross-tenant-b", name: "Cross Tenant B" },
+      TestUsers.systemAdmin,
+    );
   });
 
   afterAll(async () => {
@@ -169,6 +182,33 @@ describe("file-derivatives :: publicTenantResolution 'fileRef' — cross-tenant
   test("PUBLIC_VARIANT_BY_FILE_REF_QN is registered on the stack in 'fileRef' mode", () => {
     expect(stack.registry.getQueryHandler(PUBLIC_VARIANT_BY_FILE_REF_QN)).toBeDefined();
   });
+
+  // Runs last and deliberately leaves tenant B disabled — mirrors the
+  // "disabled tenant" ordering convention in
+  // tenant/__tests__/multi-tenant.integration.test.ts.
+  describe("a disabled tenant answers like an unknown fileRef", () => {
+    test("tenant B's public variant 200s before disable, then 404s identically to an unknown fileRef after disable", async () => {
+      const fileId = await uploadImage(stack, userB, "public-1");
+      const beforeRes = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+      expect(beforeRes.status).toBe(200);
+
+      const disableResult = await stack.http.writeOk(
+        TenantHandlers.disable,
+        { id: TENANT_B },
+        TestUsers.systemAdmin,
+      );
+      expect(disableResult).toBeTruthy();
+
+      const afterRes = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+      const unknownFileRefRes = await stack.app.request(
+        `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
+      );
+
+      expect(afterRes.status).toBe(404);
+      expect(unknownFileRefRes.status).toBe(404);
+      expect(await afterRes.text()).toBe(await unknownFileRefRes.text());
+    });
+  });
 });
 
 describe("file-derivatives :: default ('host') mode is unchanged", () => {

package/src/file-derivatives/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "file-derivatives fileRef mode now 404s a disabled/destroy-lifecycle tenant like an unknown fileRef",
+    "detail": "publicTenantResolution:\"fileRef\" resolved a variant's tenant straight off\nthe FileRef row, without checking whether that tenant was still enabled or\npast `active` in its destroy lifecycle — a disabled or destroy-requested\ntenant's public variants stayed reachable through the shared host. The\nby-fileRef handler now also loads the FileRef-tenant's row and, via the\nnew `isTenantServingPublicContent` predicate (isEnabled && status ===\n\"active\"), 404s identically to an unknown fileRef when it isn't serving.\n`publicTenantResolution: \"fileRef\"` now requires the `tenant` feature to\nbe mounted (fails boot otherwise) — no migration needed for apps that\nalready mount `tenant`, which every fileRef-mode consumer does today."
+  },
   {
     "version": "0.310.0",
     "type": "improvement",

package/src/file-derivatives/feature.ts

@@ -160,6 +160,11 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
       // would expose its unsafeRaw, cross-tenant FileRef lookup via the
       // generic `/api` query dispatch even in default "host" mode.
       if (byFileRef) {
+        // The handler reads the FileRef-tenant's row to keep a blocked
+        // tenant's public variants from staying reachable — require the
+        // dependency so a missing mount fails boot, not the tenant check
+        // silently no-op-ing at request time.
+        r.requires("tenant");
         r.queryHandler(publicVariantByFileRefQuery);
       }
 

package/src/file-derivatives/handlers/public-variant-by-file-ref.query.ts

@@ -6,14 +6,24 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  isTenantServingPublicContent,
+  type TenantLifecycleStatus,
+  tenantTable,
+} from "../../tenant";
 import { PUBLIC_VARIANT_QN, publicVariantPayloadSchema } from "./public-variant.query";
 
 type FileRefTenantRow = {
   readonly tenantId: TenantId;
 };
 
+type TenantGateRow = {
+  readonly isEnabled: boolean;
+  readonly status: TenantLifecycleStatus;
+};
+
 const BY_FILE_REF_ESCAPE_HATCH_REASON =
-  "shared public host serves every tenant's public variants; the FileRef row names the tenant, and publicVariantQuery's isPublic gate still runs inside that tenant via queryAs";
+  "shared public host serves every tenant's public variants; the FileRef row names the tenant, and publicVariantQuery's isPublic gate still runs inside that tenant via queryAs — reading the FileRef's tenant row (isEnabled/status) first so a blocked tenant 404s identically to an unknown fileRef";
 
 // Full QN this handler is registered under, mirrors PUBLIC_VARIANT_QN.
 export const PUBLIC_VARIANT_BY_FILE_REF_QN = "file-derivatives:query:public-variant-by-file-ref";
@@ -28,13 +38,20 @@ export const publicVariantByFileRefQuery = defineQueryHandler({
     reason: BY_FILE_REF_ESCAPE_HATCH_REASON,
   },
   handler: async (query, ctx) => {
-    const row = await fetchOne<FileRefTenantRow>(
-      ctx.db.unsafeRaw(BY_FILE_REF_ESCAPE_HATCH_REASON),
-      fileRefsTable,
-      { id: query.payload.fileRefId, isDeleted: false },
-    );
+    const db = ctx.db.unsafeRaw(BY_FILE_REF_ESCAPE_HATCH_REASON);
+    const row = await fetchOne<FileRefTenantRow>(db, fileRefsTable, {
+      id: query.payload.fileRefId,
+      isDeleted: false,
+    });
     if (!row || !isUuid(row.tenantId)) return null;
 
+    // A blocked tenant (disabled, or past active in its destroy lifecycle)
+    // must 404 identically to an unknown fileRef — otherwise this shared
+    // public host would keep serving a tenant's public variants after it
+    // was disabled or asked to be destroyed.
+    const tenant = await fetchOne<TenantGateRow>(db, tenantTable, { id: row.tenantId });
+    if (!tenant || !isTenantServingPublicContent(tenant)) return null;
+
     return ctx.queryAs(createAnonymousUser(row.tenantId), PUBLIC_VARIANT_QN, query.payload);
   },
 });

package/src/shared/index.ts

@@ -25,6 +25,7 @@ export {
   redeemRowBoundGrant,
   signRowBoundGrant,
 } from "./row-bound-grant";
+export { runInSubTransaction } from "./run-in-sub-transaction";
 export { sessionField } from "./session-field";
 export { sessionLocaleField } from "./session-locale-field";
 export { sessionTimezoneField } from "./session-timezone-field";
@@ -35,6 +36,14 @@ export {
   type VerifyResult,
   verifyToken,
 } from "./signed-token";
-export { createSingleUseTokenStore } from "./single-use-token-store";
+export {
+  EXT_SIGNUP_HANDOVER,
+  findSignupHandoverProvider,
+  isSignupHandoverProvider,
+  SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE,
+  type SignupHandoverBinding,
+  type SignupHandoverProvider,
+} from "./signup-handover";
+export { createSingleUseTokenStore, hashSingleUseToken } from "./single-use-token-store";
 export type { SystemQueryFn } from "./system-query";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";

package/src/shared/run-in-sub-transaction.ts

@@ -0,0 +1,35 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+// Per-unit sub-transaction (one user, one purged row), nesting-aware across both db shapes:
+//   - top-level connection (Bun.SQL / postgres-js Sql) → `.begin` (BEGIN)
+//   - TransactionSql (inside the dispatcher's outer tx, where every
+//     writeHandler already runs) → `.savepoint` (SAVEPOINT)
+// A TransactionSql has no `.begin`, so the previous unconditional `.begin`
+// threw "is not a function" on every user when invoked through the dispatcher
+// (the cron path) → zero deletions in production, while direct-connection tests
+// stayed green. Selecting the available method makes the sub-tx work in both
+// contexts; on throw the savepoint rolls back just this user (others survive).
+export async function runInSubTransaction<T>(
+  db: DbRunner,
+  fn: (tx: DbRunner) => Promise<T>,
+): Promise<T> {
+  // `db` is already the raw runner (the handler passes ctx.db.unsafeRaw(...),
+  // the tests a top-level connection) — cast to read the transaction surface directly,
+  // without asRawClient (a test-only escape hatch).
+  const runner = db as {
+    begin?: (f: (tx: DbRunner) => Promise<T>) => Promise<T>;
+    savepoint?: (f: (tx: DbRunner) => Promise<T>) => Promise<T>;
+  };
+  // savepoint-first: empirically (Bun 1.3.14, not re-checked on 1.4.0) the
+  // surfaces are NOT mutually exclusive — a TransactionSql exposes begin AND
+  // savepoint, only the top-level connection has begin alone. begin-first
+  // picked the nested BEGIN inside a tx (the incident class above);
+  // savepoint-first hits the savepoint there and falls back to begin top-level.
+  const open = runner.savepoint ?? runner.begin;
+  if (!open) {
+    throw new Error(
+      "runInSubTransaction: db exposes neither .begin nor .savepoint — cannot open a sub-transaction",
+    );
+  }
+  return open.call(runner, fn);
+}

package/src/shared/signup-handover.ts

@@ -0,0 +1,67 @@
+// Cross-device try-first handover (kumiko-framework#3035 follow-up,
+// offlot-app#454): signup-request runs in whichever browser the activation
+// link ends up opened in, which may not be the one holding the anonymous
+// visitor's tenant-handover grant. This extension point lets
+// auth-email-password bind a verified grant to the signup token server-side
+// — without knowing anything about tenant-handover's row-bound-grant
+// mechanics — so signup-confirm can claim the data into the freshly
+// provisioned tenant regardless of which browser it runs in.
+//
+// The grant itself never crosses this boundary: verifyGrant returns only
+// the { entityType, rowId, sourceTenantId } binding, and mintClaim returns a
+// freshly signed short-lived token rather than handing back the original.
+
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+
+export const EXT_SIGNUP_HANDOVER = "signupHandover" as const;
+
+// Part of the contract: a provider's minted claim write may reject two
+// different ways. Benign — this code, nothing was written (forged,
+// expired, or already spent) — a caller redeeming the claim nested in its
+// own write can log and carry on. Anything else means the provider's write
+// already applied a PARTIAL change before failing (e.g. a root row moved
+// but a declared child couldn't) — the caller must roll its own work back
+// together with it, never treat that as a skippable no-op.
+export const SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE = "invalid_or_expired_grant" as const;
+
+export type SignupHandoverBinding = {
+  readonly entityType: string;
+  readonly rowId: string;
+  readonly sourceTenantId: string;
+};
+
+export type SignupHandoverProvider = {
+  verifyGrant(args: {
+    readonly db: DbRunner;
+    readonly registry: Registry;
+    readonly entityType: string;
+    readonly token: string;
+  }): Promise<SignupHandoverBinding | null>;
+  mintClaim(binding: SignupHandoverBinding): {
+    readonly qualifiedName: string;
+    readonly payload: { readonly token: string; readonly entityType: string };
+  };
+};
+
+export function isSignupHandoverProvider(options: unknown): options is SignupHandoverProvider {
+  return (
+    typeof options === "object" &&
+    options !== null &&
+    typeof (options as Record<string, unknown>)["verifyGrant"] === "function" &&
+    typeof (options as Record<string, unknown>)["mintClaim"] === "function"
+  );
+}
+
+export function findSignupHandoverProvider(registry: Registry): SignupHandoverProvider | undefined {
+  for (const usage of registry.getExtensionUsages(EXT_SIGNUP_HANDOVER)) {
+    if (isSignupHandoverProvider(usage.options)) return usage.options;
+  }
+  return undefined;
+}
+
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [EXT_SIGNUP_HANDOVER]: SignupHandoverProvider;
+  }
+}

package/src/shared/single-use-token-store.ts

@@ -49,7 +49,10 @@
 import { createHash } from "node:crypto";
 import type Redis from "ioredis";
 
-function hashToken(token: string): string {
+// Exported so a caller that needs a byte-compatible key in a sibling Redis
+// namespace (e.g. a token↔binding side-mapping) can derive it without
+// re-implementing sha256-of-token — see auth-email-password/signup-token-store.ts.
+export function hashSingleUseToken(token: string): string {
   return createHash("sha256").update(token).digest("hex");
 }
 
@@ -59,7 +62,7 @@ export function createSingleUseTokenStore(prefixes: {
   readonly burnPrefix: string;
 }) {
   function tokenKey(token: string): string {
-    return `${prefixes.tokenPrefix}${hashToken(token)}`;
+    return `${prefixes.tokenPrefix}${hashSingleUseToken(token)}`;
   }
   // Builds the forward key from an already-hashed value (e.g. read back
   // from the by-subject entry) — does NOT hash again. Kept separate from
@@ -72,7 +75,7 @@ export function createSingleUseTokenStore(prefixes: {
     return `${prefixes.subjectPrefix}${subjectId}`;
   }
   function burnKey(token: string): string {
-    return `${prefixes.burnPrefix}${hashToken(token)}`;
+    return `${prefixes.burnPrefix}${hashSingleUseToken(token)}`;
   }
 
   // Stores the pair bidirectionally and sets TTL on both keys. Idempotent —
@@ -84,7 +87,7 @@ export function createSingleUseTokenStore(prefixes: {
   ): Promise<void> {
     await Promise.all([
       redis.set(tokenKey(args.token), args.subjectId, "EX", args.ttlSeconds),
-      redis.set(subjectKey(args.subjectId), hashToken(args.token), "EX", args.ttlSeconds),
+      redis.set(subjectKey(args.subjectId), hashSingleUseToken(args.token), "EX", args.ttlSeconds),
     ]);
   }
 
@@ -132,5 +135,22 @@ export function createSingleUseTokenStore(prefixes: {
     await redis.del(burnKey(token));
   }
 
-  return { store, getSubjectForToken, invalidateExistingBySubject, burn, deleteBoth, unburn };
+  // The by-subject entry's raw value — a token hash, not a token (see file
+  // header) — for a caller that needs to key a SIBLING Redis namespace off
+  // the same live token without recovering it (e.g. a resend that must
+  // carry a side-binding over to the fresh token before the old one is
+  // invalidated).
+  async function getTokenHashForSubject(redis: Redis, subjectId: string): Promise<string | null> {
+    return redis.get(subjectKey(subjectId));
+  }
+
+  return {
+    store,
+    getSubjectForToken,
+    invalidateExistingBySubject,
+    burn,
+    deleteBoth,
+    unburn,
+    getTokenHashForSubject,
+  };
 }