@cosmicdrift/kumiko-bundled-features 0.200.0 → 0.201.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.200.0",
+  "version": "0.201.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>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.200.0",
-    "@cosmicdrift/kumiko-framework": "0.200.0",
-    "@cosmicdrift/kumiko-headless": "0.200.0",
-    "@cosmicdrift/kumiko-renderer": "0.200.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.200.0",
-    "@cosmicdrift/kumiko-types": "0.200.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.201.0",
+    "@cosmicdrift/kumiko-framework": "0.201.0",
+    "@cosmicdrift/kumiko-headless": "0.201.0",
+    "@cosmicdrift/kumiko-renderer": "0.201.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.201.0",
+    "@cosmicdrift/kumiko-types": "0.201.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

package/src/auth-email-password/__tests__/invite-flow.integration.test.ts

@@ -669,4 +669,131 @@ describe("privilege escalation via invite role", () => {
     )) as { role: string };
     expect(result.role).toBe("Editor");
   });
+
+  // Regression guard for the opt-in canAssignRole hook (#security): this
+  // stack's invite feature was mounted WITHOUT canAssignRole, so any
+  // non-reserved app-defined role must still go through unchanged — the
+  // hierarchy gate below is a separate, opt-in stack, not a default.
+  test("without canAssignRole configured, any non-reserved app-defined role is still assignable", async () => {
+    const result = (await stack.http.writeOk(
+      AuthHandlers.inviteCreate,
+      { email: "dpo-candidate@example.com", role: "DPO" },
+      aliceSession(),
+    )) as { role: string };
+    expect(result.role).toBe("DPO");
+  });
+});
+
+// canAssignRole is a role-hierarchy gate that must live in the app (roles are
+// app-defined strings, not a framework concept) — a separate stack mounts the
+// invite feature WITH the hook to prove it's actually enforced, distinct from
+// the framework-reserved-role check covered above.
+describe("invite-create role-hierarchy gate (opt-in canAssignRole)", () => {
+  let gateStack: TestStack;
+  let gateAliceId: string;
+  let gateTenantId: TenantId;
+  const gateTransport = createInMemoryTransport();
+
+  function gateAliceSession(): SessionUser {
+    return { id: gateAliceId, tenantId: gateTenantId, roles: ["Admin"] };
+  }
+
+  beforeAll(async () => {
+    gateStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createTemplateResolverFeature(),
+        createRendererFoundationFeature(),
+        createDeliveryFeature(),
+        createRendererSimpleFeature(),
+        createChannelEmailFeature({
+          transport: gateTransport,
+          renderer: simpleRenderer,
+          resolveEmail: async () => "unused@test.local",
+        }),
+        createAuthEmailPasswordFeature({
+          invite: {
+            tokenTtlMinutes: 60,
+            appUrl: APP_ACCEPT_URL,
+            // Only "Admin" may grant "DPO" — everything else may only grant
+            // non-DPO roles. A minimal, deliberately app-shaped hierarchy;
+            // the framework itself knows nothing about "DPO".
+            canAssignRole: (inviterRoles, targetRole) =>
+              targetRole !== "DPO" || inviterRoles.includes("Admin"),
+          },
+        }),
+      ],
+      extraContext: (deps) => ({
+        ...createDeliveryTestContext(deps),
+        configResolver: createConfigResolver(),
+      }),
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        loginHandler: AuthHandlers.login,
+        invite: {
+          acceptHandler: AuthHandlers.inviteAccept,
+          acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
+          signupCompleteHandler: AuthHandlers.inviteSignupComplete,
+        },
+      },
+    });
+
+    await unsafeCreateEntityTable(gateStack.db, userEntity);
+    await unsafeCreateEntityTable(gateStack.db, tenantEntity);
+    await unsafeCreateEntityTable(gateStack.db, tenantInvitationEntity);
+    await unsafePushTables(gateStack.db, {
+      configValuesTable,
+      tenantMembershipsTable,
+      notificationPreferencesTable,
+    });
+
+    gateTenantId = newTenantId("gate");
+    await seedTenant(gateStack.db, {
+      id: gateTenantId,
+      key: `tenant-gate-${gateTenantId.slice(0, 8)}`,
+      name: "Tenant Gate",
+    });
+    ({ id: gateAliceId } = await seedUser(gateStack.db, {
+      email: "gate-alice@example.com",
+      displayName: "Gate Alice",
+      passwordHash: await hashPassword("gate-alice-pw-1234"),
+      emailVerified: true,
+    }));
+    await seedTenantMembership(gateStack.db, {
+      userId: gateAliceId,
+      tenantId: gateTenantId,
+      roles: ["Admin"],
+    });
+  });
+
+  afterAll(async () => {
+    await gateStack.cleanup();
+  });
+
+  test("canAssignRole → false blocks invite-create with a role-hierarchy error, no invitation persisted", async () => {
+    // TenantAdmin clears the handler's own access.admin gate but canAssignRole
+    // above only lets literal "Admin" grant "DPO" — the case this hook exists for.
+    const err = await gateStack.http.writeErr(
+      AuthHandlers.inviteCreate,
+      { email: "blocked-target@example.com", role: "DPO" },
+      { id: gateAliceId, tenantId: gateTenantId, roles: ["TenantAdmin"] },
+    );
+    expect(err.details).toMatchObject({ reason: "unassignable_membership_role", role: "DPO" });
+    const rows = await selectMany(gateStack.db, tenantInvitationsTable, {
+      email: "blocked-target@example.com",
+    });
+    expect(rows).toHaveLength(0);
+    expect(gateTransport.sent).toHaveLength(0);
+  });
+
+  test("canAssignRole → true allows invite-create through", async () => {
+    const result = (await gateStack.http.writeOk(
+      AuthHandlers.inviteCreate,
+      { email: "allowed-target@example.com", role: "DPO" },
+      gateAliceSession(),
+    )) as { role: string };
+    expect(result.role).toBe("DPO");
+  });
 });

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -33,6 +33,7 @@ import {
 import {
   findForbiddenMembershipRole,
   reservedMembershipRoleError,
+  unassignableMembershipRoleError,
 } from "../../tenant/membership-roles";
 import { AUTH_INVITE_DEFAULT_TTL_MINUTES } from "../constants";
 import type { AuthMailLocale } from "../email-templates";
@@ -64,6 +65,10 @@ export type InviteCreateOptions = {
   readonly appUrl: string;
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
+  // Opt-in role-hierarchy gate. Roles are app-defined strings, not a framework
+  // concept, so the hierarchy itself must live in the app — this hook lets it
+  // plug in without the framework hardcoding any role names.
+  readonly canAssignRole?: (inviterRoles: readonly string[], targetRole: string) => boolean;
 };
 
 const executor = createEventStoreExecutor(tenantInvitationsTable, tenantInvitationEntity, {
@@ -90,6 +95,10 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
         return writeFailure(reservedMembershipRoleError(forbiddenRole));
       }
 
+      if (opts.canAssignRole && !opts.canAssignRole(event.user.roles, event.payload.role)) {
+        return writeFailure(unassignableMembershipRoleError(event.payload.role));
+      }
+
       const email = event.payload.email.toLowerCase();
       const tenantId = event.user.tenantId;
       const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });

