@cosmicdrift/kumiko-bundled-features 0.311.0 → 0.313.0

package/src/document-ingest-foundation/forget-extract-with-file-ref.ts

@@ -0,0 +1,84 @@
+// documentExtract is derived data — once its source fileRef is gone (soft
+// delete or forget), the extract has no reason to survive it. A restored
+// fileRef is re-ingested by feature.ts's request-ingest MSP
+// (fileRef.restored), so a fresh extract replaces the forgotten one.
+//
+// forget(), not deleteMany: documentExtract is an ES-managed implicit
+// projection, so forget() replays correctly on rebuild. This MSP itself has
+// no `table`, so rebuildMultiStreamProjection never targets it directly.
+//
+// Also reacts to documentExtract.created: providers write extracts
+// themselves (own executor call), racing this consumer's fileRef.deleted/
+// forgotten handling. Each handler re-checks current fileRef liveness at
+// processing time, so no extract survives regardless of write/delete order —
+// this covers providers that bypass write-document-extract.ts's helper too.
+
+import { createTenantDb, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { MultiStreamApplyFn } from "@cosmicdrift/kumiko-framework/engine";
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { documentExtractsTable } from "./entity";
+import { documentExtractExecutor } from "./executor";
+import { isFileRefLive } from "./file-ref-liveness";
+
+// WriteResult.error is always a plain WriteErrorInfo object, never a
+// KumikoError instance (JSON-serializable for the dispatcher's idempotency-key
+// storage) — compare on .code, not instanceof.
+function isNotFoundWriteError(error: WriteErrorInfo): boolean {
+  return error.code === "not_found";
+}
+
+async function forgetExtractsForFileRef(
+  event: Parameters<MultiStreamApplyFn>[0],
+  tenantDb: TenantDb,
+): Promise<void> {
+  const rows = await tenantDb.selectMany<{ id: string }>(documentExtractsTable, {
+    fileRefId: event.aggregateId,
+  });
+  const user = createSystemUser(event.tenantId);
+  for (const row of rows) {
+    const result = await documentExtractExecutor.forget({ id: row.id }, user, tenantDb);
+    if (result.isSuccess) continue;
+    // Idempotent: a concurrent/redelivered apply that already forgot this
+    // row is not an error — anything else (version conflict, ownership
+    // denial) must surface so the dispatcher retries/dead-letters instead of
+    // silently leaving the extract behind.
+    if (isNotFoundWriteError(result.error)) continue;
+    throw new Error(
+      `document-ingest-foundation: failed to forget documentExtract ${row.id} for fileRef ${event.aggregateId}: ${result.error.message}`,
+    );
+  }
+}
+
+const documentExtractCreatedPayloadSchema = z.object({ fileRefId: z.string().min(1) });
+
+export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (event, tx) => {
+  const parsed = documentExtractCreatedPayloadSchema.safeParse(event.payload);
+  // skip: malformed payload — don't poison the consumer
+  if (!parsed.success) return;
+  const tenantDb = createTenantDb(tx, event.tenantId);
+  // skip: fileRef still live — the extract is legitimate
+  if (await isFileRefLive(tenantDb, parsed.data.fileRefId)) return;
+  const user = createSystemUser(event.tenantId);
+  const result = await documentExtractExecutor.forget({ id: event.aggregateId }, user, tenantDb);
+  // skip: forgotten now, or already gone via a concurrent/redelivered apply
+  if (result.isSuccess || isNotFoundWriteError(result.error)) return;
+  throw new Error(
+    `document-ingest-foundation: failed to forget orphaned documentExtract ${event.aggregateId}: ${result.error.message}`,
+  );
+};
+
+export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (event, tx) => {
+  const tenantDb = createTenantDb(tx, event.tenantId);
+  // skip: fileRef is live again — request-ingest and this consumer poll via
+  // separate cursors, so a delete→restore round-trip can finish before this
+  // consumer sees fileRef.deleted; forgetting would drop the live file's extract.
+  if (await isFileRefLive(tenantDb, event.aggregateId)) return;
+  await forgetExtractsForFileRef(event, tenantDb);
+};
+
+export const forgetExtractOnFileRefForgottenHook: MultiStreamApplyFn = async (event, tx) => {
+  const tenantDb = createTenantDb(tx, event.tenantId);
+  await forgetExtractsForFileRef(event, tenantDb);
+};

package/src/document-ingest-foundation/index.ts

@@ -10,8 +10,25 @@ export {
   DOCUMENT_INGEST_AGGREGATE_TYPE,
   DOCUMENT_INGEST_REQUESTED_EVENT_QN,
   DOCUMENT_INGEST_REQUESTED_EVENT_SHORT,
+  DOCUMENT_INGEST_SKIPPED_EVENT_QN,
+  DOCUMENT_INGEST_SKIPPED_EVENT_SHORT,
   type DocumentIngestRequestedPayload,
+  type DocumentIngestSkippedPayload,
   documentIngestRequestedPayloadSchema,
+  documentIngestSkippedPayloadSchema,
 } from "./events";
 export { documentIngestFoundationFeature } from "./feature";
 export { readIngestPages, writeIngestPages } from "./pages";
+export {
+  type DocumentIngestProviderOptions,
+  documentIngestProviderOptionsSchema,
+  documentIngestProviderTrigger,
+  EXT_DOCUMENT_INGEST_PROVIDER,
+  listIngestibleMimeTypes,
+  type ResolvedDocumentIngestProvider,
+  resolveDocumentIngestProviders,
+} from "./providers";
+export {
+  type DocumentExtractWriteResult,
+  writeDocumentExtractForLiveFileRef,
+} from "./write-document-extract";

package/src/document-ingest-foundation/providers.ts

@@ -0,0 +1,78 @@
+// document-ingest-foundation — provider extension-point. One shared
+// documentIngest.requested QN fans out to every mounted provider's job,
+// partitioned by documentIngestProviderTrigger's where-filter.
+
+import type { FeatureDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { normalizeMimeType } from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+import { DOCUMENT_INGEST_REQUESTED_EVENT_QN } from "./events";
+
+export const EXT_DOCUMENT_INGEST_PROVIDER = "documentIngestProvider" as const;
+
+export const documentIngestProviderOptionsSchema = z.object({
+  mimeTypes: z.array(z.string().min(1)).min(1),
+  maxFileBytes: z.number().int().positive(),
+});
+export type DocumentIngestProviderOptions = z.infer<typeof documentIngestProviderOptionsSchema>;
+
+// r.useExtension options-shape, co-located since the framework never imports upward.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [EXT_DOCUMENT_INGEST_PROVIDER]: DocumentIngestProviderOptions;
+  }
+}
+
+export type ResolvedDocumentIngestProvider = {
+  readonly name: string;
+  readonly maxFileBytes: number;
+};
+
+type ExtensionUsages = FeatureDefinition["extensionUsages"];
+
+// Throws on an invalid options shape or two providers claiming the same
+// normalized mimeType — callers decide whether that's boot-fatal.
+export function resolveDocumentIngestProviders(
+  usages: ExtensionUsages,
+): ReadonlyMap<string, ResolvedDocumentIngestProvider> {
+  const byMime = new Map<string, ResolvedDocumentIngestProvider>();
+  for (const usage of usages) {
+    if (usage.extensionName !== EXT_DOCUMENT_INGEST_PROVIDER) continue;
+    const parsed = documentIngestProviderOptionsSchema.safeParse(usage.options);
+    if (!parsed.success) {
+      throw new Error(
+        `document-ingest-foundation: provider "${usage.entityName}" registered invalid options via ` +
+          `r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, "${usage.entityName}", ...) — ${parsed.error.message}`,
+      );
+    }
+    for (const mimeType of parsed.data.mimeTypes) {
+      const normalized = normalizeMimeType(mimeType);
+      const existing = byMime.get(normalized);
+      if (existing && existing.name !== usage.entityName) {
+        throw new Error(
+          `document-ingest-foundation: providers "${existing.name}" and "${usage.entityName}" both claim mimeType ` +
+            `"${normalized}" — each mimeType may have exactly one registered provider.`,
+        );
+      }
+      byMime.set(normalized, { name: usage.entityName, maxFileBytes: parsed.data.maxFileBytes });
+    }
+  }
+  return byMime;
+}
+
+export function listIngestibleMimeTypes(registry: Registry): readonly string[] {
+  const usages = registry.getExtensionUsages(EXT_DOCUMENT_INGEST_PROVIDER);
+  return [...resolveDocumentIngestProviders(usages).keys()].sort();
+}
+
+export type DocumentIngestProviderJobTrigger = {
+  readonly on: typeof DOCUMENT_INGEST_REQUESTED_EVENT_QN;
+  readonly where: { readonly provider: string };
+};
+
+// The trigger every provider's job must use — filters the shared
+// documentIngest.requested QN down to just this provider's requests.
+export function documentIngestProviderTrigger(
+  providerName: string,
+): DocumentIngestProviderJobTrigger {
+  return { on: DOCUMENT_INGEST_REQUESTED_EVENT_QN, where: { provider: providerName } };
+}

