@cosmicdrift/kumiko-bundled-features 0.389.0 → 0.390.0

package/dist/auth-email-password/handlers/verify-email.write.js

@@ -23,7 +23,7 @@ export function createVerifyEmailHandler(opts) {
         escapeHatch: {
             grants: ["systemIdentity"],
             reason: "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +
-                "target user via ctx.writeAs(SYSTEM, user:update) to set emailVerified.",
+                "target user via ctx.dispatch.writeAs(SYSTEM, user:update) to set emailVerified.",
         },
         agent: { expose: false },
         handler: async (event, ctx) => {
@@ -37,7 +37,7 @@ export function createVerifyEmailHandler(opts) {
                 return invalidVerificationToken();
             return runConfirmTokenFlow(ctx, verify.userId, verify.expiresAtMs, {
                 purpose: "verify",
-                redisRequiredMessage: "email-verification requires ctx.redis to enforce token single-use",
+                redisRequiredMessage: "email-verification requires ctx.services.redis to enforce token single-use",
                 invalidToken: invalidVerificationToken,
                 buildChanges: async () => ({ emailVerified: true }),
                 successData: { kind: "verified" },

package/dist/auth-email-password/seeding.d.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type SeedTenantHooks } from "../tenant/seeding.ts";
 export { seedTenant, seedTenantMembership } from "../tenant/seeding.ts";
 export { seedUser } from "../user/seeding.ts";

package/dist/auth-email-password/seeding.js

@@ -13,9 +13,9 @@
 // sub-paths themselves.
 import { configuredBlindIndexKey, configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, SYSTEM_TENANT_ID, } 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/seeding";
 import { hashPassword } from "../shared/index.js";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { seedTenant, seedTenantMembership } from "../tenant/seeding.js";
@@ -129,9 +129,9 @@ hooks) {
  * persistent-DB mode succeeds. Returns the userId.
  */
 export async function seedAdmin(db, options) {
-    const by = options.by ?? TestUsers.systemAdmin;
+    const byOption = options.by === undefined ? {} : { by: options.by };
     for (const m of options.memberships) {
-        await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
+        await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, ...byOption });
     }
     const { id: userId } = await seedUserWithPassword(db, {
         email: options.email,
@@ -139,14 +139,14 @@ export async function seedAdmin(db, options) {
         displayName: options.displayName,
         ...(options.globalRoles !== undefined && { roles: options.globalRoles }),
         ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
-        by,
+        ...byOption,
     });
     for (const m of options.memberships) {
         await seedTenantMembership(db, {
             userId,
             tenantId: m.tenantId,
             roles: m.roles,
-            by,
+            ...byOption,
         });
     }
     return { id: userId };
@@ -239,7 +239,8 @@ export async function seedAdminGuarded(db, options) {
     const existingId = await findExistingUserIdForEmail(db, kms, options.email);
     if (existingId === undefined)
         return seedAdmin(db, options);
-    const by = options.by ?? TestUsers.systemAdmin;
+    const byOption = options.by === undefined ? {} : { by: options.by };
+    const by = options.by ?? createSystemUser(SYSTEM_TENANT_ID);
     const existingRow = await fetchOne(db, userTable, { id: existingId });
     if (existingRow) {
         // Re-write the email so email_bidx is recomputed; without it the account
@@ -251,12 +252,12 @@ export async function seedAdminGuarded(db, options) {
         }
     }
     for (const m of options.memberships) {
-        await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
+        await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, ...byOption });
         await seedTenantMembership(db, {
             userId: existingId,
             tenantId: m.tenantId,
             roles: m.roles,
-            by,
+            ...byOption,
         });
     }
     return { id: existingId };

package/dist/auth-foundation/feature.js

@@ -10,6 +10,7 @@
 // Middleware / runProdApp resolve providers from the registry at boot
 // (tokenVerifier/sessionStore) or request-time (tokenVerifier shape match).
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { systemScopedRunner } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import { validateSessionStoreMultiplicity, validateTenantExistenceMultiplicity, validateTenantResolverMultiplicity, validateTokenVerifierMultiplicity, } from "./boot-checks.js";
 import { EXT_SESSION_STORE, EXT_TENANT_EXISTENCE, EXT_TENANT_RESOLVER, EXT_TOKEN_VERIFIER, isAuthProviderPlugin, isSessionStoreProvider, isTenantExistenceProvider, isTenantResolverProvider, tokenShapeMatches, } from "./types.js";
 export { EXT_SESSION_STORE, EXT_TENANT_EXISTENCE, EXT_TENANT_RESOLVER, EXT_TOKEN_VERIFIER, } from "./types.js";
@@ -49,6 +50,13 @@ export function createAuthFoundationFeature() {
         r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
     }, { dedupeOptions: {} });
 }
+// Providers run before any tenant or session exists (token verify, host to tenant), so their reads are cross-tenant by nature.
+function systemScopedDeps(deps) {
+    return {
+        ...deps,
+        db: systemScopedRunner(deps.db, "auth lookups run before a tenant is established"),
+    };
+}
 /**
  * Tries every registered tokenVerifier provider's shape against `rawToken`
  * in registration order and calls the first match's verifier. Returns null
@@ -62,7 +70,7 @@ export async function resolveTokenVerifier(deps, rawToken) {
             continue;
         if (!tokenShapeMatches(usage.options.shape, rawToken))
             continue;
-        const verify = await usage.options.build(deps);
+        const verify = await usage.options.build(systemScopedDeps(deps));
         return verify(rawToken);
     }
     return null;
@@ -78,7 +86,7 @@ export async function resolveSessionStore(deps) {
     if (!usage || !isSessionStoreProvider(usage.options)) {
         throw new Error("[auth-foundation] no sessionStore provider registered — did the boot validator run?");
     }
-    return usage.options.build(deps);
+    return usage.options.build(systemScopedDeps(deps));
 }
 /** Optional tenantResolver — null when no provider registered. */
 export async function resolveTenantResolver(deps) {
@@ -88,7 +96,7 @@ export async function resolveTenantResolver(deps) {
     if (!isTenantResolverProvider(usage.options)) {
         throw new Error("[auth-foundation] tenantResolver provider registered without a valid TenantResolverProvider");
     }
-    const resolve = await usage.options.build(deps);
+    const resolve = await usage.options.build(systemScopedDeps(deps));
     return { resolve, trust: usage.options.trust };
 }
 /** Optional tenantExistence — null when no provider registered. */
@@ -99,5 +107,5 @@ export async function resolveTenantExistence(deps) {
     if (!isTenantExistenceProvider(usage.options)) {
         throw new Error("[auth-foundation] tenantExistence provider registered without a valid TenantExistenceProvider");
     }
-    return usage.options.build(deps);
+    return usage.options.build(systemScopedDeps(deps));
 }

package/dist/auth-mfa/handlers/disable.write.js

@@ -30,18 +30,18 @@ export function createDisableHandler(opts) {
             if (!row)
                 return mfaNotEnabled();
             // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
-            // without ctx.redis, verifyMfaFactor's TOTP-replay burn is skipped, and
+            // without ctx.services.redis, verifyMfaFactor's TOTP-replay burn is skipped, and
             // a code observed once (phishing proxy/shoulder-surfing) could be
             // replayed within the ±1-step window to disable MFA outright.
-            // "no ctx.redis means no one gets through MFA login" doesn't cover
+            // "no ctx.services.redis means no one gets through MFA login" doesn't cover
             // this route — it's session-authed, and JWTs issued before Redis was
             // unwired stay valid until they expire.
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "disable (mfa) requires ctx.redis for TOTP replay protection",
+                    message: "disable (mfa) requires ctx.services.redis for TOTP replay protection",
                 }));
             }