package/src/auth-mfa/feature.ts

@@ -11,6 +11,7 @@ import { createRegenerateRecoveryHandler } from "./handlers/regenerate-recovery.
 import { mfaStatusQuery } from "./handlers/status.query";
 import { createMfaVerifyHandler } from "./handlers/verify.write";
 import { AUTH_MFA_FEATURE_I18N } from "./i18n";
+import { createMfaCodeVerifier, type MfaCodeVerifier } from "./mfa-code-verifier";
 import { createMfaStatusChecker, type MfaStatusChecker } from "./mfa-status-checker";
 import { userMfaEntity } from "./schema/user-mfa";
 
@@ -70,6 +71,42 @@ export function mfaStatusCheckerFromFeature(
   return undefined;
 }
 
+// Reads the eagerly-built `verifyMfaCode` off a mounted auth-mfa feature's
+// exports — personal-access-tokens wires this in as its optional
+// mfaVerifier (re-auth gate for minting a token). Same no-bind-setter
+// reasoning as checkMfaStatus above.
+export function mfaVerifierFromFeature(feature: FeatureDefinition): MfaCodeVerifier | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "verifyMfaCode" in exports) {
+    const { verifyMfaCode } = exports as { verifyMfaCode: unknown };
+    if (typeof verifyMfaCode === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return verifyMfaCode as MfaCodeVerifier;
+    }
+  }
+  return undefined;
+}
+
+export type BindRevokeAllPatTokens = (revoker: (userId: string) => Promise<number>) => void;
+
+// Reads the late-bind setter off a mounted auth-mfa feature's exports —
+// run{Prod,Dev}App call this once the personal-access-tokens feature (if
+// mounted) has produced a concrete revoker, same wiring shape as
+// bindMfaRevokeAllOtherSessionsFromFeature.
+export function bindRevokeAllPatTokensFromFeature(
+  feature: FeatureDefinition,
+): BindRevokeAllPatTokens | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindRevokeAllPatTokens" in exports) {
+    const { bindRevokeAllPatTokens } = exports as { bindRevokeAllPatTokens: unknown };
+    if (typeof bindRevokeAllPatTokens === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindRevokeAllPatTokens as BindRevokeAllPatTokens;
+    }
+  }
+  return undefined;
+}
+
 export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefinition {
   return defineFeature("auth-mfa", (r) => {
     r.describe(
@@ -120,6 +157,14 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     const sharedRevoker = (userId: string, currentSid: string | undefined): Promise<number> =>
       revokeAllOtherSessions?.(userId, currentSid) ?? Promise.resolve(0);
 
+    // Same late-bind shape as sharedRevoker above, for the personal-access-
+    // tokens feature (if mounted). Wired to enable-confirm(-preauth)/disable
+    // only — regenerate-recovery doesn't change enrollment state, so it's
+    // out of scope for the "MFA-enable/disable" finding this mirrors.
+    let revokeAllPatTokens: ((userId: string) => Promise<number>) | undefined;
+    const sharedPatRevoker = (userId: string): Promise<number> =>
+      revokeAllPatTokens?.(userId) ?? Promise.resolve(0);
+
     const handlers = {
       enableStart: r.writeHandler(
         createEnableStartHandler({ setupTokenSecret: opts.setupTokenSecret, issuer: opts.issuer }),
@@ -135,15 +180,22 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
         createEnableConfirmHandler({
           setupTokenSecret: opts.setupTokenSecret,
           revokeAllOtherSessions: sharedRevoker,
+          revokeAllPatTokens: sharedPatRevoker,
         }),
       ),
       enableConfirmPreauth: r.writeHandler(
         createEnableConfirmPreauthHandler({
           setupTokenSecret: opts.setupTokenSecret,
           revokeAllOtherSessions: sharedRevoker,
+          revokeAllPatTokens: sharedPatRevoker,
+        }),
+      ),
+      disable: r.writeHandler(
+        createDisableHandler({
+          revokeAllOtherSessions: sharedRevoker,
+          revokeAllPatTokens: sharedPatRevoker,
         }),
       ),
-      disable: r.writeHandler(createDisableHandler({ revokeAllOtherSessions: sharedRevoker })),
       regenerateRecovery: r.writeHandler(
         createRegenerateRecoveryHandler({ revokeAllOtherSessions: sharedRevoker }),
       ),
@@ -164,10 +216,25 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
       challengeTokenSecret: opts.challengeTokenSecret,
     });
 
+    // No late-bind needed — same reasoning as checkMfaStatus: only needs the
+    // HandlerContext the caller already has.
+    const verifyMfaCode = createMfaCodeVerifier();
+
     const bindRevokeAllOtherSessions: BindMfaRevokeAllOtherSessions = (revoker) => {
       revokeAllOtherSessions = revoker;
     };
 
-    return { handlers, queries, bindRevokeAllOtherSessions, checkMfaStatus };
+    const bindRevokeAllPatTokens: BindRevokeAllPatTokens = (revoker) => {
+      revokeAllPatTokens = revoker;
+    };
+
+    return {
+      handlers,
+      queries,
+      bindRevokeAllOtherSessions,
+      checkMfaStatus,
+      verifyMfaCode,
+      bindRevokeAllPatTokens,
+    };
   });
 }

