@cosmicdrift/kumiko-framework 0.297.0 → 0.304.0

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/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

@@ -0,0 +1,146 @@
+// ExtraRoute — declarative replacement for the old `extraRoutes: (app, deps)
+// => void` closure (kumiko-framework#3050). Every entry declares its access
+// tier (`entry`) up front; buildServer wires the matching guard + deps
+// instead of handing every route a raw db/redis escape hatch.
+
+import type { Context, Hono } from "hono";
+import type {
+  HttpRouteMethod,
+  Registry,
+  SessionUser,
+  TenantId,
+  WriteResult,
+} from "../engine/types";
+import type { SecretsContext } from "../secrets";
+
+export const ExtraRouteEntries = {
+  anonymous: "anonymous",
+  user: "user",
+  signature: "signature",
+} as const;
+
+export type ExtraRouteEntry = (typeof ExtraRouteEntries)[keyof typeof ExtraRouteEntries];
+
+export type AnonymousExtraRouteDeps = {
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: Hono<any, any>;
+  readonly registry: Registry;
+  readonly systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+  /** Runs as the session the /api chain resolved for this request —
+   *  anonymous when no token is sent, the authenticated user otherwise.
+   *  Never more than that caller could already do via /api/write: same
+   *  user, same request-resolved tenant (never overridable), only under
+   *  "/api/" (the only path that populates a session user). */
+  readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+};
+
+export type AnonymousExtraRoute = {
+  readonly method: HttpRouteMethod;
+  readonly path: string;
+  readonly entry: "anonymous";
+  readonly handler: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    deps: AnonymousExtraRouteDeps,
+  ) => Response | Promise<Response>;
+};
+
+export type UserExtraRouteDeps = {
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: Hono<any, any>;
+  readonly registry: Registry;
+  readonly user: SessionUser;
+  readonly query: (type: string, payload: unknown) => Promise<unknown>;
+  readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+};
+
+export type UserExtraRoute = {
+  readonly method: HttpRouteMethod;
+  readonly path: string;
+  readonly entry: "user";
+  readonly handler: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    deps: UserExtraRouteDeps,
+  ) => Response | Promise<Response>;
+};
+
+export type SignatureExtraRouteVerifyRequest = {
+  readonly rawBody: string;
+  /** Lowercase header names — Hono/undici normalize incoming headers to
+   *  lowercase, verify() must not have to re-normalize per provider. */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly params: Readonly<Record<string, string>>;
+  readonly query: Readonly<Record<string, string>>;
+};
+
+export type SignatureExtraRouteVerifyDeps = {
+  readonly registry: Registry;
+  readonly secrets?: SecretsContext;
+};
+
+export type SystemDispatchArgs = {
+  readonly handlerQn: string;
+  readonly payload: unknown;
+  readonly tenantId: TenantId;
+};
+
+export type SignatureExtraRouteDeps = {
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: Hono<any, any>;
+  readonly registry: Registry;
+  readonly secrets?: SecretsContext;
+  readonly systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+  /** Privilege scope: SystemAdmin of the target tenant, WITHOUT the route's
+   *  access check — only reachable because verify() has already proven the
+   *  caller's authenticity (signature, HMAC state, etc.). */
+  readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
+  readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+};
+
+export type SignatureExtraRoute<TVerified> = {
+  readonly method: HttpRouteMethod;
+  readonly path: string;
+  readonly entry: "signature";
+  readonly verify: (
+    request: SignatureExtraRouteVerifyRequest,
+    deps: SignatureExtraRouteVerifyDeps,
+  ) => Promise<TVerified>;
+  readonly handler: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    verified: TVerified,
+    deps: SignatureExtraRouteDeps,
+  ) => Response | Promise<Response>;
+};
+
+export type ExtraRouteDefinition =
+  | AnonymousExtraRoute
+  | UserExtraRoute
+  | SignatureExtraRoute<unknown>;
+
+/** Narrows a `SignatureExtraRoute<T>` into the storable `ExtraRouteDefinition`
+ *  union. The single point where the verify/handler generic `T` is erased —
+ *  callers keep full type-safety between their own verify() and handler(). */
+export function signatureRoute<T>(def: SignatureExtraRoute<T>): ExtraRouteDefinition {
+  // @cast-boundary generic erasure at the public ExtraRouteDefinition boundary;
+  // verify() and handler() above stay paired through T at the call site.
+  return def as unknown as SignatureExtraRoute<unknown>;
+}
+
+export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500;
+
+/** 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. */
+export class ExtraRouteRejection extends Error {
+  readonly status: ExtraRouteRejectionStatus;
+  readonly body: unknown;
+
+  constructor(status: ExtraRouteRejectionStatus, body: unknown, message?: string) {
+    super(message ?? `extra route rejected with status ${status}`);
+    this.name = "ExtraRouteRejection";
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/api/index.ts

@@ -28,6 +28,21 @@ export {
   createInMemoryLoginRateLimiter,
   createRedisLoginRateLimiter,
 } from "./auth-routes";
+export type {
+  AnonymousExtraRoute,
+  AnonymousExtraRouteDeps,
+  ExtraRouteDefinition,
+  ExtraRouteEntry,
+  ExtraRouteRejectionStatus,
+  SignatureExtraRoute,
+  SignatureExtraRouteDeps,
+  SignatureExtraRouteVerifyDeps,
+  SignatureExtraRouteVerifyRequest,
+  SystemDispatchArgs,
+  UserExtraRoute,
+  UserExtraRouteDeps,
+} from "./extra-route";
+export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route";
 export type { CachedResponseInit, CachePolicy } from "./http-cache";
 export {
   cacheControlHeader,
@@ -50,7 +65,7 @@ export {
 } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";
 export type { KumikoServer, ServerOptions } from "./server";
-export { buildServer } from "./server";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker";
 export { createSseBroker } from "./sse-broker";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";