@cosmicdrift/kumiko-samples 0.367.0 → 0.369.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.367.0",
+  "version": "0.369.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.367.0",
+  "version": "0.369.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -73,6 +73,7 @@
     "./mail-transport-inmemory": "./src/mail-transport-inmemory/index.ts",
     "./file-foundation": "./src/file-foundation/index.ts",
     "./file-provider-s3": "./src/file-provider-s3/index.ts",
+    "./file-provider-s3/lib": "./src/file-provider-s3/lib/index.ts",
     "./document-ingest-foundation": "./src/document-ingest-foundation/index.ts",
     "./file-provider-s3-env": "./src/file-provider-s3-env/index.ts",
     "./file-provider-inmemory": "./src/file-provider-inmemory/index.ts",
@@ -397,6 +398,10 @@
         "types": "./dist/file-provider-s3/index.d.ts",
         "default": "./dist/file-provider-s3/index.js"
       },
+      "./file-provider-s3/lib": {
+        "types": "./dist/file-provider-s3/lib/index.d.ts",
+        "default": "./dist/file-provider-s3/lib/index.js"
+      },
       "./document-ingest-foundation": {
         "types": "./dist/document-ingest-foundation/index.d.ts",
         "default": "./dist/document-ingest-foundation/index.js"
@@ -707,6 +712,15 @@
     "@cosmicdrift/kumiko-locale-es": "workspace:*",
     "@cosmicdrift/kumiko-renderer-mail-html": "workspace:*",
     "jsqr": "^1.4.0",
-    "unpdf": "^1.8.1"
+    "unpdf": "^1.8.1",
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  },
+  "peerDependencies": {
+    "@cosmicdrift/kumiko-testing": ">=0.366.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cosmicdrift/kumiko-testing": {
+      "optional": true
+    }
   }
 }

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -3,7 +3,7 @@
 // can only read events in their own tenant; a SystemAdmin can pass scope
 // "system" to read app-instance system events (e.g. app.started).
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -12,7 +12,7 @@
 // Event payloads hold PII as subject-KMS ciphertext; it is replaced by
 // REDACTED_PII_PLACEHOLDER before returning, since the API leak guard refuses ciphertext.
 
-import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -1,13 +1,13 @@
-import {
-  aggregateWhere,
-  runnerCanBeginTransaction,
-  selectMany,
-} from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   COMPLIANCE_PROFILES,
   subtractRetentionSpec,
 } from "@cosmicdrift/kumiko-framework/compliance";
 import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  aggregateWhere,
+  runnerCanBeginTransaction,
+  selectMany,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigResolver,
   parseTenantId,

package/packages/bundled-features/src/auth-email-password/bootstrap.ts

@@ -10,8 +10,8 @@ import {
   makeDispatchWriteAs,
   type RoleDispatchArgs,
 } from "@cosmicdrift/kumiko-framework/api";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   createSystemUser,

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -21,8 +21,11 @@
 // both already exist. The magic is the combined login+accept operation in
 // one round trip.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  fetchOne,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   buildSessionRoles,
   createSystemUser,
@@ -235,7 +238,11 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         if (!globalGrant.isSuccess) return globalGrant;
 
         // Invitation → accepted: TenantDb for the invitation's tenant.