package/src/auth-mfa/handlers/disable.write.ts

@@ -12,6 +12,10 @@ export type DisableOptions = {
     userId: string,
     currentSid: string | undefined,
   ) => Promise<number>;
+  // Wired late by run-prod-app once the personal-access-tokens feature (if
+  // mounted) is concrete. Absent when PAT isn't mounted: disabling MFA just
+  // doesn't revoke PAT tokens.
+  readonly revokeAllPatTokens?: (userId: string) => Promise<number>;
 };
 
 const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
@@ -60,6 +64,9 @@ export function createDisableHandler(opts: DisableOptions) {
       if (opts.revokeAllOtherSessions) {
         await opts.revokeAllOtherSessions(event.user.id, event.user.sid);
       }
+      if (opts.revokeAllPatTokens) {
+        await opts.revokeAllPatTokens(event.user.id);
+      }
 
       return { isSuccess: true, data: { disabled: true } };
     },

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

@@ -36,6 +36,10 @@ export type EnableConfirmPreauthOptions = {
     userId: string,
     currentSid: string | undefined,
   ) => Promise<number>;
+  // Wired late by run-prod-app once the personal-access-tokens feature (if
+  // mounted) is concrete. Absent when PAT isn't mounted: enabling MFA just
+  // doesn't revoke PAT tokens.
+  readonly revokeAllPatTokens?: (userId: string) => Promise<number>;
 };
 
 const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
@@ -202,6 +206,9 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       if (opts.revokeAllOtherSessions) {
         await opts.revokeAllOtherSessions(userId, undefined);
       }
+      if (opts.revokeAllPatTokens) {
+        await opts.revokeAllPatTokens(userId);
+      }
 
       return { isSuccess: true, data: { kind: "mfa-preauth-confirm-success", session } };
     },

package/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -20,6 +20,10 @@ export type EnableConfirmOptions = {
     userId: string,
     currentSid: string | undefined,
   ) => Promise<number>;
+  // Wired late by run-prod-app once the personal-access-tokens feature (if
+  // mounted) is concrete. Absent when PAT isn't mounted: enabling MFA just
+  // doesn't revoke PAT tokens.
+  readonly revokeAllPatTokens?: (userId: string) => Promise<number>;
 };
 
 const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
@@ -99,6 +103,9 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
       if (opts.revokeAllOtherSessions) {
         await opts.revokeAllOtherSessions(event.user.id, event.user.sid);
       }
+      if (opts.revokeAllPatTokens) {
+        await opts.revokeAllPatTokens(event.user.id);
+      }
 
       return { isSuccess: true, data: { enabled: true } };
     },

package/src/auth-mfa/index.ts

