@cosmicdrift/kumiko-framework 0.1.0

package/src/api/csrf-middleware.ts

@@ -0,0 +1,77 @@
+import { timingSafeEqual } from "node:crypto";
+import type { Context, Next } from "hono";
+import { getCookie } from "hono/cookie";
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, getAuthTransport } from "./auth-middleware";
+
+// Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
+// CORS + SameSite-cookie semantics and skip the CSRF check entirely.
+const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+// Constant-time byte compare. `a !== b` short-circuits at the first
+// differing byte and leaks the common prefix length to anyone who can
+// time requests — in principle exploitable against sufficiently small
+// tokens. CSRF tokens are UUIDs so the practical risk is low, but this
+// is the standard production pattern for any secret-vs-secret compare.
+// Length-check first because timingSafeEqual throws on size mismatch;
+// the length itself isn't a secret (the UUID format is known).
+const encoder = new TextEncoder();
+function tokensMatch(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(encoder.encode(a), encoder.encode(b));
+}
+
+// Double-submit CSRF guard. Runs AFTER authMiddleware — reads the
+// authTransport flag set there. Only enforces on cookie-authenticated,
+// state-changing requests. Bearer-auth requests skip the check because
+// browsers cannot set the Authorization header on cross-origin requests
+// (same-origin policy), so there is no CSRF vector to defend against.
+//
+// Mechanic: the framework sets two cookies on login — `kumiko_auth`
+// (HttpOnly, carries the JWT) and `kumiko_csrf` (JS-readable, carries a
+// token). The web client reads `kumiko_csrf` from document.cookie and
+// echoes the value in an `X-CSRF-Token` header on every state-changing
+// request. An attacker on bad.com cannot read the cookie (same-origin)
+// and therefore cannot forge the header, so any cross-site POST from the
+// attacker's page will fail the match even if the browser sent the
+// cookies along (which SameSite=Lax already prevents for all methods
+// other than top-level GETs — CSRF-middleware is belt-and-braces).
+//
+// Token rotation: issued at login + switch-tenant only, tied to the same
+// lifetime as the auth-cookie. No per-request rotation — that's the
+// Synchronizer Token pattern, needed only when token leakage via URL
+// logs or referrers is on the threat model. We keep cookies out of URLs.
+export function csrfMiddleware() {
+  return async (c: Context, next: Next) => {
+    // Not authenticated (public route) or bearer-only — no CSRF vector.
+    const transport = getAuthTransport(c);
+    if (transport !== "cookie") return next();
+
+    // Safe method — no CSRF check. SameSite=Lax blocks cross-site
+    // navigation-GETs from sending cookies, which is the only plausible
+    // CSRF-via-GET vector.
+    if (!STATE_CHANGING_METHODS.has(c.req.method)) return next();
+
+    const cookieToken = getCookie(c, CSRF_COOKIE_NAME);
+    const headerToken = c.req.header(CSRF_HEADER_NAME);
+
+    // Both must exist and match byte-for-byte. A missing cookie means the
+    // token was never issued (stale session or cross-origin attempt);
+    // a missing header means the client didn't attach it (attacker's
+    // cross-origin form submission can't read the cookie to forge one).
+    if (!cookieToken || !headerToken || !tokensMatch(cookieToken, headerToken)) {
+      return c.json(
+        {
+          error: {
+            code: "csrf_token_mismatch",
+            httpStatus: 403,
+            message: "csrf token missing or mismatch",
+            i18nKey: "auth.errors.csrfTokenMismatch",
+          },
+        },
+        403,
+      );
+    }
+
+    return next();
+  };
+}

package/src/api/index.ts

@@ -0,0 +1,31 @@
+export type { SetTenantCookieOptions } from "./anonymous-cookie";
+export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie";
+export type {
+  AnonymousAccessConfig,
+  AuthMiddlewareOptions,
+  AuthSessionChecker,
+  AuthSessionStatus,
+  TenantExists,
+  TenantResolver,
+} from "./auth-middleware";
+export { authMiddleware, getUser } from "./auth-middleware";
+export type {
+  AuthRoutesConfig,
+  LoginRateLimiter,
+  SessionChecker,
+  SessionCreator,
+  SessionMetadata,
+  SessionRevoker,
+} from "./auth-routes";
+export { createAuthRoutes, createInMemoryLoginRateLimiter } from "./auth-routes";
+export type { JwtHelper, JwtPayload } from "./jwt";
+export { createJwtHelper } from "./jwt";
+export { type RequestContextData, requestContext } from "./request-context";
+export { requestIdMiddleware } from "./request-id-middleware";
+export { createApiRoutes } from "./routes";
+export type { KumikoServer, ServerOptions } from "./server";
+export { buildServer } from "./server";
+export type { SseBroker, SseClient, SseEvent } from "./sse-broker";
+export { createSseBroker } from "./sse-broker";
+export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";
+export { generateToken } from "./tokens";