-            const replay = { redis: ctx.redis, userId: event.user.id };
+            const replay = { redis: ctx.services.redis, userId: event.user.id };
             const verify = await verifyMfaFactor(row, event.payload.code, replay);
             if (!verify.ok)
                 return invalidTotpCode();

package/dist/auth-mfa/handlers/enable-confirm-preauth.write.js

@@ -37,8 +37,8 @@ export function createEnableConfirmPreauthHandler(opts) {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         escapeHatch: {
             grants: ["systemIdentity", "unsafeRaw"],
-            reason: "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.queryAs(SYSTEM, " +
-                "user:findForAuth) and membership via ctx.resolveActiveMembership for the setup token's user. " +
+            reason: "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.dispatch.queryAs(SYSTEM, " +
+                "user:findForAuth) and membership via ctx.auth.resolveActiveMembership for the setup token's user. " +
                 "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
                 "guest dispatch tenant.",
         },
@@ -60,19 +60,19 @@ export function createEnableConfirmPreauthHandler(opts) {
             // endpoint has NO gate before it (access: { roles: ["anonymous"] }, no JWT,
             // no prior challenge-token from a successful login) — its only secret
             // is a 6-digit TOTP code. Silently skipping the brute-force cap and
-            // single-use burn when ctx.redis is absent would let the setup token
+            // single-use burn when ctx.services.redis is absent would let the setup token
             // be guessed against unboundedly until its TTL expires. The route's
             // IP rate limiter is not a substitute: it's IP-scoped and resets on
             // every success.
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "enable-confirm-preauth requires ctx.redis for the brute-force cap and single-use burn",
+                    message: "enable-confirm-preauth requires ctx.services.redis for the brute-force cap and single-use burn",
                 }));
             }
             // Same guessing surface as /auth/mfa/verify (a short TOTP code) and
             // the same per-userId cap — deliberately shared counter, see
             // mfa-verify-attempts.ts.