@@ -9,12 +9,16 @@ export {
 export type {
   AuthMfaFeatureOptions,
   BindMfaRevokeAllOtherSessions,
+  BindRevokeAllPatTokens,
 } from "./feature";
 export {
   bindMfaRevokeAllOtherSessionsFromFeature,
+  bindRevokeAllPatTokensFromFeature,
   createAuthMfaFeature,
   mfaStatusCheckerFromFeature,
+  mfaVerifierFromFeature,
 } from "./feature";
+export type { MfaCodeVerifier, MfaCodeVerifyResult } from "./mfa-code-verifier";
 export type { MfaStatusChecker, MfaStatusCheckResult } from "./mfa-status-checker";
 export { userMfaEntity, userMfaTable } from "./schema/user-mfa";
 export {

package/src/auth-mfa/mfa-code-verifier.ts

@@ -0,0 +1,33 @@
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { findUserMfaRow } from "./db/queries";
+import { verifyMfaFactor } from "./verify-factor";
+
+export type MfaCodeVerifyResult = { readonly enrolled: boolean; readonly ok: boolean };
+
+export type MfaCodeVerifier = (
+  ctx: HandlerContext,
+  userId: string,
+  tenantId: TenantId,
+  code: string | undefined,
+) => Promise<MfaCodeVerifyResult>;
+
+// Re-auth-only primitive (personal-access-tokens' currentPassword+mfaCode
+// gate), distinct from login's mfaStatusChecker (enrollment/policy only, no
+// code) and from verify.write.ts (full login-completion flow). TOTP-only —
+// a recovery code accepted here without persisting single-use consumption
+// (verify.write.ts's remainingHashes update) would become infinitely
+// reusable, and a re-auth gate is not the account-recovery flow recovery
+// codes exist for.
+export function createMfaCodeVerifier(): MfaCodeVerifier {
+  return async (ctx, userId, tenantId, code) => {
+    const scopedDb = createTenantDb(ctx.db.raw, tenantId, "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 —
+    // skipping the TOTP-replay burn would let an observed code be replayed.
+    if (!code || !ctx.redis) return { enrolled: true, ok: false };
+    const verify = await verifyMfaFactor(row, code, { redis: ctx.redis, userId });
+    return { enrolled: true, ok: verify.ok && verify.method === "totp" };
+  };
+}

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -37,11 +37,12 @@ import { userSessionEntity } from "../../sessions/schema/user-session";
 import { createTenantFeature } from "../../tenant";
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 import { tenantEntity } from "../../tenant/schema/tenant";
-import { USER_STATUS } from "../../user";
+import { USER_STATUS, UserHandlers, UserQueries } from "../../user";
 import { createUserFeature } from "../../user/feature";
 import { userEntity, userTable } from "../../user/schema/user";
-import { PatHandlers, PatQueries } from "../constants";
+import { PAT_DEFAULT_EXPIRES_IN_DAYS, PatErrors, PatHandlers, PatQueries } from "../constants";
 import { createPersonalAccessTokensFeature } from "../feature";
+import { revokeAllPatTokensForUser } from "../revoke-for-user";
 import { apiTokenEntity, apiTokenTable } from "../schema/api-token";
 import type { PatScopeConfig } from "../scopes";
 
@@ -66,14 +67,21 @@ const SCOPES: PatScopeConfig = {
 
 async function mintToken(
   actor: SessionUser,
-  opts?: { scopes?: string[]; expiresInDays?: number },
+  opts?: {
+    scopes?: string[];
+    expiresInDays?: number;
+    currentPassword?: string;
+    mfaCode?: string;
+  },
 ): Promise<string> {
   const res = await stack.http.writeOk<{ id: string; token: string }>(
     PatHandlers.create,
     {
       name: "test",
       scopes: opts?.scopes ?? ["tokens:read"],
+      currentPassword: opts?.currentPassword ?? "pw",
       ...(opts?.expiresInDays ? { expiresInDays: opts.expiresInDays } : {}),
+      ...(opts?.mfaCode ? { mfaCode: opts.mfaCode } : {}),
     },
     actor,
   );
@@ -91,7 +99,12 @@ beforeAll(async () => {
       createTenantFeature(),
       createAuthEmailPasswordFeature(),
       createSessionsFeature(),
-      createPersonalAccessTokensFeature({ scopes: SCOPES }),
+      createPersonalAccessTokensFeature({
+        scopes: SCOPES,
+        // Closure over `stack` is fine here: the hook only invokes this at
+        // fire-time, well after setupTestStack below has assigned it.
+        autoRevokeOnPasswordChange: (userId) => revokeAllPatTokensForUser(stack.db, userId),
+      }),
       authFoundationFeature,
     ],
     extraContext: { configResolver: resolver, configEncryption: encryption },
@@ -253,3 +266,157 @@ describe("PAT with active KMS (#820): token name is userOwned PII", () => {
     }
   });
 });
+
+describe("PAT create: re-auth (#security)", () => {
+  test("missing currentPassword → rejected, no token minted", async () => {
+    const actor = await actorFor("reauth-missing@example.com");
+    const err = await stack.http.writeErr(
+      PatHandlers.create,
+      { name: "test", scopes: ["tokens:read"] },
+      actor,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    const rows = await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    expect(rows).toHaveLength(0);
+  });
+
+  test("wrong currentPassword → rejected, no token minted", async () => {
+    const actor = await actorFor("reauth-wrong@example.com");
+    const err = await stack.http.writeErr(
+      PatHandlers.create,
+      { name: "test", scopes: ["tokens:read"], currentPassword: "not-the-password" },
+      actor,
+    );
+    expect(err.details).toMatchObject({ reason: PatErrors.reauthRequired });
+    const rows = await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    expect(rows).toHaveLength(0);
+  });
+
+  test("expiresInDays omitted → defaults to ~90 days, not never-expiring", async () => {
+    const actor = await actorFor("reauth-expiry@example.com");
+    await mintToken(actor);
+    const rows = await stack.http.queryOk<Array<{ id: string; expiresAt: string | null }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
+    expect(rows[0]?.expiresAt).not.toBeNull();
+    const expiresAt = Temporal.Instant.from(rows[0]?.expiresAt as string);
+    const expected = Temporal.Now.instant().add({ hours: 24 * PAT_DEFAULT_EXPIRES_IN_DAYS });
+    const driftHours = Math.abs(expiresAt.since(expected).total({ unit: "hours" }));
+    expect(driftHours).toBeLessThan(1);
+  });
+});
+
+describe("PAT create: MFA re-auth gate", () => {
+  let mfaStack: TestStack;
+  let mfaH: ReturnType<typeof makeSessionHelpers>;
+
+  beforeAll(async () => {
+    const encryption = createTestEnvelopeCipher(encryptionKey);
+    const resolver = createConfigResolver({ cipher: encryption });
+    mfaStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createAuthEmailPasswordFeature(),
+        createSessionsFeature(),
+        createPersonalAccessTokensFeature({
+          scopes: SCOPES,
+          // Stub verifier: always enrolled, code never accepted — exercises
+          // the real gate over HTTP without depending on auth-mfa's TOTP
+          // machinery (same shape as sessions' massRevokeSpy tests).
+          mfaVerifier: async () => ({ enrolled: true, ok: false }),
+        }),
+        authFoundationFeature,
+      ],
+      extraContext: { configResolver: resolver, configEncryption: encryption },
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        loginHandler: AuthHandlers.login,
+        tokenVerifier: (raw: string) =>
+          resolveTokenVerifier({ db: mfaStack.db, registry: mfaStack.registry }, raw),
+        patRateLimiter: createInMemoryLoginRateLimiter(10, 60_000),
+      },
+    });
+    mfaH = makeSessionHelpers(mfaStack, TENANT);
+    await unsafeCreateEntityTable(mfaStack.db, userEntity);
+    await unsafeCreateEntityTable(mfaStack.db, tenantEntity);
+    await unsafeCreateEntityTable(mfaStack.db, userSessionEntity);
+    await unsafeCreateEntityTable(mfaStack.db, apiTokenEntity);
+    await unsafePushTables(mfaStack.db, { configValuesTable, tenantMembershipsTable });
+  });
+
+  afterAll(async () => {
+    await mfaStack.cleanup();
+  });
+
+  test("MFA-enrolled user without mfaCode → rejected, no token minted", async () => {
+    const { userId } = await mfaH.seedUser("mfa-missing-code@example.com", "pw");
+    const actor: SessionUser = { id: userId, tenantId: TENANT, roles: ["User"] };
+    const err = await mfaStack.http.writeErr(
+      PatHandlers.create,
+      { name: "test", scopes: ["tokens:read"], currentPassword: "pw" },
+      actor,
+    );
+    expect(err.details).toMatchObject({ reason: PatErrors.reauthRequired });
+    const rows = await mfaStack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    expect(rows).toHaveLength(0);
+  });
+
+  test("MFA-enrolled user with wrong mfaCode → rejected, no token minted", async () => {
+    const { userId } = await mfaH.seedUser("mfa-wrong-code@example.com", "pw");
+    const actor: SessionUser = { id: userId, tenantId: TENANT, roles: ["User"] };
+    const err = await mfaStack.http.writeErr(
+      PatHandlers.create,
+      { name: "test", scopes: ["tokens:read"], currentPassword: "pw", mfaCode: "000000" },
+      actor,
+    );
+    expect(err.details).toMatchObject({ reason: PatErrors.reauthRequired });
+    const rows = await mfaStack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    expect(rows).toHaveLength(0);
+  });
+});
+
+describe("PAT revoke on password change (#security)", () => {
+  test("changing password revokes all of the user's live PAT tokens", async () => {
+    const actor = await actorFor("pat-revoke-pwchange@example.com");
+    const token = await mintToken(actor);
+    const preCheck = await h.authedPost("/api/query", token, {
+      type: PatQueries.mine,
+      payload: {},
+    });
+    expect(preCheck.status).toBe(200);
+
+    await stack.http.writeOk(
+      AuthHandlers.changePassword,
+      { oldPassword: "pw", newPassword: "NewPassw0rd!42" },
+      actor,
+    );
+
+    const rows = await selectMany<{ revokedAt: string | null }>(stack.db, apiTokenTable, {
+      userId: actor.id,
+    });
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.every((row) => row.revokedAt !== null)).toBe(true);
+
+    const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(401);
+  });
+
+  test("editing a non-password field does NOT revoke PAT tokens", async () => {
+    const actor = await actorFor("pat-no-revoke-other-field@example.com");
+    const token = await mintToken(actor);
+
+    const me = await stack.http.queryOk<{ version: number }>(UserQueries.me, {}, actor);
+    await stack.http.writeOk(
+      UserHandlers.update,
+      { id: actor.id, version: me.version, changes: { displayName: "New Name" } },
+      actor,
+    );
+
+    const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(200);
+  });
+});