package/src/document-ingest-foundation/tenant-destroy-hook.ts

@@ -10,13 +10,9 @@
 // (kumiko-framework#1495). The `pages` ciphertext dies separately when the
 // pipeline's later `subject-keys` stage erases the tenant subject key.
 
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, type TenantDataDestroyHook } from "@cosmicdrift/kumiko-framework/engine";
-import { documentExtractEntity, documentExtractsTable } from "./entity";
-
-const executor = createEventStoreExecutor(documentExtractsTable, documentExtractEntity, {
-  entityName: "document-extract",
-});
+import { documentExtractsTable } from "./entity";
+import { documentExtractExecutor } from "./executor";
 
 export const documentExtractTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
   const rows = await ctx.db.selectMany<{ id: string }>(documentExtractsTable, {
@@ -24,7 +20,7 @@ export const documentExtractTenantDestroyHook: TenantDataDestroyHook = async (ct
   });
   const user = createSystemUser(ctx.tenantId);
   for (const row of rows) {
-    const result = await executor.forget({ id: row.id }, user, ctx.db);
+    const result = await documentExtractExecutor.forget({ id: row.id }, user, ctx.db);
     // Executor writes return {isSuccess:false} instead of throwing — a
     // discarded result would report this destroy stage "succeeded" while the
     // extracted document text survives. Throw so the pipeline's retry/abandon

package/src/document-ingest-foundation/write-document-extract.ts

@@ -0,0 +1,48 @@
+// Providers write documentExtract rows themselves (their own executor
+// call on ctx.db) rather than through a request/response API, so this is
+// the one place that write must go through to stay race-safe against a
+// concurrent fileRef delete/forget — see forget-extract-with-file-ref.ts.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { DocumentExtractMeta, IngestPage } from "./entity";
+import { documentExtractExecutor } from "./executor";
+import { isFileRefLive } from "./file-ref-liveness";
+import { writeIngestPages } from "./pages";
+
+export type DocumentExtractWriteResult =
+  | { readonly kind: "written"; readonly documentExtractId: string }
+  | { readonly kind: "skipped"; readonly reason: "file_ref_deleted" };
+
+export async function writeDocumentExtractForLiveFileRef(input: {
+  readonly tenantDb: TenantDb;
+  readonly actor: SessionUser;
+  readonly fileRefId: string;
+  readonly storageKey: string;
+  readonly pages: readonly IngestPage[];
+  readonly meta: DocumentExtractMeta & Readonly<Record<string, unknown>>;
+}): Promise<DocumentExtractWriteResult> {
+  // Early-skip optimization only — a fileRef deleted/forgotten right after
+  // this check still gets caught by forget-extract-with-file-ref.ts's
+  // documentExtract.created handler, which is the actual race-safety guarantee.
+  if (!(await isFileRefLive(input.tenantDb, input.fileRefId))) {
+    return { kind: "skipped", reason: "file_ref_deleted" };
+  }
+  const result = await documentExtractExecutor.create(
+    {
+      fileRefId: input.fileRefId,
+      storageKey: input.storageKey,
+      pages: writeIngestPages(input.pages),
+      meta: input.meta,
+    },
+    input.actor,
+    input.tenantDb,
+  );
+  if (!result.isSuccess) {
+    throw new InternalError({
+      message: `document-ingest-foundation: failed to write documentExtract for fileRef ${input.fileRefId}: ${result.error.message}`,
+    });
+  }
+  return { kind: "written", documentExtractId: String(result.data.id) };
+}

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,
+  };
 }

