@cosmicdrift/kumiko-framework 0.147.0 → 0.147.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.147.0",
+  "version": "0.147.2",
   "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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.147.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.147.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/anonymous-access.integration.test.ts

@@ -8,6 +8,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
+import type { AnonymousAccessConfig } from "../api/auth-middleware";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { asRawClient, selectMany } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
@@ -307,6 +308,165 @@ describe("anonymous access — header-supplied tenant", () => {
   });
 });
 
+describe("anonymous access — resolverTrust: authoritative", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    // Simulates a subdomain resolver: TENANT_ID is "known" (the resolver
+    // recognises it), everything else is an unrecognised host (null).
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        tenantResolver: () => TENANT_ID,
+        resolverTrust: "authoritative",
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("no client tenant → resolver wins", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("X-Tenant header agreeing with the resolver → accepted", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": TENANT_ID },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("X-Tenant header disagreeing with the resolver → 400 tenant_mismatch, resolver's tenant is NOT overridden", async () => {
+    // The core #51 regression: a header claiming a different (real, active)
+    // tenant than the one the resolver derived must never win — that would
+    // let a guest on tenantA's subdomain write into tenantB by forging a
+    // header. Reject, don't silently prefer either side.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": OTHER_TENANT_ID },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_mismatch");
+  });
+});
+
+describe("anonymous access — resolverTrust: authoritative, resolver returns null", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    // Resolver never recognises the host (e.g. an unmapped/unknown
+    // subdomain) — always returns null.
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        tenantResolver: () => null,
+        resolverTrust: "authoritative",
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("resolver null + X-Tenant header present → 400 tenant_required, header does NOT pick the tenant", async () => {
+    // If this fell back to the client header, an unrecognised-host request
+    // could still choose its own tenant via X-Tenant — the same override
+    // "authoritative" exists to prevent, just reached via "unknown host"
+    // instead of "known host, disagreeing header".
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": TENANT_ID },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_required");
+  });
+
+  test("resolver null + no client tenant → 400 tenant_required", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_required");
+  });
+});
+
+describe("anonymous access — resolverTrust: fallback-only", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        tenantResolver: () => TENANT_ID,
+        resolverTrust: "fallback-only",
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("X-Tenant header disagreeing with the resolver → header wins (documented convenience-fallback behaviour)", async () => {
+    // Opposite of "authoritative": a client tenant that disagrees with the
+    // resolver is accepted, not rejected — this mode is for resolvers that
+    // carry no more trust than the client's own claim.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": OTHER_TENANT_ID },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("no client tenant → resolver runs as fallback", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("anonymous access — tenantResolver without resolverTrust", () => {
+  test("authMiddleware throws at boot, not silently at request time", async () => {
+    await expect(
+      setupTestStack({
+        features: [shopFeature],
+        // Simulates a caller that bypasses the compiler (JS consumer, an
+        // `as any` cast) — the discriminated union stops well-typed callers,
+        // this proves the runtime guard behind it also fires.
+        anonymousAccess: {
+          tenantResolver: () => TENANT_ID,
+          resolverTrust: undefined,
+        } as unknown as AnonymousAccessConfig,
+      }),
+    ).rejects.toThrow(/resolverTrust/);
+  });
+});
+
 describe("anonymous access — disabled by default", () => {
   let stack: TestStack;
 

package/src/api/__tests__/auth-routes-mfa-verify.test.ts

@@ -0,0 +1,201 @@
+// auth-routes /auth/mfa/verify — framework-level route mechanics only:
+// body validation, dispatch-and-mint-on-success, its OWN rate limiter
+// (mfaVerifyRateLimit, distinct from loginRateLimit), and error-status
+// mapping. Uses a stub Dispatcher with a fake mfaVerifyHandler — the REAL
+// challenge-token verification / TOTP check / brute-force cap lives in
+// auth-mfa's own handler and is covered there, not here.
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import { InternalError, UnprocessableError } from "../../errors";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
+import { TestUsers } from "../../stack";
+import { getSetCookies } from "../../testing/http-cookies";
+import { PUBLIC_API_PATHS } from "../api-constants";
+import { AUTH_COOKIE_NAME, authMiddleware, CSRF_COOKIE_NAME } from "../auth-middleware";
+import {
+  type AuthRoutesConfig,
+  createAuthRoutes,
+  createInMemoryLoginRateLimiter,
+} from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-routes-mfa-verify-test-secret-min-32-characters";
+const MFA_VERIFY_QN = "auth-mfa:write:verify";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = {
+        isSuccess: true,
+        data: { kind: "mfa-verify-success", session: TestUsers.user },
+      };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      const ok: BatchResult = { isSuccess: true, results: [] };
+      return ok;
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    mfaVerifyHandler: MFA_VERIFY_QN,
+    mfaVerifyRateLimit: null,
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app };
+}
+
+function verifyRequest(body: unknown): Request {
+  return new Request("http://localhost/api/auth/mfa/verify", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("POST /auth/mfa/verify", () => {
+  test("is public — reachable without a JWT", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/verify")).toBe(true);
+  });
+
+  test("not mounted when mfaVerifyHandler is unset", async () => {
+    const { app } = await buildApp({ mfaVerifyHandler: undefined });
+    const res = await app.request(verifyRequest({ challengeToken: "t", code: "123456" }));
+    expect(res.status).toBe(404);
+  });
+
+  test("400 on a malformed body, before dispatch or rate-limit", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "mfa-verify-success", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(verifyRequest({ challengeToken: "t" }));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("invalid_body");
+    expect(dispatched).toBe(false);
+  });
+
+  test("on success: dispatches to mfaVerifyHandler, mints a JWT + cookies", async () => {
+    let receivedBody: unknown;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(MFA_VERIFY_QN);
+        receivedBody = payload;
+        return { isSuccess: true, data: { kind: "mfa-verify-success", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      verifyRequest({ challengeToken: "opaque-challenge-token", code: "123456" }),
+    );
+    expect(res.status).toBe(200);
+    expect(receivedBody).toEqual({
+      challengeToken: "opaque-challenge-token",
+      code: "123456",
+    });
+
+    const body = (await res.json()) as { isSuccess: boolean; token: string };
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.token.length).toBeGreaterThan(20);
+
+    const cookies = getSetCookies(res);
+    expect(cookies.get(AUTH_COOKIE_NAME)).toBeDefined();
+    expect(cookies.get(CSRF_COOKIE_NAME)).toBeDefined();
+  });
+
+  test("a handler failure maps through mfaVerifyErrorStatusMap", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_totp_code", {
+            details: { reason: "invalid_totp_code" },
+          }),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaVerifyErrorStatusMap: { invalid_totp_code: 422 } },
+      dispatcher,
+    );
+    const res = await app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(false);
+  });
+
+  test("an unmapped handler failure falls back to the error's own httpStatus", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return { isSuccess: false, error: new InternalError({ message: "boom" }) };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect(res.status).toBe(500);
+  });
+
+  test("mfaVerifyRateLimit is independent from loginRateLimit — 429 after its own cap", async () => {
+    // A failing dispatcher — reset() only fires on success, so failed
+    // attempts accumulate against the cap instead of clearing it each time.
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_totp_code"),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaVerifyRateLimit: createInMemoryLoginRateLimiter(2, 60_000) },
+      dispatcher,
+    );
+    const attempt = () => app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect((await attempt()).status).toBe(422);
+    expect((await attempt()).status).toBe(422);
+    const third = await attempt();
+    expect(third.status).toBe(429);
+    const body = (await third.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("rate_limited");
+  });
+
+  test("a successful verify resets the rate-limit counter for that IP", async () => {
+    const { app } = await buildApp({
+      mfaVerifyRateLimit: createInMemoryLoginRateLimiter(1, 60_000),
+    });
+    const attempt = () => app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect((await attempt()).status).toBe(200);
+    // Without a reset-on-success this would be 429 (cap=1 already spent).
+    expect((await attempt()).status).toBe(200);
+  });
+});