-            const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+            const state = await getMfaVerifyLockoutState(ctx.services.redis, userId);
             if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
                 const now = Date.now();
                 if (state.lockedUntil > now) {
@@ -82,17 +82,22 @@ export function createEnableConfirmPreauthHandler(opts) {
             }
             const secret = base32Decode(verify.payload.totpSecretBase32);
             if (verifyTotp(secret, event.payload.code) === false) {
-                await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+                await recordFailedMfaVerifyAttempt(ctx.services.redis, userId, maxAttempts, lockoutMinutes);
                 return invalidTotpCode();
             }
             // Burn the setup token on the first successful confirm — same
             // single-use guarantee as enable-confirm.write.ts.
-            const burnResult = await burnToken(ctx.redis, "mfa-setup", userId, verify.expiresAtMs);
+            const burnResult = await burnToken(ctx.services.redis, "mfa-setup", userId, verify.expiresAtMs);
             if (burnResult === "already-used")
                 return invalidSetupToken();
             // "system" mode: no session exists yet, tenantId comes from the
             // verified token, mirroring enable-start-preauth.write.ts.
-            const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+            const scopedDb = createTenantDb({
+                db: ctx.db.unsafeRaw(),
+                tenantId,
+                mode: "system",
+                reason: "pre-auth MFA setup has no session, the tenant comes from the verified setup token",
+            });
             const scopedUser = { id: userId, tenantId, roles: ["User"] };
             const existing = await findUserMfaRow(scopedDb, scopedUser);
             if (existing)
@@ -112,7 +117,7 @@ export function createEnableConfirmPreauthHandler(opts) {
             // existing userId-unique-constraint backstop between the
             // `existing` check above and executor.create() below.
             const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
-            const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+            const userRow = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
                 id: userId,
             })); // @cast-boundary engine-payload
             if (!userRow)
@@ -123,7 +128,7 @@ export function createEnableConfirmPreauthHandler(opts) {
                 return invalidSetupToken();
             }
             const globalRoles = parseRoles(userRow?.roles ?? null);
-            const active = await ctx.resolveActiveMembership(userId, tenantId);
+            const active = await ctx.auth.resolveActiveMembership(userId, tenantId);
             if (active.kind === "rejected")
                 return invalidSetupToken();
             const result = await executor.create({
@@ -135,8 +140,8 @@ export function createEnableConfirmPreauthHandler(opts) {
             }, scopedUser, scopedDb);
             if (!result.isSuccess)
                 return result;
-            // ctx.redis is guaranteed by the fail-closed check above.
-            await clearMfaVerifyAttempts(ctx.redis, userId);
+            // ctx.services.redis is guaranteed by the fail-closed check above.
+            await clearMfaVerifyAttempts(ctx.services.redis, userId);
             // Re-derive the full session the way verify.write.ts does — the
             // setupToken only proves "password + new TOTP secret", not roles;
             // roles come from the membership lookup above, same as every other
@@ -157,7 +162,7 @@ export function createEnableConfirmPreauthHandler(opts) {
                 ...sessionTimezoneField(userRow?.timezone),
                 ...sessionLocaleField(userRow?.locale),
             };
-            const claims = await ctx.resolveAuthClaims(baseSession);
+            const claims = await ctx.auth.resolveClaims(baseSession);
             const session = Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
             // Last step before returning success: every gate above (status,
             // membership, entity-write) has passed, so this is the point of no

package/dist/auth-mfa/handlers/enable-confirm.write.js

@@ -45,9 +45,9 @@ export function createEnableConfirmHandler(opts) {
             // second seeing invalidSetupToken(). Checked before the TOTP verify
             // for the same reason the other two handlers check it early: fail
             // closed before doing any of the guarded work, not partway through.
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "enable-confirm requires ctx.redis for the single-use setup-token burn",
+                    message: "enable-confirm requires ctx.services.redis for the single-use setup-token burn",
                 }));
             }
             const secret = base32Decode(verify.payload.totpSecretBase32);
