@cosmicdrift/kumiko-bundled-features 0.109.0 → 0.110.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.109.0",
+  "version": "0.110.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>",
@@ -95,11 +95,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.109.0",
-    "@cosmicdrift/kumiko-framework": "0.109.0",
-    "@cosmicdrift/kumiko-headless": "0.109.0",
-    "@cosmicdrift/kumiko-renderer": "0.109.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.109.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.110.0",
+    "@cosmicdrift/kumiko-framework": "0.110.0",
+    "@cosmicdrift/kumiko-headless": "0.110.0",
+    "@cosmicdrift/kumiko-renderer": "0.110.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.110.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/auth-email-password/__tests__/feature-options.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { MIN_HMAC_SECRET_LENGTH } from "../constants";
+import { createAuthEmailPasswordFeature } from "../feature";
+
+// A short HMAC secret makes reset/verify tokens forgeable (account takeover),
+// so the factory must fail fast — same bar as the ≥32-char JWT_SECRET check.
+
+const okSecret = "x".repeat(MIN_HMAC_SECRET_LENGTH);
+const shortSecret = "x".repeat(MIN_HMAC_SECRET_LENGTH - 1);
+const appUrl = "https://app.example.com/flow";
+
+describe("createAuthEmailPasswordFeature hmacSecret validation", () => {
+  test("rejects a short passwordReset.hmacSecret", () => {
+    expect(() =>
+      createAuthEmailPasswordFeature({ passwordReset: { hmacSecret: shortSecret, appUrl } }),
+    ).toThrow(/passwordReset\.hmacSecret must be/);
+  });
+
+  test("rejects a short emailVerification.hmacSecret", () => {
+    expect(() =>
+      createAuthEmailPasswordFeature({ emailVerification: { hmacSecret: shortSecret, appUrl } }),
+    ).toThrow(/emailVerification\.hmacSecret must be/);
+  });
+
+  test("accepts secrets at the minimum length", () => {
+    expect(() =>
+      createAuthEmailPasswordFeature({
+        passwordReset: { hmacSecret: okSecret, appUrl },
+        emailVerification: { hmacSecret: okSecret, appUrl },
+      }),
+    ).not.toThrow();
+  });
+});

package/src/auth-email-password/constants.ts

@@ -6,6 +6,10 @@
 // der server-side Zugriff (handlers, dispatcher) erhalten.
 export const AUTH_EMAIL_PASSWORD_FEATURE = "auth-email-password" as const;
 
