@cosmicdrift/kumiko-framework 0.299.0 → 0.305.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.299.0",
+  "version": "0.305.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.299.0",
-    "@cosmicdrift/kumiko-types": "0.299.0",
+    "@cosmicdrift/kumiko-http": "0.305.0",
+    "@cosmicdrift/kumiko-types": "0.305.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.299.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.305.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api.test.ts

@@ -851,6 +851,7 @@ describe("feature-declared HTTP routes (r.httpRoute)", () => {
         r.httpRoute({
           method: "GET",
           path: "/api/forbidden",
+          anonymous: true,
           handler: (c) => c.text("nope"),
         });
       }),
@@ -860,8 +861,8 @@ describe("feature-declared HTTP routes (r.httpRoute)", () => {
   test("Boot-Validator: doppelte method+path-Combo wird abgelehnt", () => {
     expect(() =>
       defineFeature("dup", (r) => {
-        r.httpRoute({ method: "GET", path: "/x", handler: (c) => c.text("a") });
-        r.httpRoute({ method: "GET", path: "/x", handler: (c) => c.text("b") });
+        r.httpRoute({ method: "GET", path: "/x", anonymous: true, handler: (c) => c.text("a") });
+        r.httpRoute({ method: "GET", path: "/x", anonymous: true, handler: (c) => c.text("b") });
       }),
     ).toThrow(/already registered/);
   });

package/src/api/__tests__/extra-route-rejection.test.ts

@@ -0,0 +1,38 @@
+// Constructor invariants for ExtraRouteRejection's `retryAfterSeconds` option
+// (kumiko-framework#3168): it only makes sense together with 503 and must
+// render as a valid Retry-After delta-seconds header.
+
+import { describe, expect, test } from "bun:test";
+import { ExtraRouteRejection } from "../extra-route";
+
+describe("ExtraRouteRejection retryAfterSeconds invariants", () => {
+  test("retryAfterSeconds with a non-503 status throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(404, { error: "x" }, undefined, { retryAfterSeconds: 30 }),
+    ).toThrow(RangeError);
+  });
+
+  test("negative retryAfterSeconds throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(503, { error: "x" }, undefined, { retryAfterSeconds: -1 }),
+    ).toThrow(RangeError);
+  });
+
+  test("non-integer retryAfterSeconds throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(503, { error: "x" }, undefined, { retryAfterSeconds: 1.5 }),
+    ).toThrow(RangeError);
+  });
+
+  test("retryAfterSeconds: 0 with status 503 is accepted", () => {
+    const rejection = new ExtraRouteRejection(503, { error: "x" }, undefined, {
+      retryAfterSeconds: 0,
+    });
+    expect(rejection.retryAfterSeconds).toBe(0);
+  });
+
+  test("no options leaves retryAfterSeconds undefined", () => {
+    const rejection = new ExtraRouteRejection(503, { error: "x" });
+    expect(rejection.retryAfterSeconds).toBeUndefined();
+  });
+});

package/src/api/__tests__/extra-routes.integration.test.ts