package/src/personal-access-tokens/constants.ts

@@ -6,8 +6,16 @@ export const PAT_FEATURE = "personal-access-tokens";
 // Snake_case reason strings (Error-Reasons guard: no colons/dashes).
 export const PatErrors = {
   ownershipDenied: "ownership_denied",
+  // Uniform for wrong-password AND missing/wrong MFA code — a distinct
+  // reason per case would leak whether the account has MFA enrolled.
+  reauthRequired: "reauth_required",
 } as const;
 
+// expiresInDays default when omitted at mint time. A silent "never expires"
+// default is a standing-credential risk; the existing 3650-day cap still
+// lets callers who genuinely want a long-lived token pass it explicitly.
+export const PAT_DEFAULT_EXPIRES_IN_DAYS = 90;
+
 // Dormant custom-screen id (r.screen) — the app places it via r.nav. The client
 // maps it to the PatTokensScreen component.
 export const PAT_SCREEN_ID = "api-tokens";

package/src/personal-access-tokens/feature.ts

@@ -7,7 +7,7 @@ import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PAT_SCREEN_ID, type PatRateLimit } from "./constants";
 import { buildAvailableScopesQuery } from "./handlers/available-scopes.query";
-import { createPatWrite } from "./handlers/create.write";
+import { type CreatePatOptions, createPatCreateHandler } from "./handlers/create.write";
 import { listPatQuery } from "./handlers/list.query";
 import { revokePatWrite } from "./handlers/revoke.write";
 import { PAT_FEATURE_I18N } from "./i18n";
@@ -15,6 +15,36 @@ import { createPatResolver } from "./resolver";
 import { apiTokenEntity } from "./schema/api-token";
 import type { PatScopeConfig } from "./scopes";
 