-        const invitationTdb = createTenantDb(dbConn, invitationTenantId, "system");
+        const invitationTdb = createTenantDb({
+          db: dbConn,
+          tenantId: invitationTenantId,
+          mode: "system",
+        });
         const updateResult = await invitationExecutor.update(
           {
             id: invitationId,

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept.write.ts

@@ -15,8 +15,11 @@
 // Session"-Flow. Branch 2 (anon + existing email) und Branch 3 (anon +
 // new email) kommen als separate Handler.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  fetchOne,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   defineWriteHandler,
@@ -170,7 +173,11 @@ export function createInviteAcceptHandler() {
         // Tenant-scoping: ctx.db ist auf event.user.tenantId gescopt
         // (= NICHT der invitation-tenant). Eigene TenantDb für den
         // invitation-tenant bauen damit der executor die row findet.
-        const invitationTdb = createTenantDb(dbConn, invitationTenantId, "system");
+        const invitationTdb = createTenantDb({
+          db: dbConn,
+          tenantId: invitationTenantId,
+          mode: "system",
+        });
         const updateResult = await invitationExecutor.update(
           {
             id: invitationId,

package/packages/bundled-features/src/auth-email-password/handlers/invite-info.query.ts

@@ -5,7 +5,7 @@
 // the token store — the token is not burned and stays usable for the
 // actual accept call.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/packages/bundled-features/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -17,11 +17,11 @@
 //      e. Invitation → accepted, Token gelöscht
 //   5. Response: SessionUser + tenantId für Auto-Login
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
   createTenantDb,
   type DbConnection,
+  fetchOne,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildSessionRoles,
@@ -185,7 +185,11 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
         });
 
         // Invitation → accepted: TenantDb für invitation-tenant
-        const invitationTdb = createTenantDb(dbConn, invitationTenantId, "system");
+        const invitationTdb = createTenantDb({
+          db: dbConn,
+          tenantId: invitationTenantId,
+          mode: "system",
+        });
         const updateResult = await invitationExecutor.update(
           {
             id: invitationId,

package/packages/bundled-features/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -19,8 +19,8 @@
 // bei !committed wird der burn released damit ein legitimer Retry
 // nicht durch einen stale Marker geblockt wird (wie reset/verify).
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineWriteHandler,
   type HandlerContext,

package/packages/bundled-features/src/auth-email-password/seeding.ts

@@ -12,7 +12,6 @@
 // Damit Sample-Server und Tests keine drei sub-paths zusammensammeln
 // müssen.
 
-import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredBlindIndexKey,
   configuredPiiSubjectKms,
@@ -20,10 +19,11 @@ import {
   type LocalKeyKmsAdapter,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { hashPassword } from "../shared/index.js";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { type SeedTenantHooks, seedTenant, seedTenantMembership } from "../tenant/seeding.js";

package/packages/bundled-features/src/auth-foundation/feature.ts

@@ -44,45 +44,54 @@ export {
 
 const FEATURE_NAME = "auth-foundation";
 
-export const authFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Declares auth-middleware extension points: `tokenVerifier` (Bearer), `sessionStore` (revocable JWT sid), optional `tenantResolver` + `tenantExistence` for anonymous multi-tenant. Provider-features register via r.useExtension; mount auth-foundation with the matching provider features.",
-  );
-  r.uiHints({
-    displayLabel: "Auth Provider Foundation",
-    category: "identity",
-    recommended: false,
-  });
+export function createAuthFoundationFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Declares auth-middleware extension points: `tokenVerifier` (Bearer), `sessionStore` (revocable JWT sid), optional `tenantResolver` + `tenantExistence` for anonymous multi-tenant. Provider-features register via r.useExtension; mount auth-foundation with the matching provider features.",
+      );
+      r.uiHints({
+        displayLabel: "Auth Provider Foundation",
+        category: "identity",
+        recommended: false,
+      });
 
-  r.extendsRegistrar(EXT_TOKEN_VERIFIER, {
-    onRegister: () => {
-      // No side-effects at register-time — registry stores the usage,
-      // resolveTokenVerifier looks it up at request-time.
-    },
-  });
-  r.bootCheck(({ features }) => validateTokenVerifierMultiplicity(features));
+      r.extendsRegistrar(EXT_TOKEN_VERIFIER, {
+        onRegister: () => {
+          // No side-effects at register-time — registry stores the usage,
+          // resolveTokenVerifier looks it up at request-time.
+        },
+      });
+      r.bootCheck(({ features }) => validateTokenVerifierMultiplicity(features));
 
-  r.extendsRegistrar(EXT_SESSION_STORE, {
-    onRegister: () => {
-      // No side-effects at register-time — resolveSessionStore at boot/request.
-    },
-  });
-  r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
+      r.extendsRegistrar(EXT_SESSION_STORE, {
+        onRegister: () => {
+          // No side-effects at register-time — resolveSessionStore at boot/request.
+        },
+      });
+      r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
 
-  r.extendsRegistrar(EXT_TENANT_RESOLVER, {
-    onRegister: () => {
-      // Optional — zero providers is fine (single-tenant / header-cookie).
-    },
-  });
-  r.bootCheck(({ features }) => validateTenantResolverMultiplicity(features));
+      r.extendsRegistrar(EXT_TENANT_RESOLVER, {
+        onRegister: () => {
+          // Optional — zero providers is fine (single-tenant / header-cookie).
+        },
+      });
+      r.bootCheck(({ features }) => validateTenantResolverMultiplicity(features));
 
-  r.extendsRegistrar(EXT_TENANT_EXISTENCE, {
-    onRegister: () => {
-      // Optional — zero providers skips the existence check.
+      r.extendsRegistrar(EXT_TENANT_EXISTENCE, {
+        onRegister: () => {
+          // Optional — zero providers skips the existence check.
+        },
+      });
+      r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
     },
-  });
-  r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
-});
+    { dedupeOptions: {} },
+  );
+}
+
+/** @deprecated Use createAuthFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const authFoundationFeature = createAuthFoundationFeature();
 
 /**
  * Tries every registered tokenVerifier provider's shape against `rawToken`

package/packages/bundled-features/src/auth-foundation/index.ts

@@ -2,6 +2,7 @@
 
 export {
   authFoundationFeature,
+  createAuthFoundationFeature,
   type ResolvedTenantResolver,
   resolveSessionStore,
   resolveTenantExistence,

package/packages/bundled-features/src/auth-mfa/db/queries.ts

@@ -1,5 +1,8 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  fetchOne,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import { userMfaEntity, userMfaTable } from "../schema/user-mfa.js";

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -134,7 +134,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
 
       // "system" mode: no session exists yet, tenantId comes from the
       // verified token, mirroring enable-start-preauth.write.ts.
-      const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
+      const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();

package/packages/bundled-features/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -62,7 +62,7 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       // "system" mode: the guest dispatch identity's own tenantId is
       // meaningless here — the preauthSetupToken is the source of truth
       // for which tenant's row to read, mirroring verify.write.ts.
-      const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
+      const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();

package/packages/bundled-features/src/auth-mfa/handlers/reencrypt.job.ts

@@ -23,7 +23,6 @@
 // an old-KEK wrap would happen if rotation only touched the read-side
 // projection instead of appending a real `.updated` event).
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   collectPiiSubjectFields,
   configuredPiiSubjectKms,
@@ -34,6 +33,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbConnection,
+  selectMany,
   type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -109,7 +109,7 @@ export async function mfaReencryptJob(
   function tdbFor(tenantId: TenantId): TenantDb {
     let existing = tdbCache.get(tenantId);
     if (!existing) {
-      existing = createTenantDb(db, tenantId, "system");
+      existing = createTenantDb({ db, tenantId, mode: "system" });
       tdbCache.set(tenantId, existing);
     }
     return existing;

package/packages/bundled-features/src/auth-mfa/handlers/status.query.ts

@@ -1,4 +1,4 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { userMfaTable } from "../schema/user-mfa.js";

package/packages/bundled-features/src/auth-mfa/handlers/verify.write.ts

@@ -98,7 +98,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // "system" mode: this handler runs with a guest identity whose own
       // tenantId is meaningless here — the challenge token is the source
       // of truth for which tenant's row to read.
-      const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
+      const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const row = await findUserMfaRow(scopedDb, scopedUser);
       // MFA got disabled between login and verify (race, or a stale

package/packages/bundled-features/src/auth-mfa/mfa-code-verifier.ts

@@ -29,7 +29,7 @@ export function createMfaCodeVerifier(): MfaCodeVerifier {
       reason:
         "reads the MFA enrollment of the user being re-authenticated on the caller's handler context; the calling handler declares its own escapeHatch",
     });
-    const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
+    const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
     const row = await findUserMfaRow(scopedDb, { id: userId, tenantId, roles: [] });
     if (!row) return { enrolled: false, ok: false };
     // Fail closed without ctx.redis, matching disable.write.ts/verify.write.ts —

package/packages/bundled-features/src/auth-mfa/mfa-status-checker.ts

@@ -47,7 +47,7 @@ export function createMfaStatusChecker(opts: {
       reason:
         "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant, on the caller's handler context; the calling handler declares its own escapeHatch",
     });
-    const scopedDb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
+    const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
     const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
     const row = await findUserMfaRow(scopedDb, scopedUser);
 

package/packages/bundled-features/src/auth-mfa-user-data/index.ts

@@ -8,14 +8,23 @@
 import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { userMfaDeleteHook, userMfaExportHook } from "./hooks.js";
 
-export const authMfaUserDataFeature = defineFeature("auth-mfa-user-data", (r) => {
-  r.describe(
-    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `auth-mfa` feature's `user-mfa` entity. Mounts the EXT_USER_DATA export + delete hooks so 2FA enrollment status is included in the user-data export bundle and a user's TOTP secret + recovery codes are hard-deleted (via executor.forget, rebuild-safe) on a data-subject erasure request. Kept separate from `auth-mfa` so consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `auth-mfa`.",
+export function createAuthMfaUserDataFeature() {
+  return defineFeature(
+    "auth-mfa-user-data",
+    (r) => {
+      r.describe(
+        "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `auth-mfa` feature's `user-mfa` entity. Mounts the EXT_USER_DATA export + delete hooks so 2FA enrollment status is included in the user-data export bundle and a user's TOTP secret + recovery codes are hard-deleted (via executor.forget, rebuild-safe) on a data-subject erasure request. Kept separate from `auth-mfa` so consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `auth-mfa`.",
+      );
+      r.requires({ features: ["user-data-rights"] });
+      r.optionalRequires("auth-mfa");
+      r.useExtension(EXT_USER_DATA, "user-mfa", {
+        export: userMfaExportHook,
+        delete: userMfaDeleteHook,
+      });
+    },
+    { dedupeOptions: {} },
   );
-  r.requires({ features: ["user-data-rights"] });
-  r.optionalRequires("auth-mfa");
-  r.useExtension(EXT_USER_DATA, "user-mfa", {
-    export: userMfaExportHook,
-    delete: userMfaDeleteHook,
-  });
-});
+}
+
+/** @deprecated Use createAuthMfaUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const authMfaUserDataFeature = createAuthMfaUserDataFeature();

package/packages/bundled-features/src/billing-foundation/billing-info-query.ts

@@ -5,7 +5,7 @@
 // off the app's extraContext.
 //
 // Deliberately does NOT call defineQueryHandler itself: apps use different
-// wrappers around it (publicstatus's `@app/define`, which adds
+// wrappers around it (publicstatus's own wrapper, which adds
 // `agent: { expose: false }`; show-pony's plain framework
 // `defineQueryHandler`). Calling defineQueryHandler here would bypass
 // whatever an app's own wrapper does. Instead this factory returns just the