@cosmicdrift/kumiko-framework 0.160.0 → 0.161.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.160.0",
+  "version": "0.161.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.160.0",
+    "@cosmicdrift/kumiko-types": "0.161.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.160.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.161.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-middleware.ts

@@ -75,7 +75,7 @@ export type AuthMiddlewareOptions = {
   // callers instead of being rejected with 401. The middleware synthesises
   // a SessionUser with id="anonymous" and roles=["anonymous"], scoped to a
   // tenantId resolved through the chain documented on AnonymousAccessConfig.
-  readonly anonymousAccess?: AnonymousAccessConfig;
+  readonly anonymousAccess?: AnonymousAccessResolved;
   // Consulted after tenantId is resolved (JWT/PAT/anonymous). Returns 410
   // when the tenant is in teardown (destroyRequested/destroying/destroyed).
   // cancel-destruction is exempt while status=destroyRequested.
@@ -96,50 +96,23 @@ export type TenantResolver = (c: Context) => Promise<TenantId | null> | TenantId
 // deployments where a caller could otherwise probe arbitrary ids.
 export type TenantExists = (tenantId: TenantId) => Promise<boolean> | boolean;
 
-// Single-tenant shortcut. When set, the server runs in **locked** mode:
-//   - no client-supplied tenant: defaultTenantId is used.
-//   - client supplies a matching tenant (header/cookie/resolver): allowed.
-//   - client supplies a non-matching tenant: 400 tenant_mismatch (the
-//     server is single-tenant; rejecting protects against confused clients
-//     who think they're talking to a different deployment).
-// The framework does NOT verify defaultTenantId against the DB at boot;
-// the caller is responsible (see sample for the pattern).
-// Per-request existence check for header/cookie/resolver-supplied ids.
-// Skipped for the defaultTenantId path (the caller already vetted that
-// value when configuring the server).
-type AnonymousAccessConfigCommon = {
+// App-facing anonymous-access config (#1374). tenantResolver / tenantExists
+// / resolverTrust come from auth-foundation providers (EXT_TENANT_RESOLVER /
+// EXT_TENANT_EXISTENCE), resolved at boot into AnonymousAccessResolved.
+//
+// Single-tenant shortcut: when defaultTenantId is set, the server runs in
+// **locked** mode (client must agree or get tenant_mismatch).
+export type AnonymousAccessConfig = {
   readonly defaultTenantId?: TenantId;
-  readonly tenantExists?: TenantExists;
 };
 
-// Union, not one flat optional-everything type: a tenantResolver without a
-// declared resolverTrust is an ambiguous trust decision the compiler should
-// catch, not a silent runtime default. Set resolverTrust to:
-//   - "authoritative": the resolver is trusted (e.g. it derives the tenant
-//     from the subdomain, which the client cannot forge) and is consulted
-//     FIRST. A client-supplied tenant that disagrees with the resolver's
-//     answer is rejected with 400 tenant_mismatch — it is never used to
-//     override the resolver, and it is never used as a substitute answer
-//     when the resolver returns null either (that would just reopen the
-//     same override via an unrecognised host). Pick this whenever the
-//     resolver derives the tenant from something the caller cannot control
-//     (subdomain, mTLS cert, etc.) — the whole point of such a resolver is
-//     defeated if a client header can still override it.
-//   - "fallback-only": a client-supplied header/cookie wins outright; the
-//     resolver only runs when neither is present. Pick this only when the
-//     resolver is a pure convenience fallback for callers that never send
-//     a tenant of their own (e.g. a bare API host with no per-tenant
-//     subdomains) and its answer carries no more trust than the client's
-//     own claim.
-export type AnonymousAccessConfig =
-  | (AnonymousAccessConfigCommon & {
-      readonly tenantResolver?: undefined;
-      readonly resolverTrust?: undefined;
-    })
-  | (AnonymousAccessConfigCommon & {
-      readonly tenantResolver: TenantResolver;
-      readonly resolverTrust: "authoritative" | "fallback-only";
-    });
+// Runtime config consumed by authMiddleware after boot merges registry
+// providers onto the app-facing AnonymousAccessConfig.
+export type AnonymousAccessResolved = AnonymousAccessConfig & {
+  readonly tenantResolver?: TenantResolver;
+  readonly tenantExists?: TenantExists;
+  readonly resolverTrust?: "authoritative" | "fallback-only";
+};
 
 // Where the candidate tenant came from. Drives the validation policy:
 //   - header / cookie / resolver: untrusted, must pass tenantExists if set.
@@ -409,7 +382,7 @@ async function handleVerifiedBearerUser(
 //      no CSRF vector to defend against).
 async function handleAnonymous(
   c: Context,
-  config: AnonymousAccessConfig,
+  config: AnonymousAccessResolved,
   next: Next,
   resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
@@ -495,7 +468,7 @@ type ResolveError = { error: RejectArgs };
 // clients that think they're talking to a different installation.
 async function resolveTenant(
   c: Context,
-  config: AnonymousAccessConfig,
+  config: AnonymousAccessResolved,
   clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
 ): Promise<ResolvedTenant | ResolveError> {
   if (config.defaultTenantId !== undefined) {

package/src/api/auth-routes.ts

@@ -598,13 +598,17 @@ export function createAuthRoutes(
       const data = result.data as
         | { kind: "auth-session"; session: SessionUser }
         | { kind: "mfa-challenge"; challengeToken: string }
-        | { kind: "mfa-setup-required" };
+        | { kind: "mfa-setup-required"; preauthSetupToken: string };
 
       if (data.kind === "mfa-setup-required") {
         // No session, no challenge — the client must show an
         // enrollment-required message. No rate-limit reset (same reasoning
         // as the mfa-challenge branch below).
-        return c.json({ isSuccess: true, mfaSetupRequired: true });
+        return c.json({
+          isSuccess: true,
+          mfaSetupRequired: true,
+          preauthSetupToken: data.preauthSetupToken,
+        });
       }
 
       if (data.kind === "mfa-challenge") {

package/src/api/index.ts

@@ -2,6 +2,7 @@ export type { SetTenantCookieOptions } from "./anonymous-cookie";
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie";
 export type {
   AnonymousAccessConfig,
+  AnonymousAccessResolved,
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,

package/src/api/server.ts

@@ -47,7 +47,7 @@ import {
 import type { SearchAdapter } from "../search/types";
 import { assertUnreachable, generateId } from "../utils";
 import { PUBLIC_API_PATHS } from "./api-constants";
-import { type AnonymousAccessConfig, authMiddleware, getUser } from "./auth-middleware";
+import { type AnonymousAccessResolved, authMiddleware, getUser } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
@@ -201,9 +201,10 @@ export type ServerOptions = {
   instanceId?: string;
   // Opt-in: serve unauthenticated requests on handlers that allow
   // roles=["anonymous"]. When omitted, every /api/* request still requires
-  // a valid JWT (status quo). See AnonymousAccessConfig for the resolution
-  // chain (header → cookie → resolver → defaultTenantId).
-  anonymousAccess?: AnonymousAccessConfig;
+  // a valid JWT (status quo). App-facing config is AnonymousAccessConfig
+  // (defaultTenantId only); run{Prod,Dev}App merge auth-foundation tenant
+  // providers into AnonymousAccessResolved before calling buildServer.
+  anonymousAccess?: AnonymousAccessResolved;
 };
 
 export type KumikoServer = {

package/src/stack/request-helper.ts

@@ -1,4 +1,5 @@
 import type { Hono } from "hono";
+import type { SessionCreator } from "../api/auth-routes";
 import type { JwtHelper } from "../api/jwt";
 import type { SessionUser } from "../engine/types";
 
@@ -98,9 +99,25 @@ export type RequestHelper = {
   ) => Promise<Response>;
 };
 
-export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
+export type RequestHelperOptions = {
+  // When sessionChecker is wired (sessions feature), JWTs without jti are
+  // rejected as no_sid. Seed/test helpers that only jwt.sign(user) need a
+  // live sid — create one via the same sessionCreator login uses (#1372).
+  readonly sessionCreator?: SessionCreator;
+};
+
+export function createRequestHelper(
+  app: Hono,
+  jwt: JwtHelper,
+  options: RequestHelperOptions = {},
+): RequestHelper {
   async function authHeader(user: SessionUser): Promise<Record<string, string>> {
-    const token = await jwt.sign(user);
+    let forJwt = user;
+    if (options.sessionCreator && !user.sid) {
+      const sid = await options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
+      forJwt = { ...user, sid };
+    }
+    const token = await jwt.sign(forJwt);
     return { Authorization: `Bearer ${token}` };
   }
 

package/src/stack/test-stack.ts

@@ -124,6 +124,16 @@ export type TestStackOptions = {
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").ServerOptions["anonymousAccess"]);
+  /** Optional post-factory enricher (e.g. merge auth-foundation tenant
+   *  providers). Keeps framework free of a bundled-features dependency. */
+  enrichAnonymousAccess?: (
+    base: import("../api/server").ServerOptions["anonymousAccess"] | undefined,
+    deps: {
+      registry: Registry;
+      // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
+      db: any;
+    },
+  ) => Promise<import("../api/server").ServerOptions["anonymousAccess"] | undefined>;
   /** Opt-in JobRunner wired into ctx.jobRunner and merged into
    *  dispatcherOptions so event-triggered jobs enqueue on commit — mirrors
    *  the prod entrypoint's `buildJobRunnerWithHook`. Unlike prod (which
@@ -382,19 +392,24 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
         : {}),
       ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
       ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
-      ...(options.anonymousAccess
-        ? {
-            anonymousAccess:
-              typeof options.anonymousAccess === "function"
-                ? options.anonymousAccess({
-                    registry,
-                    db: testDb.db,
-                    sseBroker,
-                    redis: testRedis.redis,
-                  })
-                : options.anonymousAccess,
-          }
-        : {}),
+      ...(await (async () => {
+        const baseAnon =
+          typeof options.anonymousAccess === "function"
+            ? options.anonymousAccess({
+                registry,
+                db: testDb.db,
+                sseBroker,
+                redis: testRedis.redis,
+              })
+            : options.anonymousAccess;
+        const resolvedAnon = options.enrichAnonymousAccess
+          ? await options.enrichAnonymousAccess(baseAnon, {
+              registry,
+              db: testDb.db,
+            })
+          : baseAnon;
+        return resolvedAnon ? { anonymousAccess: resolvedAnon } : {};
+      })()),
     });
 
     const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
@@ -406,7 +421,11 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // timer loop call start() again (idempotent) after setup.
     if (eventDispatcher) await eventDispatcher.ensureRegistered();
 
-    const http = createRequestHelper(server.app, server.jwt);
+    const http = createRequestHelper(server.app, server.jwt, {
+      ...(options.authConfig?.sessionCreator !== undefined && {
+        sessionCreator: options.authConfig.sessionCreator,
+      }),
+    });
 
     return {
       app: server.app,