+// Password-change is the only field-level trigger — see the postSave hook
+// below. MFA-enable/disable is wired separately (auth-mfa's
+// revokeAllPatTokens callback, late-bound at app-composition time) since
+// that's a different entity ("user-mfa") this feature doesn't own or
+// require.
+const PAT_REVOKE_TRIGGERING_FIELDS = ["passwordHash"] as const;
+
+export type BindPatAutoRevokeOnPasswordChange = (
+  revoker: (userId: string) => Promise<number>,
+) => void;
+
+// Reads the late-bind setter off a mounted personal-access-tokens feature's
+// exports — run{Prod,Dev}App call this once a concrete db is available,
+// mirrors sessions' own bindAutoRevokeFromFeature/bindAutoRevokeOnPasswordChange.
+export function bindPatAutoRevokeOnPasswordChangeFromFeature(
+  feature: FeatureDefinition,
+): BindPatAutoRevokeOnPasswordChange | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
+    const { bindAutoRevokeOnPasswordChange } = exports as {
+      bindAutoRevokeOnPasswordChange: unknown;
+    };
+    if (typeof bindAutoRevokeOnPasswordChange === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindAutoRevokeOnPasswordChange as BindPatAutoRevokeOnPasswordChange;
+    }
+  }
+  return undefined;
+}
+
 export type PersonalAccessTokensOptions = {
   // The scopes this deployment offers. Each is a named bundle of QN globs a PAT
   // may be granted (a scope can span features). Closed over by available-scopes
@@ -28,10 +58,20 @@ export type PersonalAccessTokensOptions = {
    *  { default: false } for fail-closed gating (feature off until a tier grants
    *  it). Omit to keep PAT always-on (default). */
   readonly toggleable?: { readonly default: boolean };
+  // Opt-in MFA re-auth gate for minting a token — wired via
+  // mfaVerifierFromFeature (auth-mfa/feature.ts) at app-composition time. No
+  // hard dependency on the optional auth-mfa feature.
+  readonly mfaVerifier?: CreatePatOptions["mfaVerifier"];
+  // Password-change revoker — same constructor-option-or-late-bind duality as
+  // sessions' own autoRevokeOnPasswordChange (bindAutoRevokeOnPasswordChange
+  // below wins only if this is unset). Lets tests pass a revoker directly
+  // instead of needing a post-setupTestStack bind call.
+  readonly autoRevokeOnPasswordChange?: (userId: string) => Promise<number>;
 };
 
 export type PatFeatureExports = {
   readonly rateLimit: PatRateLimit;
+  readonly bindAutoRevokeOnPasswordChange: BindPatAutoRevokeOnPasswordChange;
 };
 
 // Personal Access Tokens — long-lived, revocable bearer credentials for the
@@ -73,8 +113,31 @@ export function createPersonalAccessTokensFeature(
       piiEncryptedOnWrite: true,
     });
 
+    // Password-change auto-revoke — mirrors sessions' own
+    // autoRevokeOnPasswordChange postSave hook, including WHY it's a
+    // late-bind callback rather than direct ctx.db use: user:write:user:update
+    // is r.systemScope()'d (the user aggregate is a systemStream, framework
+    // #497), so a postSave hook on "user" gets a poisoned ctx.db here. The
+    // concrete revoker is bound once run{Prod,Dev}App has a real db handle.
+    let autoRevokeOnPasswordChange = options.autoRevokeOnPasswordChange;
+    r.hook("postSave", { allOf: "user" }, async (result) => {
+      // skip: nothing bound — same late-bind pattern as sessions/feature.ts
+      if (!autoRevokeOnPasswordChange) return;
+      // skip: brand-new user, no PATs can exist yet
+      if (result.isNew) return;
+      // skip: handler didn't touch any revoke-triggering field
+      if (!PAT_REVOKE_TRIGGERING_FIELDS.some((field) => result.changes[field] !== undefined)) {
+        return;
+      }
+      await autoRevokeOnPasswordChange(String(result.id));
+    });
+    const bindAutoRevokeOnPasswordChange: BindPatAutoRevokeOnPasswordChange = (revoker) => {
+      // explicit constructor option wins over the runtime binding
+      autoRevokeOnPasswordChange ??= revoker;
+    };
+
     const handlers = {
-      create: r.writeHandler(createPatWrite),
+      create: r.writeHandler(createPatCreateHandler({ mfaVerifier: options.mfaVerifier })),
       revoke: r.writeHandler(revokePatWrite),
     };
     const queries = {
@@ -102,6 +165,7 @@ export function createPersonalAccessTokensFeature(
     return {
       handlers,
       queries,
+      bindAutoRevokeOnPasswordChange,
       rateLimit: options.rateLimit ?? PAT_DEFAULT_RATE_LIMIT,
     } satisfies { handlers: unknown; queries: unknown } & PatFeatureExports;
   });

package/src/personal-access-tokens/handlers/create.write.ts

@@ -1,47 +1,105 @@
 import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type HandlerContext,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
-import { encryptForDirectWrite } from "../../shared";
+import { encryptForDirectWrite, verifyPassword } from "../../shared";
+import { UserQueries } from "../../user";
+import { PAT_DEFAULT_EXPIRES_IN_DAYS, PatErrors } from "../constants";
 import { mintPatToken } from "../hash";
 import { apiTokenEntity, apiTokenTable } from "../schema/api-token";
 
+export type PatMfaVerifyResult = { readonly enrolled: boolean; readonly ok: boolean };
+
+export type CreatePatOptions = {
+  // Opt-in MFA re-auth gate — auth-mfa (if mounted) wires this in at
+  // app-composition time via mfaVerifierFromFeature. Deliberately generic
+  // here, same decoupling as login.write.ts's mfaStatusChecker: this
+  // feature must not import auth-mfa's types, only this shape.
+  readonly mfaVerifier?: (
+    ctx: HandlerContext,
+    userId: string,
+    tenantId: TenantId,
+    code: string | undefined,
+  ) => Promise<PatMfaVerifyResult>;
+};
+
+function reauthFailed() {
+  return writeFailure(
+    new UnprocessableError(PatErrors.reauthRequired, {
+      i18nKey: "errors.reauthRequired",
+    }),
+  );
+}
+
 // Mint a PAT for the calling user in their active tenant. The plaintext token
 // is returned ONCE (data.token) and never again — only the hash is stored.
 // `scopes` are granted scope names; unknown names simply grant nothing at
 // resolve time (fail-closed), so no cross-check against the app config here.
