@cosmicdrift/kumiko-bundled-features 0.200.1 → 0.202.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.200.1",
+  "version": "0.202.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.1",
-    "@cosmicdrift/kumiko-framework": "0.200.1",
-    "@cosmicdrift/kumiko-headless": "0.200.1",
-    "@cosmicdrift/kumiko-renderer": "0.200.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.200.1",
-    "@cosmicdrift/kumiko-types": "0.200.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.202.0",
+    "@cosmicdrift/kumiko-framework": "0.202.0",
+    "@cosmicdrift/kumiko-headless": "0.202.0",
+    "@cosmicdrift/kumiko-renderer": "0.202.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.202.0",
+    "@cosmicdrift/kumiko-types": "0.202.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/__tests__/session-auto-revoke.integration.test.ts

@@ -30,6 +30,18 @@ import { currentTotpCode } from "../totp";
 // account — every OTHER live session must be signed out (stolen-session
 // defense), but the session that performed the change must survive.
 
+// sessionChecker's "live" outcome can now carry re-derived roles as
+// `{status: "live", roles: [...]}` instead of the bare string — these tests
+// only care about liveness, not the exact role set, so unwrap the status.
+async function checkerStatus(
+  callbacks: ReturnType<typeof createSessionCallbacks>,
+  sid: string,
+  userId: string,
+): Promise<string> {
+  const result = await callbacks.sessionChecker(sid, userId);
+  return typeof result === "string" ? result : result.status;
+}
+
 let stack: TestStack;
 let sessionCallbacks: ReturnType<typeof createSessionCallbacks>;
 
@@ -94,8 +106,8 @@ describe("session auto-revoke on MFA state changes", () => {
       user,
     );
 
-    expect(await sessionCallbacks.sessionChecker(currentSid, userId)).toBe("live");
-    expect(await sessionCallbacks.sessionChecker(otherSid, userId)).toBe("revoked");
+    expect(await checkerStatus(sessionCallbacks, currentSid, userId)).toBe("live");
+    expect(await checkerStatus(sessionCallbacks, otherSid, userId)).toBe("revoked");
   });
 
   test("disable revokes every OTHER session but keeps the caller's", async () => {
@@ -130,8 +142,8 @@ describe("session auto-revoke on MFA state changes", () => {
       caller,
     );
 
-    expect(await sessionCallbacks.sessionChecker(currentSid, userId)).toBe("live");
-    expect(await sessionCallbacks.sessionChecker(otherSid, userId)).toBe("revoked");
+    expect(await checkerStatus(sessionCallbacks, currentSid, userId)).toBe("live");
+    expect(await checkerStatus(sessionCallbacks, otherSid, userId)).toBe("revoked");
   });
 
   test("a failed disable attempt does NOT revoke any session", async () => {
@@ -163,7 +175,7 @@ describe("session auto-revoke on MFA state changes", () => {
     const err = await stack.http.writeErr(AuthMfaHandlers.disable, { code: "000000" }, caller);
     expectErrorIncludes(err, "invalid_totp_code");
 
-    expect(await sessionCallbacks.sessionChecker(currentSid, userId)).toBe("live");
-    expect(await sessionCallbacks.sessionChecker(otherSid, userId)).toBe("live");
+    expect(await checkerStatus(sessionCallbacks, currentSid, userId)).toBe("live");
+    expect(await checkerStatus(sessionCallbacks, otherSid, userId)).toBe("live");
   });
 });

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/jobs/web/__tests__/job-runs-screen.test.tsx

@@ -49,10 +49,12 @@ const stubNav: NavApi = {
   route: undefined,
   navigate: () => {},
   replace: () => {},
-  hrefFor: (target) =>
-    target.entityId !== undefined
+  hrefFor: (target) => {
+    if (!("screenId" in target)) return "";
+    return target.entityId !== undefined
       ? `/${target.screenId}/${target.entityId}`
-      : `/${target.screenId}`,
+      : `/${target.screenId}`;
+  },
   searchParams: {},
   setSearchParams: () => {},
 };