+// Minimum length for reset/verify hmacSecret — mirrors the ≥32-char
+// JWT_SECRET env check (HMAC-SHA256 key material).
+export const MIN_HMAC_SECRET_LENGTH = 32;
+
 // Qualified handler names. Non-CRUD handlers, no entity prefix.
 export const AuthHandlers = {
   login: "auth-email-password:write:login",

package/src/auth-email-password/feature.ts

@@ -1,5 +1,6 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { MIN_HMAC_SECRET_LENGTH } from "./constants";
 import type { AuthMailLocale } from "./email-templates";
 import { changePasswordWrite } from "./handlers/change-password.write";
 import { createInviteAcceptHandler } from "./handlers/invite-accept.write";
@@ -122,14 +123,17 @@ export type AuthEmailPasswordOptions = {
 export function createAuthEmailPasswordFeature(
   opts: AuthEmailPasswordOptions = {},
 ): FeatureDefinition {
-  if (opts.passwordReset && !opts.passwordReset.hmacSecret) {
+  // ≥32 chars, symmetric to the JWT_SECRET env check: a short HMAC secret
+  // makes reset/verify tokens forgeable — that's account takeover, so the
+  // factory fails fast instead of trusting the caller.
+  if (opts.passwordReset && opts.passwordReset.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
     throw new Error(
-      "[auth-email-password] passwordReset.hmacSecret must be non-empty when passwordReset is configured",
+      `[auth-email-password] passwordReset.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
     );
   }
-  if (opts.emailVerification && !opts.emailVerification.hmacSecret) {
+  if (opts.emailVerification && opts.emailVerification.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
     throw new Error(
-      "[auth-email-password] emailVerification.hmacSecret must be non-empty when emailVerification is configured",
+      `[auth-email-password] emailVerification.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
     );
   }
 

package/src/sessions/__tests__/auto-revoke-binding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { AppContext, SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { bindAutoRevokeFromFeature, createSessionsFeature } from "../feature";
+
+// The postSave hook is registered unconditionally; the revoker arrives either
+// as the explicit constructor option or late-bound by run{Prod,Dev}App via
+// bindAutoRevokeOnPasswordChange. These tests pin the binding + precedence
+// semantics at the hook level — the full DB sweep is covered by
+// password-auto-revoke.integration.test.ts.
+
+const passwordChange: SaveContext = {
+  kind: "save",
+  id: "user-1",
+  data: {},
+  changes: { passwordHash: "new-hash" },
+  previous: {},
+  isNew: false,
+};
+
+// @cast-boundary test fixture — the hook never touches AppContext
+const appContext = {} as unknown as AppContext;
+
+function userPostSaveHook(feature: ReturnType<typeof createSessionsFeature>) {
+  const hook = feature.entityHooks?.postSave?.["user"]?.[0];
+  if (!hook) throw new Error("sessions feature did not register the user postSave hook");
+  return (ctx: SaveContext) => hook.fn(ctx, appContext);
+}
+
+describe("sessions auto-revoke binding", () => {
+  test("late-bound revoker fires on password change", async () => {
+    const revoker = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature();
+
+    const bind = bindAutoRevokeFromFeature(feature);
+    expect(bind).toBeDefined();
+    bind?.(revoker);
+
+    await userPostSaveHook(feature)(passwordChange);
+    expect(revoker).toHaveBeenCalledTimes(1);
+    expect(revoker).toHaveBeenCalledWith("user-1");
+  });
+
+  test("unbound hook is a silent no-op", async () => {
+    const feature = createSessionsFeature();
+    // must resolve without throwing — stateless-JWT deployments have no revoker
+    const result = await userPostSaveHook(feature)(passwordChange);
+    expect(result).toBeUndefined();
+  });
+
+  test("skips isNew and non-passwordHash changes", async () => {
+    const revoker = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature();
+    bindAutoRevokeFromFeature(feature)?.(revoker);
+
+    await userPostSaveHook(feature)({ ...passwordChange, isNew: true });
+    await userPostSaveHook(feature)({ ...passwordChange, changes: { displayName: "x" } });
+    expect(revoker).not.toHaveBeenCalled();
+  });
+
+  test("explicit constructor option wins over the runtime binding", async () => {
+    const explicit = mock(async (_userId: string) => 1);
+    const lateBound = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature({ autoRevokeOnPasswordChange: explicit });
+
+    bindAutoRevokeFromFeature(feature)?.(lateBound);
+    await userPostSaveHook(feature)(passwordChange);
+
+    expect(explicit).toHaveBeenCalledWith("user-1");
+    expect(lateBound).not.toHaveBeenCalled();
+  });
+});

package/src/sessions/feature.ts

@@ -10,19 +10,46 @@ import { userSessionEntity } from "./schema/user-session";
 import type { SessionMassRevoker } from "./session-callbacks";
 
 export type SessionsFeatureOptions = {
-  // When wired, a successful update on the `user` entity that changes the
-  // `passwordHash` column triggers a mass-revoke of every live session for
-  // that user. Industry-standard "password-change signs you out everywhere"
-  // flow, including the session that did the change itself — the client has
+  // A successful update on the `user` entity that changes the `passwordHash`
+  // column triggers a mass-revoke of every live session for that user.
+  // Industry-standard "password-change signs you out everywhere" flow,
+  // including the session that did the change itself — the client has
   // to re-login after a password change.
   //
   // Runs as an afterCommit postSave hook: the password-change commits first,
   // then the sessions are revoked. Best-effort — if the mass-revoker throws,
   // the password change is NOT rolled back (a password change with a stale
   // session still wins over a user-visible error on the change itself).
+  //
+  // Default: run{Prod,Dev}App bind their own sessionMassRevoker via
+  // `bindAutoRevokeOnPasswordChange` (secure-by-default). Set this option
+  // only to supply a custom revoker — an explicit value wins over the
+  // runtime binding.
   readonly autoRevokeOnPasswordChange?: SessionMassRevoker;
 };
 
+export type BindAutoRevokeOnPasswordChange = (revoker: SessionMassRevoker) => void;
+
+// Reads the late-bind setter off a mounted sessions feature's exports.
+// run{Prod,Dev}App call it once the DB connection is concrete — the feature
+// itself is constructed in app run-config long before a db exists, so the
+// revoker can't be a constructor argument.
+export function bindAutoRevokeFromFeature(
+  feature: FeatureDefinition,
+): BindAutoRevokeOnPasswordChange | 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 BindAutoRevokeOnPasswordChange;
+    }
+  }
+  return undefined;
+}
+
 // The sessions feature registers the read_user_sessions table (as an
 // unmanaged direct-write store, NOT an r.entity — see below) and the three
 // user-facing handlers (mine/revoke/revoke-all-others). It intentionally does NOT
@@ -93,20 +120,26 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     // "the handler didn't touch this column", which is exactly the signal
     // we want to skip on. Works for both direct user:update calls and any
     // other handler that happens to write the column.
-    const autoRevoke = options?.autoRevokeOnPasswordChange;
-    if (autoRevoke) {
-      r.entityHook("postSave", "user", async (ctx) => {
-        // skip: brand-new user, no sessions can possibly exist yet. The
-        // initial passwordHash on a user:create would trip the second guard
-        // otherwise — every registration would do a mass-revoke roundtrip
-        // for a user who literally has no rows in user_sessions.
-        if (ctx.isNew) return;
-        // skip: handler didn't touch passwordHash, nothing to revoke
-        if (ctx.changes["passwordHash"] === undefined) return;
-        await autoRevoke(String(ctx.id));
-      });
-    }
+    let autoRevoke = options?.autoRevokeOnPasswordChange;
+    r.entityHook("postSave", "user", async (ctx) => {
+      // skip: nothing bound — stateless-JWT deployments without a runtime
+      // that calls bindAutoRevokeOnPasswordChange keep the old behavior.
+      if (!autoRevoke) return;
+      // skip: brand-new user, no sessions can possibly exist yet. The
+      // initial passwordHash on a user:create would trip the second guard
+      // otherwise — every registration would do a mass-revoke roundtrip
+      // for a user who literally has no rows in user_sessions.
+      if (ctx.isNew) return;
+      // skip: handler didn't touch passwordHash, nothing to revoke
+      if (ctx.changes["passwordHash"] === undefined) return;
+      await autoRevoke(String(ctx.id));
+    });
+
+    const bindAutoRevokeOnPasswordChange: BindAutoRevokeOnPasswordChange = (revoker) => {
+      // explicit constructor option wins over the runtime binding
+      autoRevoke ??= revoker;
+    };
 
-    return { handlers, queries };
+    return { handlers, queries, bindAutoRevokeOnPasswordChange };
   });
 }