package/src/api/jwt.ts

@@ -0,0 +1,66 @@
+import * as jose from "jose";
+import type { DbRow } from "../db/connection";
+import type { SessionUser, TenantId } from "../engine/types";
+
+export type JwtPayload = {
+  // JWT `sub` is a string per RFC 7519. Matches SessionUser.id — a UUID-string
+  // under the ES migration. `sign()` already stringifies via String(user.id);
+  // `verify()` just passes it through.
+  sub: string;
+  tenantId: TenantId;
+  roles: string[];
+  // Optional — present when a feature has registered auth claims via the
+  // `r.authClaims()` hook system. Absent for stateless-JWT deployments
+  // without auth-claims wiring.
+  claims?: Record<string, unknown>;
+  // Optional session-ID, carried in the standard `jti` JWT claim.
+  // Present when the app wires a `sessionCreator` callback (see sessions
+  // feature). Absent → stateless-JWT mode, no revocation possible.
+  jti?: string;
+};
+
+export type JwtHelper = {
+  sign(user: SessionUser): Promise<string>;
+  verify(token: string): Promise<JwtPayload>;
+};
+
+export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
+  const encodedSecret = new TextEncoder().encode(secret);
+
+  return {
+    async sign(user) {
+      const body: Omit<JwtPayload, "sub" | "jti"> = {
+        tenantId: user.tenantId,
+        roles: [...user.roles],
+      };
+      if (user.claims) body.claims = { ...user.claims };
+
+      const builder = new jose.SignJWT(body)
+        .setProtectedHeader({ alg: "HS256" })
+        .setSubject(String(user.id))
+        .setIssuer(issuer)
+        .setIssuedAt()
+        .setExpirationTime("24h");
+      if (user.sid) builder.setJti(user.sid);
+
+      return builder.sign(encodedSecret);
+    },
+
+    async verify(token) {
+      const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
+      const result: JwtPayload = {
+        sub: String(payload.sub),
+        tenantId: payload["tenantId"] as string,
+        roles: payload["roles"] as string[],
+      };
+      const claims = payload["claims"];
+      if (claims && typeof claims === "object") {
+        result.claims = claims as DbRow;
+      }
+      if (typeof payload.jti === "string") {
+        result.jti = payload.jti;
+      }
+      return result;
+    },
+  };
+}

package/src/api/observability-middleware.ts

@@ -0,0 +1,89 @@
+import type { Context, Next } from "hono";
+import {
+  emitHttpRequest,
+  type Meter,
+  observabilityContext,
+  redactQueryString,
+  type SensitiveFilterConfig,
+  type Tracer,
+} from "../observability";
+import { getUser } from "./auth-middleware";
+import { requestContext } from "./request-context";
+
+// Wraps each incoming /api/* request in an `http.request` span. Must be
+// installed AFTER requestIdMiddleware so the active request-id is available
+// as a span attribute. Installed BEFORE auth so auth verification shows up
+// as a child span later when auth-middleware itself is instrumented (v2).
+
+export type ObservabilityMiddlewareOptions = {
+  readonly tracer: Tracer;
+  readonly meter: Meter;
+  readonly sensitiveConfig: SensitiveFilterConfig;
+};
+
+export function observabilityMiddleware(opts: ObservabilityMiddlewareOptions) {
+  const { tracer, meter, sensitiveConfig } = opts;
+
+  return async (c: Context, next: Next) => {
+    const method = c.req.method;
+    const path = c.req.path;
+    const target = redactQueryString(c.req.url.replace(/^https?:\/\/[^/]+/, ""), sensitiveConfig);
+
+    // Start the root span for this request. kind=server marks it as an
+    // incoming server-side span in OTel terms.
+    const span = tracer.startSpan("http.request", {
+      kind: "server",
+      attributes: {
+        "http.method": method,
+        "http.route": path,
+        "http.target": target,
+      },
+    });
+
+    const reqCtx = requestContext.get();
+    if (reqCtx?.requestId) {
+      span.setAttribute("kumiko.request_id", reqCtx.requestId);
+    }
+
+    const startTime = performance.now();
+    try {
+      await observabilityContext.run({ activeSpan: span }, () => next());
+
+      // Auth middleware runs inside `next()` and sets the user on the
+      // Hono context if the token was valid. Enrich the span after the
+      // fact so public paths (health, login) don't emit empty user attrs.
+      try {
+        const user = getUser(c);
+        if (user) {
+          span.setAttribute("kumiko.user_id", user.id);
+          span.setAttribute("kumiko.tenant_id", user.tenantId);
+        }
+      } catch {
+        // getUser throws if called before auth ran — public paths, fine.
+      }
+
+      span.setAttribute("http.status_code", c.res.status);
+      if (c.res.status >= 500) {
+        span.setStatus("error", `HTTP ${c.res.status}`);
+      } else {
+        span.setStatus("ok");
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        span.recordException(error);
+        span.setStatus("error", error.message);
+      } else {
+        span.setStatus("error", String(error));
+      }
+      span.setAttribute("http.status_code", 500);
+      throw error;
+    } finally {
+      const durationSec = (performance.now() - startTime) / 1000;
+      // c.res may be undefined on very early throws (before any route handler);
+      // fall back to 500 for the metric so the counter is always incremented.
+      const status = c.res?.status ?? 500;
+      emitHttpRequest(meter, { route: path, method, status }, durationSec);
+      span.end();
+    }
+  };
+}