-export const createPatWrite = defineWriteHandler({
-  name: "create",
-  schema: z.object({
-    name: z.string().min(1).max(120),
-    scopes: z.array(z.string().min(1)).min(1),
-    expiresInDays: z.number().int().positive().max(3650).optional(),
-  }),
-  access: { openToAll: true },
-  handler: async (event, ctx) => {
-    const { raw, hash, prefix } = mintPatToken();
-    const now = Temporal.Now.instant();
-    const id = generateId();
-    const row = await encryptForDirectWrite(
-      apiTokenEntity,
-      {
-        id,
-        userId: event.user.id,
-        tenantId: event.user.tenantId,
-        name: event.payload.name,
-        tokenHash: hash,
-        prefix,
-        scopes: JSON.stringify(event.payload.scopes),
-        createdAt: now,
-        expiresAt: event.payload.expiresInDays
-          ? now.add({ hours: 24 * event.payload.expiresInDays })
-          : null,
-        revokedAt: null,
-      },
-      "pat:create",
-    );
-    await insertOne(ctx.db, apiTokenTable, row);
-    return { isSuccess: true, data: { id, token: raw, prefix } };
-  },
-});
+//
+// Minting a long-lived bearer credential re-verifies the caller's password
+// (and MFA code, if enrolled) even though the request is already
+// session-authed — a stolen/leaked session cookie must not be enough to
+// stand up a durable API credential.
+export function createPatCreateHandler(opts: CreatePatOptions = {}) {
+  return defineWriteHandler({
+    name: "create",
+    schema: z.object({
+      name: z.string().min(1).max(120),
+      scopes: z.array(z.string().min(1)).min(1),
+      expiresInDays: z.number().int().positive().max(3650).optional(),
+      currentPassword: z.string().min(1),
+      mfaCode: z.string().optional(),
+    }),
+    access: { openToAll: true },
+    handler: async (event, ctx) => {
+      const systemUser = createSystemUser(event.user.tenantId);
+      const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+        id: event.user.id,
+      })) as { passwordHash: string | null } | null; // @cast-boundary db-runner
+      if (!me?.passwordHash) return reauthFailed();
+      const passwordOk = await verifyPassword(me.passwordHash, event.payload.currentPassword);
+      if (!passwordOk) return reauthFailed();
+
+      if (opts.mfaVerifier) {
+        const mfa = await opts.mfaVerifier(
+          ctx,
+          event.user.id,
+          event.user.tenantId,
+          event.payload.mfaCode,
+        );
+        if (mfa.enrolled && !mfa.ok) return reauthFailed();
+      }
+
+      const { raw, hash, prefix } = mintPatToken();
+      const now = Temporal.Now.instant();
+      const id = generateId();
+      const row = await encryptForDirectWrite(
+        apiTokenEntity,
+        {
+          id,
+          userId: event.user.id,
+          tenantId: event.user.tenantId,
+          name: event.payload.name,
+          tokenHash: hash,
+          prefix,
+          scopes: JSON.stringify(event.payload.scopes),
+          createdAt: now,
+          expiresAt: now.add({
+            hours: 24 * (event.payload.expiresInDays ?? PAT_DEFAULT_EXPIRES_IN_DAYS),
+          }),
+          revokedAt: null,
+        },
+        "pat:create",
+      );
+      await insertOne(ctx.db, apiTokenTable, row);
+      return { isSuccess: true, data: { id, token: raw, prefix } };
+    },
+  });
+}

package/src/personal-access-tokens/index.ts

@@ -3,10 +3,15 @@ import { PAT_DEFAULT_RATE_LIMIT, type PatRateLimit } from "./constants";
 
 export type { PatRateLimit } from "./constants";
 export { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PatHandlers, PatQueries } from "./constants";
-export type { PersonalAccessTokensOptions } from "./feature";
-export { createPersonalAccessTokensFeature } from "./feature";
+export type { BindPatAutoRevokeOnPasswordChange, PersonalAccessTokensOptions } from "./feature";
+export {
+  bindPatAutoRevokeOnPasswordChangeFromFeature,
+  createPersonalAccessTokensFeature,
+} from "./feature";
+export type { CreatePatOptions, PatMfaVerifyResult } from "./handlers/create.write";
 export { hashPatToken, mintPatToken } from "./hash";
 export { createPatResolver } from "./resolver";
+export { revokeAllPatTokensForUser } from "./revoke-for-user";
 export { apiTokenEntity, apiTokenTable } from "./schema/api-token";
 export type { PatScopeConfig, PatScopeDef } from "./scopes";
 export { expandScopes } from "./scopes";

package/src/personal-access-tokens/revoke-for-user.ts

@@ -0,0 +1,18 @@
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { Temporal } from "temporal-polyfill";
+import { apiTokenTable } from "./schema/api-token";
+
+// Cross-tenant revoke: password-change and MFA-enable/disable are account-
+// level security events, not scoped to one tenant. Mirrors sessions'
+// sessionMassRevoker (session-callbacks.ts) which passes the boot-time
+// DbConnection directly — not ctx.db, which would be tenant-scoped in a hook.
+export async function revokeAllPatTokensForUser(db: DbConnection, userId: string): Promise<number> {
+  const updated = await updateMany<{ id: string }>(
+    db,
+    apiTokenTable,
+    { revokedAt: Temporal.Now.instant() },
+    { userId, revokedAt: null },
+  );
+  return updated.length;
+}

package/src/personal-access-tokens/web/i18n.ts