@@ -65,7 +65,7 @@ export function createEnableConfirmHandler(opts) {
             // concurrent mfa_already_enabled() write) is meant to leave the burn
             // standing. Add unburnToken here if create-failure retries turn out
             // to matter.
-            const burnResult = await burnToken(ctx.redis, "mfa-setup", event.user.id, verify.expiresAtMs);
+            const burnResult = await burnToken(ctx.services.redis, "mfa-setup", event.user.id, verify.expiresAtMs);
             if (burnResult === "already-used")
                 return invalidSetupToken();
             const existing = await findUserMfaRow(ctx.db, event.user);

package/dist/auth-mfa/handlers/enable-start-preauth.write.js

@@ -44,7 +44,12 @@ export function createEnableStartPreauthHandler(opts) {
             // "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({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+            const scopedDb = createTenantDb({
+                db: ctx.db.unsafeRaw(),
+                tenantId,
+                mode: "system",
+                reason: "pre-auth MFA setup has no session, the tenant comes from the verified setup token",
+            });
             const scopedUser = { id: userId, tenantId, roles: ["User"] };
             const existing = await findUserMfaRow(scopedDb, scopedUser);
             if (existing)

package/dist/auth-mfa/handlers/enable-start.write.js

@@ -53,7 +53,7 @@ export function createEnableStartHandler(opts) {
             if (!accountLabel) {
                 // The declarative secretMint screen has no client component left to
                 // read the session email off — derive the otpauth label server-side.
-                accountLabel = readableAccountLabel(await ctx.queryAs(event.user, UserQueries.me, {}));
+                accountLabel = readableAccountLabel(await ctx.dispatch.queryAs(event.user, UserQueries.me, {}));
             }
             const secret = generateTotpSecret();
             const recoveryCodes = generateRecoveryCodes();

package/dist/auth-mfa/handlers/reencrypt.job.js

@@ -47,12 +47,12 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
     // hoisted function declarations below capture this — pin the narrowed
     // type explicitly so TS keeps it inside the closures.
     const cipher = maybeCipher;
-    if (!ctx.masterKeyProvider) {
+    if (!ctx.services.masterKeyProvider) {
         throw new InternalError({
-            message: "[auth-mfa:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+            message: "[auth-mfa:reencrypt] ctx.services.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
         });
     }
-    const provider = ctx.masterKeyProvider;
+    const provider = ctx.services.masterKeyProvider;
     // Undefined = per-subject crypto-shredding isn't configured for this app —
     // both fields are then plain envelope strings, no PII layer to peel.
     const piiKms = configuredPiiSubjectKms();
@@ -65,7 +65,12 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
     function tdbFor(tenantId) {
         let existing = tdbCache.get(tenantId);
         if (!existing) {
-            existing = createTenantDb({ db, tenantId, mode: "system" });
+            existing = createTenantDb({
+                db,
+                tenantId,
+                mode: "system",
+                reason: "MFA key re-encryption job rewrites enrollments of every tenant",
+            });
             tdbCache.set(tenantId, existing);
         }
         return existing;
@@ -101,7 +106,7 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         const totpClass = classifyStoredEnvelope(envelopeValues.totpSecret, targetVersion);
         const recoveryClass = classifyStoredEnvelope(envelopeValues.recoveryCodes, targetVersion);
         if (totpClass === "unrecognized" || recoveryClass === "unrecognized") {
-            ctx.log?.warn?.(`[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`);
+            ctx.obs.log?.warn?.(`[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`);
             return "failed";
         }
         if (totpClass === "current" && recoveryClass === "current") {
@@ -128,7 +133,7 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         if (!result.isSuccess) {
             if (result.error.code === "version_conflict")
                 return "skipped";
-            ctx.log?.warn?.(`[auth-mfa:reencrypt] executor rejected row ${row.id}`, {
+            ctx.obs.log?.warn?.(`[auth-mfa:reencrypt] executor rejected row ${row.id}`, {
                 code: result.error.code,
             });
             return "failed";
@@ -140,9 +145,9 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         migrateRow,
         maxFailures,
         deadlineAt: deadline,
-        signal: ctx.signal,
+        signal: ctx.lifecycle.signal,
         onRowError: (row, err) => {
-            ctx.log?.warn?.(`[auth-mfa:reencrypt] failed to re-encrypt row ${row.id}`, { err });
+            ctx.obs.log?.warn?.(`[auth-mfa:reencrypt] failed to re-encrypt row ${row.id}`, { err });
         },
     });
     const result = {
@@ -152,5 +157,5 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         batchesProcessed: outcome.batchesProcessed,
         stoppedReason: outcome.stoppedReason,
     };
-    ctx.log?.info?.(`[auth-mfa:reencrypt] complete: ${JSON.stringify(result)}`);
+    ctx.obs.log?.info?.(`[auth-mfa:reencrypt] complete: ${JSON.stringify(result)}`);
 }

package/dist/auth-mfa/handlers/regenerate-recovery.write.js

@@ -37,16 +37,16 @@ export function createRegenerateRecoveryHandler(opts) {
             // afterward.
             //
             // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts:
-            // without ctx.redis, verifyMfaFactor's TOTP-replay burn is skipped,
+            // without ctx.services.redis, verifyMfaFactor's TOTP-replay burn is skipped,
             // letting an observed code be replayed within the ±1-step window to
             // regenerate (and thus invalidate) recovery codes — a session-authed
             // route, so pre-unwiring JWTs stay a valid attack path.
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "regenerate-recovery (mfa) requires ctx.redis for TOTP replay protection",
+                    message: "regenerate-recovery (mfa) requires ctx.services.redis for TOTP replay protection",
                 }));
             }
-            const replay = { redis: ctx.redis, userId: event.user.id };
+            const replay = { redis: ctx.services.redis, userId: event.user.id };
             const verify = await verifyMfaFactor(row, event.payload.code, replay);
             if (!verify.ok)
                 return invalidTotpCode();

package/dist/auth-mfa/handlers/verify.write.js

@@ -29,8 +29,8 @@ export function createMfaVerifyHandler(opts) {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         escapeHatch: {
             grants: ["systemIdentity", "unsafeRaw"],
-            reason: "Pre-auth MFA step has no session yet — re-derives it via ctx.queryAs(SYSTEM, " +
-                "user:findForAuth) and ctx.resolveActiveMembership for the user the challenge token names. " +
+            reason: "Pre-auth MFA step has no session yet — re-derives it via ctx.dispatch.queryAs(SYSTEM, " +
+                "user:findForAuth) and ctx.auth.resolveActiveMembership for the user the challenge token names. " +
                 "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
                 "guest dispatch tenant.",
         },
@@ -46,19 +46,19 @@ export function createMfaVerifyHandler(opts) {
             // this route sits behind a challenge token from a successful login,
             // but its own secret is still just a short TOTP/recovery code —
             // silently skipping the brute-force cap and single-use burn when
-            // ctx.redis is absent would let a stolen challenge token be guessed
+            // ctx.services.redis is absent would let a stolen challenge token be guessed
             // against unboundedly, and let a recovery code be replayed via a
             // reissued challenge (mfa-verify-attempts.ts's counter is deliberately
             // NOT reset by reissuance, precisely to survive this).
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "verify (mfa) requires ctx.redis for the brute-force cap and single-use burn",
+                    message: "verify (mfa) requires ctx.services.redis for the brute-force cap and single-use burn",
                 }));
             }
             // Per-account brute-force cap — survives challenge-token reissuance
             // on purpose (see mfa-verify-attempts.ts header). Checked BEFORE the
             // TOTP/recovery verify so a locked account can't be guessed against.