package/src/sessions/index.ts

@@ -6,8 +6,8 @@ export {
   SessionHandlers,
   SessionQueries,
 } from "./constants";
-export type { SessionsFeatureOptions } from "./feature";
-export { createSessionsFeature } from "./feature";
+export type { BindAutoRevokeOnPasswordChange, SessionsFeatureOptions } from "./feature";
+export { bindAutoRevokeFromFeature, createSessionsFeature } from "./feature";
 export { userSessionEntity, userSessionTable } from "./schema/user-session";
 export type {
   SessionCallbacks,

package/src/user/__tests__/user.integration.test.ts

@@ -109,6 +109,32 @@ describe("scenario 2: field-level read access", () => {
   });
 });
 
+// --- find-for-auth is system-only: it returns the raw row incl. passwordHash,
+// and every query handler is reachable via POST /api/query — so even a
+// SystemAdmin (assignable app role) must be denied over HTTP. ---
+
+describe("scenario 2b: find-for-auth is system-only", () => {
+  test("SystemAdmin over HTTP is denied — passwordHash must not leak", async () => {
+    await seedUser({
+      email: "auth-lookup@example.com",
+      displayName: "AuthLookup",
+      passwordHash: "must-never-leave-the-server",
+    });
+
+    const res = await stack.http.queryWithHeaders(
+      UserQueries.findForAuth,
+      { email: "auth-lookup@example.com" },
+      systemAdmin,
+      {},
+    );
+
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    const body = await res.text();
+    expect(body).toContain("access_denied");
+    expect(body).not.toContain("must-never-leave-the-server");
+  });
+});
+
 // --- Scenario 3: user edits own profile, email/passwordHash are system-locked ---
 
 describe("scenario 3: self-update + field-level write access", () => {

package/src/user/handlers/find-for-auth.query.ts

@@ -7,10 +7,12 @@ import { userTable } from "../schema/user";
 // by email OR id (exactly one, enforced by the schema). Used by the auth
 // features via ctx.queryAs(systemUser, ...).
 //
-// Field-level read rules allow passwordHash for the "privileged" role set,
-// so system callers see everything; any other caller is filtered even if
-// they somehow reach this handler. Access is also restricted to privileged
-// — regular users or tenant admins cannot call this at all.
+// Access is system-only, NOT access.privileged: every query handler is
+// reachable via POST /api/query, and "SystemAdmin" is an assignable app
+// role — privileged would hand any SystemAdmin the raw passwordHash over
+// HTTP. The "system" role can't be minted into a session (only
+// createSystemUser() carries it), so system-only keeps this handler
+// internal to ctx.queryAs(systemUser, ...) callers.
 export const findForAuthQuery = defineQueryHandler({
   name: "user:find-for-auth",
   schema: z
@@ -24,7 +26,7 @@ export const findForAuthQuery = defineQueryHandler({
       (v) => (v.email !== undefined) !== (v.id !== undefined),
       { message: "exactly one of email or id must be set" },
     ),
-  access: { roles: access.privileged },
+  access: { roles: access.system },
   handler: async (query, ctx) => {
     const where =
       query.payload.email !== undefined