@@ -17,6 +17,10 @@ export const defaultTranslations: TranslationsByLocale = {
     "pat.create.submit": "Token erstellen",
     "pat.create.needName": "Bitte einen Namen vergeben.",
     "pat.create.needScope": "Bitte mindestens eine Berechtigung wählen.",
+    "pat.create.needPassword": "Bitte dein Passwort zur Bestätigung eingeben.",
+    "pat.create.currentPassword": "Passwort (zur Bestätigung)",
+    "pat.create.mfaCode": "2FA-Code (falls aktiviert)",
+    "pat.create.mfaCodePlaceholder": "6-stelliger Code",
     "pat.expiry.30d": "30 Tage",
     "pat.expiry.90d": "90 Tage",
     "pat.expiry.1y": "1 Jahr",
@@ -49,6 +53,10 @@ export const defaultTranslations: TranslationsByLocale = {
     "pat.create.submit": "Create token",
     "pat.create.needName": "Please enter a name.",
     "pat.create.needScope": "Please select at least one permission.",
+    "pat.create.needPassword": "Please enter your password to confirm.",
+    "pat.create.currentPassword": "Password (to confirm)",
+    "pat.create.mfaCode": "2FA code (if enabled)",
+    "pat.create.mfaCodePlaceholder": "6-digit code",
     "pat.expiry.30d": "30 days",
     "pat.expiry.90d": "90 days",
     "pat.expiry.1y": "1 year",

package/src/personal-access-tokens/web/pat-tokens-screen.tsx

@@ -57,6 +57,8 @@ export function PatTokensScreen({
   const [name, setName] = useState("");
   const [levels, setLevels] = useState<Readonly<Record<string, Level>>>({});
   const [expiry, setExpiry] = useState<ExpiryKey>("90d");
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [mfaCode, setMfaCode] = useState("");
   const [minted, setMinted] = useState<{ token: string } | null>(null);
   const [copied, setCopied] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -80,15 +82,21 @@ export function PatTokensScreen({
     if (name.trim() === "") return setError(t("pat.create.needName"));
     const scopes = grants();
     if (scopes.length === 0) return setError(t("pat.create.needScope"));
+    if (currentPassword === "") return setError(t("pat.create.needPassword"));
     setBusy(true);
     setError(null);
     const days = EXPIRY_DAYS[expiry];
     const res = await dispatcher.write(PatHandlers.create, {
       name: name.trim(),
       scopes,
+      currentPassword,
       ...(days !== undefined ? { expiresInDays: days } : {}),
+      ...(mfaCode.trim() !== "" ? { mfaCode: mfaCode.trim() } : {}),
     });
     setBusy(false);
+    // Never leave a submitted password/MFA code sitting in state, success or not.
+    setCurrentPassword("");
+    setMfaCode("");
     if (!res.isSuccess) return setError(t("pat.error.generic"));
     setMinted({ token: (res.data as { token: string }).token });
     setCopied(false);
@@ -219,6 +227,29 @@ export function PatTokensScreen({
             disabled={busy}
           />
         </Field>
+
+        <Field id="pat-current-password" label={t("pat.create.currentPassword")} required>
+          <Input
+            kind="password"
+            id="pat-current-password"
+            name="currentPassword"
+            value={currentPassword}
+            onChange={setCurrentPassword}
+            disabled={busy}
+          />
+        </Field>
+
+        <Field id="pat-mfa-code" label={t("pat.create.mfaCode")}>
+          <Input
+            kind="text"
+            id="pat-mfa-code"
+            name="mfaCode"
+            value={mfaCode}
+            onChange={setMfaCode}
+            placeholder={t("pat.create.mfaCodePlaceholder")}
+            disabled={busy}
+          />
+        </Field>
       </Form>
 
       <div className="flex flex-col gap-3">

package/src/tenant/membership-roles.ts

@@ -18,6 +18,13 @@ export function reservedMembershipRoleError(role: string): AccessDeniedError {
   });
 }
 
+export function unassignableMembershipRoleError(role: string): AccessDeniedError {
+  return new AccessDeniedError({
+    message: `role "${role}" cannot be assigned by this inviter`,
+    details: { reason: "unassignable_membership_role", role },
+  });
+}
+
 export function assertAssignableMembershipRoles(roles: readonly string[]): void {
   const forbidden = findForbiddenMembershipRole(roles);
   if (forbidden !== undefined) throw reservedMembershipRoleError(forbidden);

package/src/user-data-rights/__tests__/tenant-model-erasure.integration.test.ts

@@ -34,7 +34,7 @@ import {
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createConfigFeature } from "../../config";
-import { createConfigResolver } from "../../config/resolver";
+import { buildEnvConfigOverrides, createConfigResolver } from "../../config/resolver";
 import { configValueEntity } from "../../config/table";
 import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
 import { createSessionsFeature } from "../../sessions";
@@ -147,6 +147,28 @@ describe("tenant-model config resolution (seam)", () => {
     });
     expect(model).toBe("multi-user");
   });
+
+  test("TENANT_MODEL env var bridges through the real registry to resolveAppTenantModel", async () => {
+    // Mirrors the cascade.integration.test.ts env seam test, but pins it at
+    // the real tenantModel key: registry → buildEnvConfigOverrides →
+    // resolveAppTenantModel, so a key-qualification mismatch between the
+    // feature's `env` declaration and the bridge would fail here, not just
+    // on a stub registry.
+    const keyDef = stack.registry.getConfigKey(TENANT_MODEL_CONFIG_KEY);
+    expect(keyDef).toBeDefined();
+    expect(keyDef?.env).toBe("TENANT_MODEL");
+
+    const overrides = buildEnvConfigOverrides(stack.registry, { TENANT_MODEL: "single-user" });
+    expect(overrides.get(TENANT_MODEL_CONFIG_KEY)).toBe("single-user");
+
+    const model = await resolveAppTenantModel({
+      registry: stack.registry,
+      configResolver: createConfigResolver({ appOverrides: overrides }),
+      db: stack.db,
+      userId: SYSTEM_USER_ID,
+    });
+    expect(model).toBe("single-user");
+  });
 });
 
 describe("forget pipeline honours the effective tenant model", () => {

package/src/user-data-rights/feature.ts

@@ -179,6 +179,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       createSystemConfig("select", {
         default: "multi-user",
         options: ["single-user", "multi-user"],
+        env: "TENANT_MODEL",
       }),
     );