-            const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+            const state = await getMfaVerifyLockoutState(ctx.services.redis, userId);
             if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
                 const now = Date.now();
                 if (state.lockedUntil > now) {
@@ -69,7 +69,12 @@ export function createMfaVerifyHandler(opts) {
             // "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({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+            const scopedDb = createTenantDb({
+                db: ctx.db.unsafeRaw(),
+                tenantId,
+                mode: "system",
+                reason: "MFA challenge has no session, the tenant comes from the verified challenge token",
+            });
             const scopedUser = { id: userId, tenantId, roles: ["User"] };
             const row = await findUserMfaRow(scopedDb, scopedUser);
             // MFA got disabled between login and verify (race, or a stale
@@ -77,10 +82,10 @@ export function createMfaVerifyHandler(opts) {
             // bad code, no detail leak about account state.
             if (!row)
                 return invalidChallengeToken();
-            const replay = { redis: ctx.redis, userId };
+            const replay = { redis: ctx.services.redis, userId };
             const verify = await verifyMfaFactor(row, event.payload.code, replay);
             if (!verify.ok) {
-                await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+                await recordFailedMfaVerifyAttempt(ctx.services.redis, userId, maxAttempts, lockoutMinutes);
                 return invalidTotpCode();
             }
             // Burn the challenge token only after a successful code check — a
@@ -91,7 +96,7 @@ export function createMfaVerifyHandler(opts) {
             // is reached, so this burn only needs to guard a DIFFERENT code
             // (recovery, or a still-valid-but-not-yet-burned TOTP step) reused
             // against the same challenge token.
-            const burnResult = await burnToken(ctx.redis, "mfa-challenge", userId, verified.expiresAtMs);
+            const burnResult = await burnToken(ctx.services.redis, "mfa-challenge", userId, verified.expiresAtMs);
             if (burnResult === "already-used")
                 return invalidChallengeToken();
             // Recovery-code use consumes the code — persist the reduced hash-list
@@ -106,12 +111,12 @@ export function createMfaVerifyHandler(opts) {
                 if (!updateResult.isSuccess)
                     return updateResult;
             }
-            await clearMfaVerifyAttempts(ctx.redis, userId);
+            await clearMfaVerifyAttempts(ctx.services.redis, userId);
             // Re-derive the full session the way login.write.ts would have, for
             // the SAME tenant the challenge token already committed to (no
             // "pick a tenant" step here — that already happened at login time).
             const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
-            const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+            const userRow = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
                 id: userId,
             })); // @cast-boundary engine-payload
             // Re-check status + membership the way login.write.ts does after its