package/src/api/api-constants.ts

@@ -12,6 +12,7 @@ export const Routes = {
   sse: "/sse",
   auth: "/auth",
   authLogin: "/auth/login",
+  authMfaVerify: "/auth/mfa/verify",
   authLogout: "/auth/logout",
   authTenants: "/auth/tenants",
   authSwitchTenant: "/auth/switch-tenant",
@@ -36,6 +37,7 @@ export const Routes = {
 // The auth middleware skips these paths.
 export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authLogin}`,
+  `/api${Routes.authMfaVerify}`,
   `/api${Routes.authRequestPasswordReset}`,
   `/api${Routes.authResetPassword}`,
   `/api${Routes.authRequestEmailVerification}`,

package/src/api/auth-middleware.ts

@@ -98,25 +98,51 @@ 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;
 
-export type AnonymousAccessConfig = {
-  // Custom resolver (e.g. subdomain parser). Consulted only when neither
-  // the X-Tenant header nor the kumiko_tenant cookie are present.
-  readonly tenantResolver?: TenantResolver;
-  // 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).
+// 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 = {
   readonly defaultTenantId?: TenantId;
-  // 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).
   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";
+    });
+
 // Where the candidate tenant came from. Drives the validation policy:
 //   - header / cookie / resolver: untrusted, must pass tenantExists if set.
 //   - default: trusted (configured at boot), no per-request check.
@@ -204,6 +230,17 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     resolveTenantLifecycleStatus,
   } = options;
 
+  // Fail loud at boot, not silently at request time: a tenantResolver
+  // without a declared resolverTrust is an ambiguous trust decision no
+  // sane default can make on the app's behalf (see AnonymousAccessConfig).
+  if (anonymousAccess?.tenantResolver && anonymousAccess.resolverTrust === undefined) {
+    throw new Error(
+      "authMiddleware: anonymousAccess.tenantResolver is set without resolverTrust — " +
+        'declare "authoritative" (resolver wins over client header/cookie) or ' +
+        '"fallback-only" (client wins, resolver is a last resort).',
+    );
+  }
+
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
     if ("error" in extracted) {
@@ -473,34 +510,89 @@ async function resolveTenant(
   clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
 ): Promise<ResolvedTenant | ResolveError> {
   if (config.defaultTenantId !== undefined) {
-    if (clientTenant && clientTenant.id !== config.defaultTenantId) {
+    return resolveAgainstDefault(config.defaultTenantId, clientTenant);
+  }
+  if (config.tenantResolver && config.resolverTrust === "authoritative") {
+    return await resolveWithAuthoritativeResolver(c, config.tenantResolver, clientTenant);
+  }
+  return await resolveWithClientPrecedence(c, config.tenantResolver, clientTenant);
+}
+
+// Locked single-tenant mode: the client either agrees with the default or
+// gets tenant_mismatch — defending the deployment from confused clients
+// that think they're talking to a different installation.
+function resolveAgainstDefault(
+  defaultTenantId: TenantId,
+  clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
+): ResolvedTenant | ResolveError {
+  if (clientTenant && clientTenant.id !== defaultTenantId) {
+    return {
+      error: {
+        code: "tenant_mismatch",
+        status: 400,
+        message: `${clientTenant.source} tenant disagrees with server default`,
+        i18nKey: "auth.errors.tenantMismatch",
+        details: { clientTenantId: clientTenant.id, defaultTenantId },
+      },
+    };
+  }
+  return { tenantId: defaultTenantId, source: "default" };
+}
+
+// resolverTrust: "authoritative" — the resolver is trusted over the client.
+// A client-supplied tenant that disagrees is rejected, never used to
+// override the resolver's answer. Falls back to the client tenant only
+// when the resolver itself has no opinion (unrecognised host).
+async function resolveWithAuthoritativeResolver(
+  c: Context,
+  tenantResolver: TenantResolver,
+  clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
+): Promise<ResolvedTenant | ResolveError> {
+  const resolved = await tenantResolver(c);
+  if (resolved !== null && resolved !== undefined) {
+    if (clientTenant && clientTenant.id !== resolved) {
       return {
         error: {
           code: "tenant_mismatch",
           status: 400,
-          message: `${clientTenant.source} tenant disagrees with server default`,
+          message: `${clientTenant.source} tenant disagrees with resolved tenant`,
           i18nKey: "auth.errors.tenantMismatch",
-          details: {
-            clientTenantId: clientTenant.id,
-            defaultTenantId: config.defaultTenantId,
-          },
+          details: { clientTenantId: clientTenant.id, resolvedTenantId: resolved },
         },
       };
     }
-    return { tenantId: config.defaultTenantId, source: "default" };
+    return { tenantId: resolved, source: "resolver" };
   }
+  // Resolver had no opinion (unrecognised host) — do NOT fall back to the
+  // client-supplied tenant here. That would let an unrecognised-host
+  // request pick its own tenant via X-Tenant, the exact override this mode
+  // exists to prevent; it's just reached through "unknown host" instead of
+  // "known host, disagreeing header". Authoritative means the resolver's
+  // silence is final, not a delegation back to the client.
+  return tenantRequiredError();
+}
 
+// resolverTrust: "fallback-only" (or no resolver at all) — client tenant
+// wins outright; the resolver only runs as a last resort when neither
+// header nor cookie supplied a value.
+async function resolveWithClientPrecedence(
+  c: Context,
+  tenantResolver: TenantResolver | undefined,
+  clientTenant: { id: TenantId; source: "header" | "cookie" } | null,
+): Promise<ResolvedTenant | ResolveError> {
   if (clientTenant) {
     return { tenantId: clientTenant.id, source: clientTenant.source };
   }
-
-  if (config.tenantResolver) {
-    const resolved = await config.tenantResolver(c);
+  if (tenantResolver) {
+    const resolved = await tenantResolver(c);
     if (resolved !== null && resolved !== undefined) {
       return { tenantId: resolved, source: "resolver" };
     }
   }
+  return tenantRequiredError();
+}
 
+function tenantRequiredError(): ResolveError {
   return {
     error: {
       code: "tenant_required",

package/src/api/auth-routes.ts

@@ -97,6 +97,16 @@ const LoginBody = z.object({
   password: z.string(),
 });
 
+// Body schema for POST /auth/mfa/verify. challengeToken is opaque to the
+// framework — it's minted and verified entirely by the mfaVerifyHandler
+// (auth-mfa owns the token format, TOTP/recovery-code check, and the
+// brute-force cap). code covers both 6-digit TOTP and XXXX-XXXX recovery
+// codes (9 chars incl. the dash).
+const MfaVerifyBody = z.object({
+  challengeToken: z.string().min(1),
+  code: z.string().min(6).max(9),
+});
+
 const ResetPasswordBody = z.object({
   token: z.string().min(1),
   newPassword: z.string().min(8).max(200),
@@ -217,6 +227,28 @@ export type AuthRoutesConfig = {
   // Rate-limit for POST /auth/login. Defaults to in-memory 10/5min per
   // (ip + email) bucket. Pass `null` to disable (tests, trusted networks).
   loginRateLimit?: LoginRateLimiter | null;
+  // Optional: qualified write handler completing a two-step (password +
+  // TOTP/recovery-code) login. When set, POST /auth/mfa/verify dispatches
+  // { challengeToken, code } to this handler with a guest identity. On
+  // success the handler must return { kind: "mfa-verify-success", session:
+  // SessionUser } and the route mints a JWT exactly like /auth/login.
+  // Everything MFA-specific (challenge-token format, TOTP/recovery check,
+  // the per-account brute-force cap) is owned by the handler — the
+  // framework stays as agnostic about it as it is about password hashing.
+  mfaVerifyHandler?: string;
+  // Maps mfaVerifyHandler error codes to HTTP status codes, same pattern as
+  // loginErrorStatusMap. Unknown errors default to the error's own httpStatus.
+  mfaVerifyErrorStatusMap?: Readonly<Record<string, number>>;
+  // Rate-limit for POST /auth/mfa/verify, keyed by client IP. Defaults to
+  // in-memory 10/5min. Pass `null` to disable. This is DELIBERATELY separate
+  // from loginRateLimit: unlike /auth/login (a dispatcher write-handler
+  // route that could inherit a handler-level rateLimit), this is a
+  // framework route with no handler.rateLimit to fall back on — and it's
+  // also separate from any per-account brute-force cap the mfaVerifyHandler
+  // enforces itself (see its own doc comment) — IP-scoped abuse protection
+  // and per-account guessing protection are different threats, neither
+  // substitutes for the other.
+  mfaVerifyRateLimit?: LoginRateLimiter | null;
   // Session-lifecycle callbacks. When both are wired the JWT carries a `jti`
   // (sid) and the server can revoke individual sessions (logout, compromise,
   // password-change). When unwired the framework issues plain stateless JWTs.
@@ -511,8 +543,32 @@ export function createAuthRoutes(
         return c.json({ isSuccess: false, error: result.error }, status);
       }
 
-      // @cast-boundary engine-payload — generic dispatcher.write result for auth-session handler
-      const data = result.data as { kind: "auth-session"; session: SessionUser };
+      // @cast-boundary engine-payload — generic dispatcher.write result for
+      // login. Three possible shapes: a straight session, an MFA challenge
+      // when the loginHandler is wired with a second-factor gate, or a hard
+      // block when enforcement policy demands MFA but the user never
+      // enrolled (see auth-mfa's config.ts for why this has no in-band
+      // recovery yet).
+      const data = result.data as
+        | { kind: "auth-session"; session: SessionUser }
+        | { kind: "mfa-challenge"; challengeToken: string }
+        | { kind: "mfa-setup-required" };
+
+      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 });
+      }
+
+      if (data.kind === "mfa-challenge") {
+        // No session minted yet — no cookies, no token. The client must
+        // complete /auth/mfa/verify with this token before it gets either.
+        // Rate-limit counter is NOT reset here: a "correct password, wrong/
+        // no TOTP yet" outcome hasn't proven the caller owns the account any
+        // more than a wrong password did.
+        return c.json({ isSuccess: true, mfaRequired: true, challengeToken: data.challengeToken });
+      }
 
       // Session creation (optional) + JWT sign + cookies — see
       // mintSessionAndRespond. Creating the session BEFORE signing the JWT
@@ -533,6 +589,76 @@ export function createAuthRoutes(
     });
   }
 
+  // POST /auth/mfa/verify — completes a two-step login. Mirrors /auth/login
+  // structurally (public, GUEST_USER dispatch, mintSessionAndRespond on
+  // success) but with its OWN rate limiter (mfaVerifyRateLimit) — this route
+  // never goes through a dispatcher write-handler's own rateLimit config,
+  // so without this it would have NO rate limiting at all. Per-account
+  // brute-force protection (capping wrong-code guesses against one
+  // still-valid challenge token) is a separate mechanism the handler itself
+  // owns — see AuthRoutesConfig.mfaVerifyHandler's doc comment.
+  if (config.mfaVerifyHandler) {
+    const mfaVerifyQn = config.mfaVerifyHandler;
+    const statusMap = config.mfaVerifyErrorStatusMap ?? {};
+    const rateLimiter =
+      config.mfaVerifyRateLimit === null
+        ? null
+        : (config.mfaVerifyRateLimit ?? createInMemoryLoginRateLimiter());
+
+    api.post(Routes.authMfaVerify, async (c) => {
+      const raw = await c.req.json().catch(() => null);
+      const parsed = MfaVerifyBody.safeParse(raw);
+      if (!parsed.success) {
+        return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+      }
+      const body = parsed.data;
+
+      const clientIp =
+        c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+        c.req.header("x-real-ip") ??
+        "unknown";
+
+      if (rateLimiter) {
+        const allowed = await rateLimiter.check(clientIp);
+        if (!allowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+      }
+
+      const result = await dispatcher.write(mfaVerifyQn, body, GUEST_USER);
+
+      if (!result.isSuccess) {
+        // @cast-boundary error-details — KumikoError.details shape is per-error
+        const reason =
+          (result.error.details as { reason?: string } | undefined)?.reason ?? result.error.code;
+        // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
+        const status = (statusMap[reason] ?? result.error.httpStatus) as
+          | 400
+          | 401
+          | 403
+          | 422
+          | 429
+          | 500;
+        return c.json({ isSuccess: false, error: result.error }, status);
+      }
+
+      // @cast-boundary engine-payload — generic dispatcher.write result for mfa-verify handler
+      const data = result.data as { kind: "mfa-verify-success"; session: SessionUser };
+
+      const token = await mintSessionAndRespond(c, data.session);
+
+      if (rateLimiter) {
+        await rateLimiter.reset(clientIp);
+      }
+
+      return c.json({
+        isSuccess: true,
+        token,
+        user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+      });
+    });
+  }
+
   // POST /auth/request-password-reset + /auth/reset-password — public.
   // Silent-success on request (no enumeration), typed failure on confirm.
   // Rate-limit covered via config.rateLimit.auth (Sprint G.5 L2, /auth/*).

package/src/api/server.ts

@@ -3,6 +3,7 @@ import type { DbConnection, PgClient } from "../db/connection";
 import { createTenantDb } from "../db/tenant-db";
 import { EXT_FILE_PROVIDER } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
+import { createAnonymousUser } from "../engine/system-user";
 import {
   type AppContext,
   isFileField,
@@ -670,12 +671,32 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // /api/* immer Vorrang hat — feature-Routes liegen ohnehin außerhalb
   // (Boot-Validator blockt /api-Prefix). deps.app ist die Outer-App, sodass
   // der Handler /api/query intern via app.fetch(...) nutzen kann (gleicher
-  // Auth-Pfad wie ein echter HTTP-Call).
+  // Auth-Pfad wie ein echter HTTP-Call). deps.systemQuery umgeht diesen
+  // Pfad bewusst — für Routes die einen FESTEN Tenant erzwingen müssen
+  // (z.B. legal-pages → immer SYSTEM_TENANT_ID), statt ihn per X-Tenant-
+  // Header vorzutäuschen (das sieht für die anonymousAccess-Auflösung
+  // wie ein normaler Client-Header aus und wird von resolverTrust:
+  // "authoritative"-Configs zurecht als Tenant-Override abgelehnt).
   for (const feature of options.registry.features.values()) {
     for (const route of Object.values(feature.httpRoutes)) {
       // @wrapper-known semantic-alias
       const honoHandler = async (c: import("hono").Context): Promise<Response> =>
-        route.handler(c, { app });
+        route.handler(c, {
+          app,
+          systemQuery: (type, payload, tenantId) =>
+            // createAnonymousUser, NOT createSystemUser: httpRoute handlers
+            // using systemQuery are, by construction, `anonymous: true`
+            // public routes — the synthesized user must clear the SAME
+            // access gate a real anonymous visitor would, no more. The
+            // system role would ALSO satisfy that gate here, but it can
+            // read fields gated to "system" that "anonymous" can't
+            // (filterReadFields is a plain role-in-map check) — a future
+            // systemQuery caller reading a system-gated field would leak
+            // it into a public response. The forced tenant already comes
+            // from bypassing the HTTP layer entirely; no elevated role
+            // is needed or wanted on top of that.
+            dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+        });
       switch (route.method) {
         case "GET":
           app.get(route.path, honoHandler);

package/src/engine/__tests__/feature-manifest.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { ConfigScopes } from "../constants";
-import { buildManifestFromRegistry, createRegistry, defineFeature } from "../index";
+import {
+  buildManifestFromRegistry,
+  createRegistry,
+  createSystemConfig,
+  defineFeature,
+} from "../index";
 
 const boolKey = {
   type: "boolean",
@@ -104,4 +109,29 @@ describe("buildManifestFromRegistry — deterministic codepoint sort (#330)", ()
     });
     expect(noHints && "uiHints" in noHints).toBe(false);
   });
+
+  // #1039: backing:"secrets" routes the value through the envelope-encrypted
+  // secrets store — the manifest must report encrypted:true even without an
+  // explicit `encrypted` flag, so generated docs don't mislabel Stripe-style
+  // secret-backed config keys as plaintext. (createConfigKey never emits an
+  // explicit `encrypted: false` — falsy opts.encrypted just omits the field —
+  // so there's no "explicit false wins" case to pin here.)
+  test("encrypted flag — backing:secrets implies encrypted:true without an explicit flag", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.config({
+        keys: {
+          "api-key": createSystemConfig("text", { backing: "secrets" }),
+          "plain-flag": createSystemConfig("boolean", {}),
+        },
+      });
+    });
+    const registry = createRegistry([feature]);
+
+    const manifest = buildManifestFromRegistry(registry, { source: "test" });
+    const demo = manifest.features.find((f) => f.name === "demo");
+    const byKey = (key: string) => demo?.configKeys.find((k) => k.key === key);
+
+    expect(byKey("api-key")?.encrypted).toBe(true);
+    expect(byKey("plain-flag")?.encrypted).toBe(false);
+  });
 });

package/src/engine/feature-manifest.ts

@@ -106,7 +106,7 @@ export function buildManifestFromRegistry(
         type: def.type,
         scope: def.scope,
         default: def.default ?? null,
-        encrypted: def.encrypted ?? false,
+        encrypted: def.encrypted ?? def.backing === "secrets",
         computed: def.computed !== undefined,
         options: def.options ?? null,
         bounds: def.bounds ?? null,

package/src/engine/types/http-route.ts

@@ -30,6 +30,24 @@ export type HttpRouteHandlerDeps = {
    *  ansprechen (z.B. /api/query mit der vollen Auth-/Anonymous-Chain). */
   // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
   readonly app: import("hono").Hono<any, any>;
+  /** Run a query handler in-process, forcing a SPECIFIC tenant — WITHOUT
+   *  going through the public /api/query HTTP layer (no header parsing, no
+   *  anonymousAccess tenant resolution). The synthesized caller carries
+   *  anonymous-level access ONLY (same role a real anonymous request would
+   *  have, no more) — the primitive forces the tenant, not the privilege
+   *  level, so it stays safe to call from any `anonymous: true` route
+   *  without risking a field-level disclosure a real anonymous caller
+   *  couldn't already get. Use this whenever the route needs a tenant
+   *  other than the one the request resolves to (e.g. always
+   *  SYSTEM_TENANT_ID regardless of the visited host) — spoofing that via
+   *  an internal X-Tenant header on `app.fetch(...)` is indistinguishable
+   *  from an external client and gets rejected by resolverTrust:
+   *  "authoritative" anonymousAccess configs (see auth-middleware.ts). */
+  readonly systemQuery: (
+    type: string,
+    payload: unknown,
+    tenantId: import("./identifiers").TenantId,
+  ) => Promise<unknown>;
 };
 
 export type HttpRouteHandler = (

package/src/entrypoint/__tests__/entrypoint-job-wiring.integration.test.ts

@@ -17,9 +17,10 @@ import { z } from "zod";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
+import { createNoopProvider, createPrometheusMeter } from "../../observability";
 import { createEventConsumerStateTable } from "../../pipeline";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
-import { waitFor } from "../../testing";
+import { sleep, waitFor } from "../../testing";
 import { createAllInOneEntrypoint } from "../index";
 
 const jobRuns: Array<{ name: string; payload: Record<string, unknown> }> = [];
@@ -172,3 +173,55 @@ describe("createAllInOneEntrypoint auto-wires jobRunner into command-dispatcher"
     }
   });
 });
+
+// Regression test for #1046 — createJobRunner is built from the caller's
+// RAW context, BEFORE buildServer ever merges observability.tracer/meter
+// into a context object of its own. Without threading the resolved
+// provider into the job-runner's context too, `context.meter` stayed
+// undefined, the queue-depth poller's `if (context.meter)` guard skipped
+// silently, and `/metrics` showed the kumiko_job_queue_depth HELP/TYPE
+// header but never a single data line — forever, with no error anywhere.
+describe("createAllInOneEntrypoint — kumiko_job_queue_depth sees the SAME meter as buildServer (#1046)", () => {
+  test("passing an explicit observability provider makes the queue-depth poller emit real data for BOTH lanes", async () => {
+    const registry = createRegistry([wiringFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const meter = createPrometheusMeter();
+    const observability = { ...createNoopProvider(), meter };
+    const entry = createAllInOneEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `wiring-qd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      observability,
+    });
+    await entry.start();
+    try {
+      // If the job-runner never saw this meter (the #1046 bug), the poller's
+      // `if (context.meter)` guard skips entirely and no slots ever appear —
+      // this assertion is the one that would have caught it.
+      const snapshot = meter.snapshot().get("kumiko_job_queue_depth");
+      expect(snapshot).toBeDefined();
+      const workerWaiting = snapshot?.slots.find(
+        (s) => s.labels?.["lane"] === "worker" && s.labels?.["state"] === "waiting",
+      );
+      const apiWaiting = snapshot?.slots.find(
+        (s) => s.labels?.["lane"] === "api" && s.labels?.["state"] === "waiting",
+      );
+      expect(workerWaiting).toBeDefined();
+      expect(apiWaiting).toBeDefined();
+      // Same instance, not a coincidentally-equal one — proves buildServer's
+      // internal registerStandardMetrics() and the job-runner's poller wrote
+      // into the identical meter, not two disconnected Noop instances.
+      expect(entry.observability.meter).toBe(meter);
+      // BullMQ's fresh Worker connections are still settling right after
+      // start() returns — stopping immediately races their own connection
+      // teardown and throws an unrelated "Connection is closed" from
+      // ioredis (same artifact documented in job-queue-depth.integration.
+      // test.ts). Production runners live far longer than this.
+      await sleep(50);
+    } finally {
+      await entry.stop();
+    }
+  });
+});