@@ -461,6 +461,14 @@ describe("extraRoutes: entry:signature", () => {
       if (req.headers["x-force-404"] === "1") {
         throw new ExtraRouteRejection(404, { error: "unknown-provider" });
       }
+      if (req.headers["x-force-503"] === "retry") {
+        throw new ExtraRouteRejection(503, { error: "not-ready" }, undefined, {
+          retryAfterSeconds: 30,
+        });
+      }
+      if (req.headers["x-force-503"] === "plain") {
+        throw new ExtraRouteRejection(503, { error: "not-ready" });
+      }
       if (req.headers["x-hmac"] !== signHmac(req.rawBody)) {
         throw new Error("signature mismatch");
       }
@@ -536,6 +544,28 @@ describe("extraRoutes: entry:signature", () => {
     expect(await res.json()).toEqual({ error: "unknown-provider" });
   });
 
+  test("verify() throwing ExtraRouteRejection(503, body, options) surfaces the body and Retry-After header", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-503": "retry", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: "not-ready" });
+    expect(res.headers.get("retry-after")).toBe("30");
+  });
+
+  test("verify() throwing ExtraRouteRejection(503, body) without options omits the Retry-After header", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-503": "plain", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: "not-ready" });
+    expect(res.headers.get("retry-after")).toBeNull();
+  });
+
   test("mounted under /api/:provider — no session needed, honoPathToRegex matches the :param, rawBody arrives intact through /api/*", async () => {
     const rawBody = JSON.stringify({ event: "payment.succeeded" });
     const res = await stack.app.request("/api/webhooks/stripe", {

package/src/api/__tests__/http-route-entry.integration.test.ts

@@ -0,0 +1,114 @@
+// kumiko-framework#2885 step 3: `HttpRouteDefinition.anonymous` now controls
+// the mount, not just docs/boot-validation. `anonymous: false` must sit
+// behind the SAME session-auth chain /api/* uses (no anonymous fallthrough,
+// PAT rate limit, origin + CSRF guards) — a request without a session gets
+// 401, never a synthesized anonymous user. `anonymous: true` stays public.
+//
+// anonymousAccess is deliberately wired on the test stack: without it, a
+// wrongly-mounted `anonymous: false` route (using jwtGuard instead of
+// sessionOnlyGuard) would ALSO 401 on a missing token, masking the bug the
+// 401 test exists to catch.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, getUser } from "../auth-middleware";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+
+const entryFeature = defineFeature("http-route-entry", (r) => {
+  r.httpRoute({
+    method: "GET",
+    path: "/entry-public",
+    anonymous: true,
+    handler: async (c) => c.json({ ok: true }),
+  });
+  r.httpRoute({
+    method: "GET",
+    path: "/entry-private",
+    anonymous: false,
+    handler: async (c) => c.json({ id: getUser(c).id }),
+  });
+  r.httpRoute({
+    method: "POST",
+    path: "/entry-private",
+    anonymous: false,
+    handler: async (c) => c.json({ id: getUser(c).id }),
+  });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [entryFeature],
+    anonymousAccess: { defaultTenantId: TENANT_ID },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("r.httpRoute anonymous:false — session auth chain", () => {
+  test("GET without a session → 401, no anonymous fallthrough", async () => {
+    const res = await stack.app.request("/entry-private");
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("missing_token");
+  });
+
+  // Hono answers HEAD through the GET route while c.req.method stays "HEAD";
+  // the guard chain must still run for it.
+  test("HEAD without a session → 401, not the GET handler unguarded", async () => {
+    const res = await stack.app.request("/entry-private", { method: "HEAD" });
+    expect(res.status).toBe(401);
+  });
+
+  test("GET with a real session → 200, handler sees the logged-in user, not anonymous", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/entry-private", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { id: string };
+    expect(body.id).toBe(TestUsers.user.id);
+    expect(body.id).not.toBe("anonymous");
+  });
+
+  test("POST with cookie auth, no CSRF token → 403 csrf_token_mismatch", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/entry-private", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}` },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("csrf_token_mismatch");
+  });
+
+  test("POST with cookie auth + matching CSRF token → 200", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const csrf = "csrf-fixed-http-route-entry-token";
+    const res = await stack.app.request("/entry-private", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}; ${CSRF_COOKIE_NAME}=${csrf}`,
+        [CSRF_HEADER_NAME]: csrf,
+      },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { id: string };
+    expect(body.id).toBe(TestUsers.user.id);
+  });
+});
+
+describe("r.httpRoute anonymous:true — stays public", () => {
+  test("GET without a session → 200", async () => {
+    const res = await stack.app.request("/entry-public");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean };
+    expect(body.ok).toBe(true);
+  });
+});

package/src/api/__tests__/server-error-logging.test.ts

@@ -27,6 +27,14 @@ const boomFeature = defineFeature("boom", (r) => {
     },
     openToAll,
   );
+  r.writeHandler(
+    "explode",
+    z.object({}),
+    async () => {
+      throw new Error("disk on fire during write");
+    },
+    openToAll,
+  );
   r.queryHandler(
     "decode",
     z.object({}),
@@ -140,6 +148,31 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     }
   });
 
+  test("a throwing write 500s AND its cause reaches the log (reraise keeps the cause)", async () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request("/api/write", {
+        method: "POST",
+        headers: await auth(),
+        body: JSON.stringify({ type: "boom:write:explode", payload: {} }),
+      });
+      expect(res.status).toBe(500);
+      const hit = calls.find(
+        (args) => typeof args[0] === "string" && args[0].includes("[api] handler failed"),
+      );
+      const data = hit?.[1];
+      expect(isRecord(data)).toBe(true);
+      if (!isRecord(data)) return;
+      expect(data["type"]).toBe("boom:write:explode");
+      expect(data["cause"]).toBe("disk on fire during write");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
   test("a 404 stays off the error level (it is a client outcome, not a server fault)", async () => {
     const { status, errors } = await queryWithCapturedWarnings("nope:query:nothing", {});
     expect(status).toBe(404);

package/src/api/api-constants.ts

@@ -101,6 +101,19 @@ export const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.files}`,
 ]);
 
+// authEndpointRateLimit (L2) exceptions, exact method+path match, no prefix/glob.
+// A forgotten entry here is safe (over-limited, not unlimited).
+export const AUTH_RATE_LIMIT_EXEMPT_ROUTES: ReadonlyArray<{
+  readonly method: string;
+  readonly path: string;
+}> = [{ method: "GET", path: `/api${Routes.authTenants}` }];
+
+export function isAuthRateLimitExempt(method: string, path: string): boolean {
+  return AUTH_RATE_LIMIT_EXEMPT_ROUTES.some(
+    (route) => route.method === method && route.path === path,
+  );
+}
+
 // Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
 // CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
 export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([

package/src/api/auth-routes.ts

@@ -5,7 +5,7 @@ import { deleteCookie, setCookie } from "hono/cookie";
 import type Redis from "ioredis";
 import { z } from "zod";
 import { buildSessionRoles } from "../engine/membership-roles";
-import { createSystemUser } from "../engine/system-user";
+import { createAnonymousUser, createSystemUser } from "../engine/system-user";
 import {
   type ActiveMembershipRejection,
   type ActiveMembershipResult,
@@ -197,15 +197,6 @@ type MembershipRow = {
   tenantKey?: string;
 };
 
-// Guest identity used for unauthenticated calls (e.g. login). The "all" role
-// lets framework access checks pass for handlers declared with roles: ["all"].
-// `id` is the zero-uuid so it flows through event-store columns cleanly.
-const GUEST_USER: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
-  tenantId: SYSTEM_TENANT_ID,
-  roles: ["all"],
-};
-
 // Pluggable rate-limiter for POST /auth/login. Returning `false` blocks the
 // request with 429 before the login handler runs — use this to slow down
 // brute-force attempts. The framework ships a default in-memory impl; apps
@@ -780,7 +771,7 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(loginQn, body, GUEST_USER);
+      const result = await dispatcher.write(loginQn, body, createAnonymousUser(SYSTEM_TENANT_ID));
 
       if (!result.isSuccess) {
         // Feature-specific auth reason codes arrive via UnprocessableError.details.reason
@@ -845,7 +836,7 @@ export function createAuthRoutes(
   }
 
   // POST /auth/mfa/verify — completes a two-step login. Mirrors /auth/login
-  // structurally (public, GUEST_USER dispatch, mintSessionAndRespond on
+  // structurally (public, anonymous identity 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
@@ -877,7 +868,11 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(mfaVerifyQn, body, GUEST_USER);
+      const result = await dispatcher.write(
+        mfaVerifyQn,
+        body,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // @cast-boundary error-details — KumikoError.details shape is per-error
@@ -954,7 +949,11 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(mfaPreauthEnableStartQn, body, GUEST_USER);
+      const result = await dispatcher.write(
+        mfaPreauthEnableStartQn,
+        body,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // @cast-boundary error-details — KumikoError.details shape is per-error
@@ -985,7 +984,7 @@ export function createAuthRoutes(
 
   // POST /auth/mfa/preauth-confirm — completes both the enrollment started
   // by preauth-enable-start AND the login mfa-setup-required blocked.
-  // Mirrors /auth/mfa/verify structurally (public, GUEST_USER dispatch,
+  // Mirrors /auth/mfa/verify structurally (public, anonymous identity dispatch,
   // mintSessionAndRespond on success) with its OWN rate limiter
   // (mfaPreauthConfirmRateLimit) — same reasoning as mfaVerifyRateLimit.
   // Per-account brute-force protection (capping wrong-code guesses against
@@ -1016,7 +1015,11 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(mfaPreauthConfirmQn, body, GUEST_USER);
+      const result = await dispatcher.write(
+        mfaPreauthConfirmQn,
+        body,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // @cast-boundary error-details — KumikoError.details shape is per-error
@@ -1128,7 +1131,11 @@ export function createAuthRoutes(
         return c.json({ isSuccess: false, error: "invalid_body" }, 400);
       }
 
-      const result = await dispatcher.write(sg.confirmHandler, parsed.data, GUEST_USER);
+      const result = await dispatcher.write(
+        sg.confirmHandler,
+        parsed.data,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // 422 für invalid_signup_token (handler-level UnprocessableError).
@@ -1210,7 +1217,11 @@ export function createAuthRoutes(
       if (!parsed.success) {
         return c.json({ isSuccess: false, error: "invalid_body" }, 400);
       }
-      const result = await dispatcher.write(inv.acceptWithLoginHandler, parsed.data, GUEST_USER);
+      const result = await dispatcher.write(
+        inv.acceptWithLoginHandler,
+        parsed.data,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
       if (!result.isSuccess) {
         const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
         return c.json({ isSuccess: false, error: result.error }, status);
@@ -1258,7 +1269,11 @@ export function createAuthRoutes(
       if (!parsed.success) {
         return c.json({ isSuccess: false, error: "invalid_body" }, 400);
       }
-      const result = await dispatcher.write(inv.signupCompleteHandler, parsed.data, GUEST_USER);
+      const result = await dispatcher.write(
+        inv.signupCompleteHandler,
+        parsed.data,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
       if (!result.isSuccess) {
         const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
         return c.json({ isSuccess: false, error: result.error }, status);
@@ -1457,10 +1472,20 @@ function registerTokenRequestRoute(opts: {
     if (!parsed.success) return c.json({ isSuccess: true });
 
     // The handler dispatches the magic-link mail via delivery before returning.
-    // Handler-level failures (only legitimate reason: misconfiguration) are
-    // silently swallowed — observability logs capture them for ops — so the
-    // response shape stays uniform for unknown vs. known emails.
-    await opts.dispatcher.write(opts.requestHandler, { email: parsed.data.email }, GUEST_USER);
+    // Handler-level failures (misconfiguration, e.g. no RateLimitResolver) stay
+    // out of the response so it is uniform for unknown vs. known emails, but
+    // they are logged — otherwise the mail silently never goes out. No email in
+    // the log line (PII).
+    const result = await opts.dispatcher.write(
+      opts.requestHandler,
+      { email: parsed.data.email },
+      createAnonymousUser(SYSTEM_TENANT_ID),
+    );
+    if (!result.isSuccess) {
+      console.error(
+        `[kumiko] token request handler "${opts.requestHandler}" failed: ${result.error.code}`,
+      );
+    }
 
     return c.json({ isSuccess: true });
   });
@@ -1480,7 +1505,11 @@ function registerTokenConfirmRoute(opts: {
     if (!parsed.success) {
       return c.json({ isSuccess: false, error: "invalid_body" }, 400);
     }
-    const result = await opts.dispatcher.write(opts.confirmHandler, parsed.data, GUEST_USER);
+    const result = await opts.dispatcher.write(
+      opts.confirmHandler,
+      parsed.data,
+      createAnonymousUser(SYSTEM_TENANT_ID),
+    );
     if (!result.isSuccess) {
       const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
       return c.json({ isSuccess: false, error: result.error }, status);

package/src/api/extra-route.ts

@@ -128,19 +128,48 @@ export function signatureRoute<T>(def: SignatureExtraRoute<T>): ExtraRouteDefini
   return def as unknown as SignatureExtraRoute<unknown>;
 }
 
-export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500;
+export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500 | 503;
+
+export type ExtraRouteRejectionOptions = { readonly retryAfterSeconds?: number };
 
 /** Thrown by `verify()` to reject a signature route with a specific status +
  *  JSON body. Any other throw from `verify()` is mapped to 401
- *  `extra_route_signature_invalid` by the buildServer wrapper. */
+ *  `extra_route_signature_invalid` by the buildServer wrapper.
+ *
+ *  503 signals "temporarily not ready" (e.g. a dependency the verify step
+ *  needs is down) — webhook providers like Stripe retry on 503.
+ *  `options.retryAfterSeconds` renders as the `Retry-After` header. */
 export class ExtraRouteRejection extends Error {
   readonly status: ExtraRouteRejectionStatus;
   readonly body: unknown;
-
-  constructor(status: ExtraRouteRejectionStatus, body: unknown, message?: string) {
+  readonly retryAfterSeconds: number | undefined;
+
+  constructor(
+    status: ExtraRouteRejectionStatus,
+    body: unknown,
+    message?: string,
+    options?: ExtraRouteRejectionOptions,
+  ) {
     super(message ?? `extra route rejected with status ${status}`);
     this.name = "ExtraRouteRejection";
     this.status = status;
     this.body = body;
+    const retryAfterSeconds = options?.retryAfterSeconds;
+    if (retryAfterSeconds !== undefined) {
+      // Retry-After is only meaningful for 503 in this union (RFC 9110) and
+      // is rendered as a delta-seconds header — reject anything that could
+      // not survive that round-trip.
+      if (status !== 503) {
+        throw new RangeError(
+          "ExtraRouteRejection: retryAfterSeconds is only valid with status 503",
+        );
+      }
+      if (!Number.isInteger(retryAfterSeconds) || retryAfterSeconds < 0) {
+        throw new RangeError(
+          "ExtraRouteRejection: retryAfterSeconds must be a non-negative integer",
+        );
+      }
+    }
+    this.retryAfterSeconds = retryAfterSeconds;
   }
 }

package/src/api/index.ts

@@ -33,6 +33,7 @@ export type {
   AnonymousExtraRouteDeps,
   ExtraRouteDefinition,
   ExtraRouteEntry,
+  ExtraRouteRejectionOptions,
   ExtraRouteRejectionStatus,
   SignatureExtraRoute,
   SignatureExtraRouteDeps,