@@ -130,7 +135,7 @@ export function createMfaVerifyHandler(opts) {
             const globalRoles = parseRoles(userRow?.roles ?? null);
             // Membership revoked or principal blocked between login and verify —
             // mirror login.write.ts's refusal instead of falling back to globalRoles only.
-            const active = await ctx.resolveActiveMembership(userId, tenantId);
+            const active = await ctx.auth.resolveActiveMembership(userId, tenantId);
             if (active.kind === "rejected")
                 return invalidChallengeToken();
             // buildSessionRoles calls stripForbiddenMembershipRoles to strip reserved
@@ -144,7 +149,7 @@ export function createMfaVerifyHandler(opts) {
                 ...sessionTimezoneField(userRow?.timezone),
                 ...sessionLocaleField(userRow?.locale),
             };
-            const claims = await ctx.resolveAuthClaims(baseSession);
+            const claims = await ctx.auth.resolveClaims(baseSession);
             const session = Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
             return { isSuccess: true, data: { kind: "mfa-verify-success", session } };
         },

package/dist/auth-mfa/mfa-code-verifier.js

@@ -14,15 +14,20 @@ export function createMfaCodeVerifier() {
         declareEscapeHatch({
             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({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+        const scopedDb = createTenantDb({
+            db: ctx.db.unsafeRaw(),
+            tenantId,
+            mode: "system",
+            reason: "re-authentication reads the MFA enrollment of the user's own tenant, not the handler's dispatch tenant",
+        });
         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 —
+        // Fail closed without ctx.services.redis, matching disable.write.ts/verify.write.ts —
         // skipping the TOTP-replay burn would let an observed code be replayed.
-        if (!code || !ctx.redis)
+        if (!code || !ctx.services.redis)
             return { enrolled: true, ok: false };
-        const verify = await verifyMfaFactor(row, code, { redis: ctx.redis, userId });
+        const verify = await verifyMfaFactor(row, code, { redis: ctx.services.redis, userId });
         return { enrolled: true, ok: verify.ok && verify.method === "totp" };
     };
 }

package/dist/auth-mfa/mfa-status-checker.js

@@ -11,7 +11,12 @@ export function createMfaStatusChecker(opts) {
         declareEscapeHatch({
             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({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+        const scopedDb = createTenantDb({
+            db: ctx.db.unsafeRaw(),
+            tenantId,
+            mode: "system",
+            reason: "login/setup token names the tenant to check, the guest dispatch tenant is meaningless",
+        });
         const scopedUser = { id: userId, tenantId, roles: ["User"] };
         const row = await findUserMfaRow(scopedDb, scopedUser);
         if (row) {
@@ -22,12 +27,12 @@ export function createMfaStatusChecker(opts) {
             return { required: true, challengeToken: token };
         }
         // ctx.config is bound to the CALLING user's tenant (the anonymous
-        // identity's tenant for login) — wrong tenant here. ctx.configResolver takes tenantId
+        // identity's tenant for login) — wrong tenant here. ctx.services.configResolver takes tenantId
         // explicitly, which is what a pre-session check against the LOGGING-IN
         // user's tenant needs.
         // @cast-boundary engine-payload — "select" config values are validated
         // against the declared `options` at write-time by the config feature.
-        const policy = ((await ctx.configResolver?.get(mfaRequiredConfigHandle.name, mfaRequiredConfigKey(opts.requiredPolicy), tenantId, userId, scopedDb)) ?? "optional");
+        const policy = ((await ctx.services.configResolver?.get(mfaRequiredConfigHandle.name, mfaRequiredConfigKey(opts.requiredPolicy), tenantId, userId, scopedDb)) ?? "optional");
         if (policy === "optional")
             return { required: false };
         const buildSetupToken = () => signMfaPreauthSetupToken({ userId, tenantId }, MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES, opts.challengeTokenSecret).token;

package/dist/auth-mfa/verify-factor.js

@@ -13,7 +13,7 @@ import { STEP_SECONDS, verifyTotp } from "./totp.js";
 // must not verify again within its ±1-step window — otherwise a code an
 // attacker observed once, via phishing proxy or shoulder-surfing, stays
 // usable for ~90s of parallel logins). Omitted where a caller has no
-// ctx.redis available; the code-verify itself still works, just without
+// ctx.services.redis available; the code-verify itself still works, just without
 // replay protection for that call.
 export async function verifyMfaFactor(row, code, replay) {
     const secret = base32Decode(row.totpSecret);

package/dist/billing-foundation/billing-info-query.js

@@ -39,8 +39,8 @@ export function createBillingInfoQueryConfig(deps) {
             const billingLive = ctx.config
                 ? (await ctx.config(STRIPE_BILLING_LIVE_CONFIG_QN)) === true
                 : false;
-            const apiKeySet = ctx.secrets
-                ? await ctx.secrets.has(SYSTEM_TENANT_ID, STRIPE_API_KEY_CONFIG_QN)
+            const apiKeySet = ctx.services.secrets
+                ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, STRIPE_API_KEY_CONFIG_QN)
                 : false;
             const sub = await ctx.db.fetchOne(subscriptionsProjectionTable, { id: subscriptionAggregateId(ctx.user.tenantId) });
             return {

package/dist/billing-foundation/consumer-protection/consent-gate.js

@@ -112,7 +112,7 @@ export async function recordConsent(ctx, prepared, details) {
     };
     const tenantId = ctx.user.tenantId;
     const isSubscription = prepared.mode === "subscription";
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
         aggregateId: isSubscription ? subscriptionAggregateId(tenantId) : paymentAggregateId(tenantId),
         aggregateType: isSubscription ? SUBSCRIPTION_AGGREGATE_TYPE : PAYMENT_AGGREGATE_TYPE,
         type: CHECKOUT_CONSENT_RECORDED_EVENT_QN,