package/src/entrypoint/index.ts

@@ -43,6 +43,7 @@ import { createJobRunner } from "../jobs/job-runner";
 import type { Lifecycle } from "../lifecycle";
 import { createLifecycle } from "../lifecycle";
 import type { ObservabilityOptions, ObservabilityProvider } from "../observability";
+import { createNoopProvider } from "../observability";
 import type { EventDedup, EventDispatcher } from "../pipeline";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher";
 import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
@@ -175,6 +176,40 @@ function mergeDispatcherOptions(
   return { ...(caller ?? {}), jobRunner };
 }
 
+// Resolve the observability provider ONCE per entrypoint boot, before any
+// job-runner is built. `buildServer` (api/server.ts) independently falls
+// back to `options.observability ?? createNoopProvider()` and merges
+// tracer/meter into a NEW context object it builds internally — but the
+// job-runner is constructed from the caller's RAW `options.context`
+// *before* buildServer ever runs, so it never saw that merge. Its
+// queue-depth poller only starts `if (context.meter)` with no fallback
+// (unlike the tracer, which has its own `getFallbackTracer()`), so an
+// unset meter silently skipped the poller forever — `/metrics` showed the
+// `kumiko_job_queue_depth` HELP/TYPE header but never a single data line
+// (#1046). Resolving once here and threading it into the job-runner's
+// context fixes the gap. This resolved instance is ONLY used for the
+// job-runner — `buildApiServer`/`buildWorkerServer` still pass the
+// caller's original `options.observability` through unchanged (not this
+// resolved value), because `buildServer` also derives `shouldWrapRedis`
+// from whether `options.observability` was explicitly set — forcing it to
+// an always-defined value here would silently switch every app's Redis
+// client onto the tracer-wrapping Proxy path even with no provider
+// configured. buildServer's own independent Noop fallback is harmless in
+// that case: nothing scrapes `/metrics` without a real provider, so a
+// second, disconnected Noop meter costs nothing.
+function resolveObservability(
+  observability: ObservabilityProvider | undefined,
+): ObservabilityProvider {
+  return observability ?? createNoopProvider();
+}
+
+function contextWithObservability(
+  context: AppContext,
+  observability: ObservabilityProvider,
+): AppContext {
+  return { ...context, tracer: observability.tracer, meter: observability.meter };
+}
+
 // buildApiServer shapes ServerOptions from API-mode caller-options.
 // AllInOneEntrypointOptions extends ApiEntrypointOptions, so structural
 // subtyping makes the all-in-one path a valid caller without an explicit