package/src/api/readiness.ts

@@ -0,0 +1,132 @@
+// Readiness probe: runs a set of checks in parallel with a per-check timeout
+// and aggregates into a single result. Used by /health/ready when the caller
+// wires DB / Redis / Dispatcher — any of those down drops the probe to 503
+// so load balancers stop routing new traffic even while `lifecycle.state()`
+// is still "ready".
+//
+// Design:
+//   - Every check produces a `ReadinessCheckResult` — no thrown errors leak.
+//   - Timeout is enforced per-check, not per-probe, so a single hung dependency
+//     can't starve siblings of their budget.
+//   - Checks run in parallel — the probe is called on every kubelet/ALB poll,
+//     so total latency must stay ≈ slowest check, not sum.
+
+import { sql } from "drizzle-orm";
+import type Redis from "ioredis";
+import type { DbConnection } from "../db/connection";
+import { getAllConsumerProgress } from "../pipeline/event-dispatcher";
+
+export type ReadinessCheck = {
+  readonly name: string;
+  readonly run: () => Promise<void>;
+};
+
+export type ReadinessCheckResult = {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  readonly error?: string;
+};
+
+export type ReadinessResult = {
+  readonly ok: boolean;
+  readonly checks: readonly ReadinessCheckResult[];
+};
+
+export type ReadinessProbeOptions = {
+  readonly timeoutMs?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 2_000;
+
+export function createReadinessProbe(
+  checks: readonly ReadinessCheck[],
+  opts: ReadinessProbeOptions = {},
+): () => Promise<ReadinessResult> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return async () => {
+    const results = await Promise.all(checks.map((check) => runOne(check, timeoutMs)));
+    return {
+      ok: results.every((r) => r.ok),
+      checks: results,
+    };
+  };
+}
+
+async function runOne(check: ReadinessCheck, timeoutMs: number): Promise<ReadinessCheckResult> {
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      check.run(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+        // Don't keep the event loop alive on a hung probe during shutdown.
+        timer.unref?.();
+      }),
+    ]);
+    return {
+      name: check.name,
+      ok: true,
+      latencyMs: Math.round(performance.now() - start),
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      name: check.name,
+      ok: false,
+      latencyMs: Math.round(performance.now() - start),
+      error: message,
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// --- Standard checks --------------------------------------------------------
+
+export function dbPingCheck(db: DbConnection): ReadinessCheck {
+  return {
+    name: "db",
+    run: async () => {
+      await db.execute(sql`SELECT 1`);
+    },
+  };
+}
+
+export function redisPingCheck(redis: Redis): ReadinessCheck {
+  return {
+    name: "redis",
+    run: async () => {
+      const reply = await redis.ping();
+      if (reply !== "PONG") throw new Error(`unexpected PING reply: ${reply}`);
+    },
+  };
+}
+
+// Lag-Check für den Async-Event-Dispatcher. Liest HWM + Consumer-Cursor aus
+// der DB — kein extra Redis/Runtime-State. Fail-Schwelle ist in EventIds
+// (bigint), weil das die natürliche Einheit ist (events sind monoton id'd).
+// Ein Tuning-Beispiel: maxLagEvents = 1_000 bedeutet "wenn die Projection
+// mehr als 1k Events hinter HWM ist, stoppe neue Traffic-Zuweisung".
+export function dispatcherLagCheck(
+  db: DbConnection,
+  consumerNames: readonly string[],
+  maxLagEvents: bigint,
+): ReadinessCheck {
+  return {
+    name: "dispatcher_lag",
+    run: async () => {
+      // skip: no registered consumers means no dispatcher active — lag check has
+      // nothing to measure. Not a failure mode, just a no-op.
+      if (consumerNames.length === 0) return;
+      const progress = await getAllConsumerProgress(db, consumerNames);
+      for (const p of progress) {
+        if (p.lag > maxLagEvents) {
+          throw new Error(`consumer "${p.name}" lag=${p.lag} exceeds threshold ${maxLagEvents}`);
+        }
+      }
+    },
+  };
+}

package/src/api/request-context.ts

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { generateId } from "../utils";
+
+// Request-scoped propagation. Populated by the HTTP middleware and by the
+// event-dispatcher when it runs an MSP-apply, so ctx.appendEvent downstream
+// automatically stamps the right provenance on every event it writes.
+//
+//   requestId     — unique per HTTP request (or Job run). Log correlation.
+//   correlationId — the end-to-end business operation id; propagates across
+//                   service boundaries and MSP causation chains. Comes from
+//                   the `x-correlation-id` header if set, otherwise mirrors
+//                   requestId (clients that don't set the header pay no
+//                   penalty — a single HTTP call == one correlation).
+//   causationId   — the events.id that triggered THIS execution. Null for
+//                   root HTTP commands; set when an MSP-apply is running
+//                   (event-dispatcher wraps the handler call). Together
+//                   with correlationId, forms a causal DAG across streams.
+//   signal        — AbortSignal from the underlying HTTP request. Aborts
+//                   when the client disconnects (mobile back-press, tab
+//                   close). Long-running framework code (event streaming,
+//                   projection rebuild) checks signal.aborted at chunk
+//                   boundaries; short queries don't pay the overhead.
+//                   Undefined for non-HTTP entry-points (jobs, MSP-applies).
+export type RequestContextData = {
+  readonly requestId: string;
+  readonly correlationId: string;
+  readonly causationId?: string;
+  readonly signal?: AbortSignal;
+  // Client IP for per-IP rate limiting (L1, L2, L3 with per: "ip*").
+  // Populated by requestIdMiddleware from x-forwarded-for or the
+  // socket address. Undefined for non-HTTP entry points (jobs, MSP).
+  readonly ip?: string;
+};
+
+const storage = new AsyncLocalStorage<RequestContextData>();
+
+export const requestContext = {
+  run<T>(data: RequestContextData, fn: () => T): T {
+    return storage.run(data, fn);
+  },
+
+  get(): RequestContextData | undefined {
+    return storage.getStore();
+  },
+
+  generateId(): string {
+    return generateId();
+  },
+};

package/src/api/request-id-middleware.ts

@@ -0,0 +1,50 @@
+import type { Context, Next } from "hono";
+import { requestContext } from "./request-context";
+
+const REQUEST_ID_HEADER = "X-Request-ID";
+const CORRELATION_ID_HEADER = "X-Correlation-ID";
+
+/**
+ * Assigns a requestId + correlationId to every request and wraps execution
+ * in AsyncLocalStorage. Runs BEFORE auth — both ids are available even for
+ * 401 responses.
+ *
+ * correlationId defaults to the requestId if the client didn't set
+ * `x-correlation-id` — clients that don't care about cross-service tracing
+ * still get sensible single-request correlation for free.
+ */
+export function requestIdMiddleware() {
+  return async (c: Context, next: Next) => {
+    const requestId = c.req.header(REQUEST_ID_HEADER) ?? requestContext.generateId();
+    const correlationId = c.req.header(CORRELATION_ID_HEADER) ?? requestId;
+    c.header(REQUEST_ID_HEADER, requestId);
+    c.header(CORRELATION_ID_HEADER, correlationId);
+    c.set("requestId", requestId);
+
+    // Hono exposes the underlying Fetch Request — its `signal` aborts
+    // when the client disconnects (mobile back-press, tab close). We
+    // propagate it through requestContext so framework internals can
+    // honour cancellation at long-running checkpoints. Older Hono /
+    // adapter combos may not populate `c.req.raw.signal`; conditional
+    // spread keeps `signal: undefined` out of the stored record so
+    // downstream `signal?` checks behave as if no signal exists.
+    const signal = c.req.raw?.signal;
+    // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
+    // present (proxy/CDN) — first hop is the originating client. Adapter-
+    // specific socket-address fallback (bun, node) is not standardized
+    // in Hono; deployments behind a proxy should always set xff. Without
+    // either we leave `ip` undefined and skip ip-bucketed checks rather
+    // than fabricate one.
+    const xff = c.req.header("x-forwarded-for");
+    const ip = xff?.split(",")[0]?.trim();
+    await requestContext.run(
+      {
+        requestId,
+        correlationId,
+        ...(signal ? { signal } : {}),
+        ...(ip && ip.length > 0 ? { ip } : {}),
+      },
+      () => next(),
+    );
+  };
+}