package/src/subscription-stripe/__tests__/plugin-methods.test.ts

@@ -143,9 +143,53 @@ describe("createStripeCheckoutSession", () => {
       payment_intent_data: {
         metadata: { tenantId: "tenant-003" },
       },
+      // Default-on: without the runtime option, mode:"payment" gets a
+      // Stripe invoice.
+      invoice_creation: { enabled: true },
     });
   });
 
+  test("mode='payment' + paymentInvoiceCreation:false: invoice_creation.enabled is false", async () => {
+    const stripe = buildStripe();
+    const createMock = spyOn(stripe.checkout.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ url: "https://checkout.stripe.com/c/pay/topup" } as any);
+
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe), {
+      paymentInvoiceCreation: false,
+    });
+    await checkout(stubCtx, {
+      priceId: "price_credits_topup",
+      tenantId: "tenant-003",
+      successUrl: "https://example.com/success",
+      cancelUrl: "https://example.com/cancel",
+      mode: "payment",
+    });
+
+    expect(createMock).toHaveBeenCalledWith(
+      expect.objectContaining({ invoice_creation: { enabled: false } }),
+    );
+  });
+
+  test("mode='subscription': NIE invoice_creation — Stripe rejects es außerhalb payment-mode", async () => {
+    const stripe = buildStripe();
+    const createMock = spyOn(stripe.checkout.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ url: "https://x" } as any);
+
+    const checkout = createStripeCheckoutSession(ctxRuntime(stripe));
+    await checkout(stubCtx, {
+      priceId: "price_x",
+      tenantId: "tenant-005",
+      successUrl: "https://x/s",
+      cancelUrl: "https://x/c",
+      mode: "subscription",
+    });
+
+    const callArgs = createMock.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArgs).not.toHaveProperty("invoice_creation");
+  });
+
   test("mode omitted defaults to 'subscription' (Regression-Pin für bestehende Aufrufer)", async () => {
     const stripe = buildStripe();
     const createMock = spyOn(stripe.checkout.sessions, "create")