@@ -291,6 +326,7 @@ function requireDispatcher(server: KumikoServer, mode: string): EventDispatcher
 
 export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
+  const observability = resolveObservability(options.observability);
 
   // Boot-validation (Welle 2.6.c) — fail loud before traffic arrives:
   //   (a) Any jobs declared + no jobs-block → command-dispatcher would
@@ -324,7 +360,7 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
   const apiJobRunner = options.jobs
     ? buildJobRunnerWithHook(
         options.registry,
-        options.context,
+        contextWithObservability(options.context, observability),
         options.jobs,
         options.jobs.runLocalJobs ? "api" : undefined,
         lifecycle,
@@ -375,9 +411,10 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
 
 export function createWorkerEntrypoint(options: WorkerEntrypointOptions): WorkerEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
+  const observability = resolveObservability(options.observability);
   const jobRunner = buildJobRunnerWithHook(
     options.registry,
-    options.context,
+    contextWithObservability(options.context, observability),
     options,
     "worker",
     lifecycle,
@@ -406,6 +443,8 @@ export function createWorkerEntrypoint(options: WorkerEntrypointOptions): Worker
 
 export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): AllInOneEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
+  const observability = resolveObservability(options.observability);
+  const jobRunnerContext = contextWithObservability(options.context, observability);
 
   // All-in-one consumes BOTH lanes: two runners, each with a BullMQ worker
   // for its own lane's queue. Both runners hold queue-clients for both
@@ -416,7 +455,7 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
   // its own lane in its own .start().
   const workerJobRunner = buildJobRunnerWithHook(
     options.registry,
-    options.context,
+    jobRunnerContext,
     options,
     "worker",
     lifecycle,
@@ -424,7 +463,7 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
   );
   const apiJobRunner = buildJobRunnerWithHook(
     options.registry,
-    options.context,
+    jobRunnerContext,
     options,
     "api",
     lifecycle,