@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/api/post-auth-landing.ts

@@ -1,105 +0,0 @@
-// Server-computed post-auth redirect target. AuthRoutesConfig.postAuthLanding
-// lets an app decide, in ONE place, where a user lands after login/signup/
-// invite — instead of every frontend screen re-deriving it from roles/
-// tenantId via loggedInHref. The result travels in the JSON response
-// (`landingPath`) and is validated here before it ever reaches the wire: an
-// app-supplied resolver is untrusted input from the framework's perspective,
-// and a bad value would otherwise become a same-response open redirect.
-
-import { createFallbackLogger } from "../logging";
-
-export type PostAuthLandingFlow = "login" | "signup" | "invite";
-
-export type PostAuthLandingArgs = {
-  readonly flow: PostAuthLandingFlow;
-  readonly roles: readonly string[];
-  readonly tenantId: string;
-  // signup only.
-  readonly tenantKey?: string;
-  // signup only, present when signup-confirm claimed a bound handover grant.
-  readonly handover?: { readonly entityType: string; readonly id: string };
-};
-
-export type PostAuthLandingResolver = (args: PostAuthLandingArgs) => string | undefined;
-
-function hasControlOrDelCharacter(candidate: string): boolean {
-  for (let i = 0; i < candidate.length; i++) {
-    const code = candidate.charCodeAt(i);
-    if (code <= 0x1f || code === 0x7f) return true;
-  }
-  return false;
-}
-
-// Root-relative-only allowlist, stricter than the framework's existing
-// billing isRootRelativePath: rejects protocol-relative ("//host") and
-// backslash-based ("/\host") paths a browser would still resolve to a
-// different origin, and control chars/whitespace a URL parser silently
-// strips (so "/\t/evil.com" would otherwise normalize to "//evil.com" past
-// the leading-slash check). The new URL(...) parse is a backstop for
-// anything the explicit checks above missed.
-export function isSafeLandingPath(candidate: unknown): candidate is string {
-  if (typeof candidate !== "string" || candidate.length === 0) return false;
-  if (!candidate.startsWith("/")) return false;
-  const second = candidate[1];
-  if (second === "/" || second === "\\") return false;
-  if (candidate.includes("\\")) return false;
-  if (hasControlOrDelCharacter(candidate)) return false;
-  if (/\s/.test(candidate)) return false;
-  try {
-    const parsed = new URL(candidate, "https://landing.invalid");
-    if (parsed.origin !== "https://landing.invalid") return false;
-    // "/.//evil.com" clears every check above (no leading "//", no
-    // backslash) but normalizes to pathname "//evil.com" — still same-
-    // origin on first navigation, but protocol-relative if a caller ever
-    // re-resolves the bare pathname as a fresh href.
-    return !parsed.pathname.startsWith("//");
-  } catch {
-    return false;
-  }
-}
-
-function isThenable(value: unknown): value is PromiseLike<unknown> {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "then" in value &&
-    typeof value.then === "function"
-  );
-}
-
-const landingLog = createFallbackLogger("auth");
-
-export function resolvePostAuthLandingPath(
-  resolver: PostAuthLandingResolver | undefined,
-  args: PostAuthLandingArgs,
-): string | undefined {
-  if (!resolver) return undefined;
-  let candidate: unknown;
-  try {
-    candidate = resolver(args);
-  } catch (error) {
-    // Consumer error messages can carry PII or secrets; log only the error class.
-    landingLog.warn("postAuthLanding threw — landingPath omitted", {
-      flow: args.flow,
-      errorName: error instanceof Error ? error.name : typeof error,
-    });
-    return undefined;
-  }
-  if (isThenable(candidate)) {
-    // A JS consumer (or a cast) can bypass the sync signature; an unobserved
-    // rejection would terminate the Bun process on every login.
-    Promise.resolve(candidate).catch(() => undefined);
-    landingLog.warn("postAuthLanding async resolver not supported — landingPath omitted", {
-      flow: args.flow,
-    });
-    return undefined;
-  }
-  if (candidate === undefined) return undefined;
-  if (!isSafeLandingPath(candidate)) {
-    landingLog.warn("postAuthLanding returned an unsafe path — landingPath omitted", {
-      flow: args.flow,
-    });
-    return undefined;
-  }
-  return candidate;
-}

package/src/api/readiness.ts

@@ -1,132 +0,0 @@
-// 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 type Redis from "ioredis";
-import type { DbConnection } from "../db/connection";
-import { pingDatabase } from "../db/queries/raw-sql";
-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 pingDatabase(db);
-    },
-  };
-}
-
-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/redis-sse-broker.ts

@@ -1,171 +0,0 @@
-import { createRedisPubSubSignal } from "../redis/pubsub-signal";
-import type { AccessInvalidationScope } from "./sse-broker";
-import { createSseBroker, type SseBroker, type SseEvent } from "./sse-broker";
-
-// Channel namespace for cross-replica fanout (fw#2625). Every pod publishes
-// here and every pod's psubscribe listens here, so a push on one instance
-// reaches SSE clients connected to any other instance without a shared
-// cursor — Pub/Sub for connected-client fanout, the event-store's shared
-// cursor stays the mechanism for "read every event exactly once".
-const CHANNEL_PREFIX = "kumiko:sse:ch:";
-const INVALIDATION_PREFIX = "kumiko:sse:inval:";
-const PSUBSCRIBE_PATTERN = "kumiko:sse:*";
-
-export type RedisSseBrokerOptions = {
-  readonly redisUrl: string;
-};
-
-export type RedisSseBroker = SseBroker & {
-  // Not on SseBroker — the in-memory broker has nothing to release, but
-  // this one owns two live ioredis connections (via the shared PubSubSignal).
-  // buildServer only calls this when it created the broker itself (an
-  // app-injected sseBroker owns its own lifecycle).
-  close(): Promise<void>;
-};
-
-// The one property RedisSseBroker adds over SseBroker — cheap and reliable
-// to narrow on, so callers that only hold an SseBroker (e.g. a test that
-// pulled it back out of a generic ServerOptions.sseBroker slot) can tell
-// which lifecycle they own without an unsound `as` cast.
-export function isRedisSseBroker(broker: SseBroker): broker is RedisSseBroker {
-  return "close" in broker;
-}
-
-// Single decision point for "which SseBroker should a caller default to
-// when it doesn't inject its own": REDIS_URL present → cross-replica
-// Redis-backed broker, absent → the in-memory one. Both buildServer and
-// runProdApp must funnel through this rather than each deciding on their
-// own — runProdApp doing exactly that (building an in-memory broker
-// unconditionally, then passing it in as ServerOptions.sseBroker) is why
-// fw#2625's fanout fix (fw#2630) shipped without ever taking effect in
-// production: an explicit ServerOptions.sseBroker always wins in
-// buildServer, so its own REDIS_URL-based default never ran.
-export function createDefaultSseBroker(env: Record<string, string | undefined> = process.env): {
-  readonly sseBroker: SseBroker;
-  // Present only when REDIS_URL resolved. undefined means the fallback
-  // in-memory broker was used, which has nothing to release on shutdown.
-  readonly ownedRedisSseBroker: RedisSseBroker | undefined;
-} {
-  const redisUrl = env["REDIS_URL"];
-  const ownedRedisSseBroker = redisUrl ? createRedisSseBroker({ redisUrl }) : undefined;
-  return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
-}
-
-function isSseEvent(value: unknown): value is SseEvent {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    typeof (value as { type?: unknown }).type === "string" &&
-    typeof (value as { data?: unknown }).data === "object" &&
-    (value as { data?: unknown }).data !== null
-  );
-}
-
-// Invalidation payload: `1` means userwide, `{ keptSessionId }` spares that
-// one session (all-except-session), `{ scope: "sessions", sessionIds }` /
-// `{ scope: "pat-tokens", tokenIds }` narrow to those credentials. A newer
-// scope payload NEVER carries a `keptSessionId` key, by construction —
-// that's what makes it safe for an older pod (which only ever reads
-// `keptSessionId`) to treat any of these as userwide instead of silently
-// sparing something it doesn't understand: fail-closed on a mixed rolling
-// deploy. Anything malformed also falls back to userwide.
-function parseInvalidationScope(payload: unknown): AccessInvalidationScope {
-  if (typeof payload !== "object" || payload === null) return { kind: "user" };
-  const record = payload as Record<string, unknown>;
-
-  if ("scope" in record) {
-    const { scope } = record;
-    if (scope === "sessions") {
-      const sessionIds = readNonEmptyStringArray(record["sessionIds"]);
-      if (sessionIds) return { kind: "sessions", sessionIds };
-    }
-    if (scope === "pat-tokens") {
-      const tokenIds = readNonEmptyStringArray(record["tokenIds"]);
-      if (tokenIds) return { kind: "pat-tokens", tokenIds };
-    }
-    return { kind: "user" };
-  }
-
-  if ("keptSessionId" in record) {
-    const { keptSessionId } = record;
-    if (typeof keptSessionId === "string" && keptSessionId.length > 0) {
-      return { kind: "all-except-session", keptSessionId };
-    }
-    return { kind: "user" };
-  }
-
-  return { kind: "user" };
-}
-
-function readNonEmptyStringArray(value: unknown): string[] | undefined {
-  if (!Array.isArray(value) || value.length === 0) return undefined;
-  return value.every((v): v is string => typeof v === "string") ? value : undefined;
-}
-
-// Mirror of parseInvalidationScope's wire shapes. "sessions"/"pat-tokens"
-// deliberately never include a `keptSessionId` key — see the parser comment.
-function encodeInvalidationScope(scope: AccessInvalidationScope | undefined): unknown {
-  if (scope === undefined || scope.kind === "user") return 1;
-  if (scope.kind === "all-except-session") return { keptSessionId: scope.keptSessionId };
-  if (scope.kind === "sessions") return { scope: "sessions", sessionIds: scope.sessionIds };
-  return { scope: "pat-tokens", tokenIds: scope.tokenIds };
-}
-
-// Transport layer around a local `createSseBroker()` — all client/listener
-// state lives in `inner`, this only moves events across the Redis wire via
-// the shared PubSubSignal. `pushToChannel`/`publishAccessInvalidation` never
-// call `inner` directly: they publish, and the signal's message handler
-// below calls `inner` for BOTH the publishing pod and every other pod, so
-// there's exactly one delivery path regardless of which instance receives
-// the request.
-export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroker {
-  const inner = createSseBroker();
-  const signal = createRedisPubSubSignal({
-    redisUrl: opts.redisUrl,
-    channelPattern: PSUBSCRIBE_PATTERN,
-    label: "sse-broker",
-  });
-
-  signal.onMessage((channel, payload) => {
-    if (channel.startsWith(CHANNEL_PREFIX)) {
-      if (!isSseEvent(payload)) {
-        console.error(`[kumiko:sse-broker] dropping malformed event on "${channel}"`);
-        // skip: malformed payload already logged above, nothing to deliver
-        return;
-      }
-      inner.pushToChannel(channel.slice(CHANNEL_PREFIX.length), payload);
-      // skip: channel already routed to the SSE-event branch above, the
-      // invalidation branch below is mutually exclusive with this one
-      return;
-    }
-
-    if (channel.startsWith(INVALIDATION_PREFIX)) {
-      inner.publishAccessInvalidation(
-        channel.slice(INVALIDATION_PREFIX.length),
-        parseInvalidationScope(payload),
-      );
-    }
-  });
-
-  return {
-    addClient: inner.addClient,
-    removeClient: inner.removeClient,
-    getClientCount: inner.getClientCount,
-    getTotalClientCount: inner.getTotalClientCount,
-    subscribeAccessInvalidation: inner.subscribeAccessInvalidation,
-
-    pushToChannel(channel, event) {
-      signal.publish(`${CHANNEL_PREFIX}${channel}`, event);
-    },
-
-    // fw#1601: this is the security-critical call — a revoked session's
-    // stream must close on every replica, not just the one that observed
-    // the revocation event. Publishing (rather than calling inner directly,
-    // like the in-memory broker does) is what makes that true here.
-    publishAccessInvalidation(userId, scope) {
-      signal.publish(`${INVALIDATION_PREFIX}${userId}`, encodeInvalidationScope(scope));
-    },
-
-    close: signal.close,
-  };
-}

package/src/api/request-context.ts

@@ -1,137 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
-import type { AgentRisk } from "@cosmicdrift/kumiko-types/handlers";
-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). Query/stream handlers check signal.aborted at
-//                   chunk or query boundaries; runBatch (write dispatch)
-//                   strips it before executing so a disconnect can't abort
-//                   a transaction mid-commit. Undefined for non-HTTP
-//                   entry-points (jobs, MSP-applies) and inside write batches.
-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 via the shared trustedProxyHops-aware
-  // resolver (see api/client-ip.ts) — never skipped
-  // for an HTTP request, falls back to "unknown" rather than leaving this
-  // undefined. Undefined only for non-HTTP entry points (jobs, MSP).
-  readonly ip?: string;
-  // Raw User-Agent header — audit trails (download tokens, GDPR export
-  // access) want it alongside `ip`. Undefined for non-HTTP entry points.
-  readonly userAgent?: string;
-  // Client-declared active UI locale (BCP-47), resolved once from
-  // X-Locale / Accept-Language by requestIdMiddleware — see
-  // request-locale.ts. Undefined when neither header carried a valid tag;
-  // callers fall back further (dispatch-shared.ts's ctx.locale chain).
-  readonly locale?: string;
-  // Attribution of the currently executing scope (#3043): the feature that
-  // owns it and the qualified name of the handler / MSP-consumer / job
-  // inside it. event-store.append() reads both and stamps them onto every
-  // event written under this scope.
-  readonly feature?: string;
-  readonly handler?: string;
-  // performance.now() at request entry, so a failing request can report how
-  // long it ran. Monotonic — a wall-clock step cannot make it negative.
-  readonly startedAt?: number;
-  // Only ever a gated origin. Read by job enqueue and event-store.append();
-  // dispatch roots never narrow from it, only jobs inherit explicitly.
-  readonly writeOrigin?: WriteOrigin;
-  // The handler directly invoked by the dispatcher (not a nested ctx.write/
-  // writeAs target) — nested dispatches inherit it unchanged, so the
-  // irreversible-operation gate always sees the outermost caller's risk.
-  readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
-};
-
-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();
-  },
-};
-
-// Enter a scope that attributes every event written inside it. Keeps the
-// surrounding request's ids so correlation survives, and mints fresh ones
-// when there is no surrounding request (job-runner, event-dispatcher) —
-// requestId/correlationId are mandatory, `get()` may be undefined.
-export function runWithOrigin<T>(
-  origin: {
-    readonly feature?: string;
-    readonly handler?: string;
-    readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
-  },
-  fn: () => T,
-): T {
-  const current = requestContext.get();
-  const requestId = current?.requestId ?? requestContext.generateId();
-  return requestContext.run(
-    {
-      ...current,
-      requestId,
-      correlationId: current?.correlationId ?? requestId,
-      feature: origin.feature,
-      handler: origin.handler,
-      // The outermost dispatch wins — a nested ctx.write/writeAs must not
-      // overwrite the entry handler that the irreversible-operation gate reads.
-      entryHandler: current?.entryHandler ?? origin.entryHandler,
-    },
-    fn,
-  );
-}
-
-// Clears entryHandler so the next dispatch inside fn becomes the new entry —
-// used by dispatchToolCall so the invoked tool handler, not the surrounding
-// turn/approve handler, is what the irreversible-operation gate sees.
-export function runAsDirectCallEntry<T>(fn: () => T): T {
-  const current = requestContext.get();
-  if (!current) return fn();
-  const { entryHandler: _entryHandler, ...rest } = current;
-  return requestContext.run(rest, fn);
-}
-
-// An ungated origin never mints a scope: seeds and boot writes keep their missing context.
-export function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T {
-  const current = requestContext.get();
-  if (!isPersonalDataGated(origin)) {
-    if (!current?.writeOrigin) return fn();
-    const { writeOrigin: _writeOrigin, ...rest } = current;
-    return requestContext.run(rest, fn);
-  }
-  const requestId = current?.requestId ?? requestContext.generateId();
-  return requestContext.run(
-    {
-      ...current,
-      requestId,
-      correlationId: current?.correlationId ?? requestId,
-      writeOrigin: origin,
-    },
-    fn,
-  );
-}

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

@@ -1,138 +0,0 @@
-import type { Context, Next } from "hono";
-import { resolveHeaderLocale } from "../i18n/request-locale";
-import { LOCALE_HEADER_NAME } from "./api-constants";
-import { type ClientIpResolver, createClientIpResolver, extractSocketAddress } from "./client-ip";
-import { type RequestContextData, requestContext } from "./request-context";
-
-// Fallback for the few call-sites that build a RequestContextData without a
-// caller-configured resolver (e.g. an internal system-query mount reached
-// before requestIdMiddleware ran). trustedProxyHops 0 matches the framework
-// default; callers that care about the real hop count pass their own
-// resolver instead — see requestIdMiddleware(options).
-const FALLBACK_CLIENT_IP_RESOLVER = createClientIpResolver(0, "requestIdMiddleware");
-
-const REQUEST_ID_HEADER = "X-Request-ID";
-const CORRELATION_ID_HEADER = "X-Correlation-ID";
-
-// requestId/correlationId flow unvalidated into append-only event-store
-// metadata (e.g. sessions:revoke-all-for-user) — cap shape at the trust
-// boundary so a client can't smuggle an oversized/control-char payload into
-// permanent, replayed, DSGVO-exported storage via a client-set header.
-const SAFE_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
-
-function sanitizeClientId(value: string | undefined): string | undefined {
-  return value !== undefined && SAFE_ID_RE.test(value) ? value : undefined;
-}
-
-// Request.headers.get() returns `string | null` (Fetch API); Hono's
-// c.req.header() normalizes that to `string | undefined`. Match Hono's
-// contract here so both builders return the exact same RequestContextData
-// shape regardless of which one a call-site uses.
-function header(req: Request, name: string): string | undefined {
-  return req.headers.get(name) ?? undefined;
-}
-
-/**
- * Builds the RequestContextData record for a raw Fetch Request — requestId
- * (client-supplied + sanitized, or generated), correlationId (mirrors
- * requestId unless the client set its own), the underlying abort signal,
- * and the client IP/User-Agent. Extracted out of `buildRequestContextData`
- * so call-sites that only have a `Request` (no Hono `Context`) — e.g.
- * server-runtime's static-fallback page-head resolver, which runs outside
- * Hono's router entirely — can still populate the same AsyncLocalStorage
- * record via `requestContext.run(...)`.
- */
-export function buildRequestContextDataFromRequest(
-  req: Request,
-  options?: { readonly resolver?: ClientIpResolver; readonly socketAddress?: string },
-): RequestContextData {
-  const requestId = sanitizeClientId(header(req, REQUEST_ID_HEADER)) ?? requestContext.generateId();
-  const correlationId = sanitizeClientId(header(req, CORRELATION_ID_HEADER)) ?? requestId;
-
-  // The Fetch Request's `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.
-  const signal = req.signal;
-  // Client IP for per-IP rate limiting — resolved via the shared
-  // trustedProxyHops-aware resolver. Always set for
-  // an HTTP request; falls back to "unknown" rather than skipping the
-  // ip-bucket (see createClientIpResolver).
-  const resolver = options?.resolver ?? FALLBACK_CLIENT_IP_RESOLVER;
-  const ip = resolver.resolve({
-    header: (name) => header(req, name),
-    socketAddress: options?.socketAddress,
-  });
-  const userAgent = header(req, "user-agent");
-  // Runs before auth-middleware, so this reaches public routes too (e.g.
-  // signup-request) — that's the whole point: the active UI locale must
-  // survive to anonymous callers, not just authenticated ones.
-  const locale = resolveHeaderLocale({
-    headerLocale: header(req, LOCALE_HEADER_NAME),
-    acceptLanguage: header(req, "accept-language"),
-  });
-
-  return {
-    requestId,
-    correlationId,
-    startedAt: performance.now(),
-    ...(signal ? { signal } : {}),
-    ip,
-    ...(userAgent !== undefined ? { userAgent } : {}),
-    ...(locale !== undefined ? { locale } : {}),
-  };
-}
-
-/**
- * Builds the RequestContextData record for a Hono request. Thin wrapper
- * around `buildRequestContextDataFromRequest(c.req.raw)` — kept as its own
- * export because most call-sites (server.ts's httpRoute→systemQuery mount,
- * `requestIdMiddleware` below) already hold a Hono `Context`.
- */
-export function buildRequestContextData(
-  c: Context,
-  resolver?: ClientIpResolver,
-): RequestContextData {
-  // Older Hono / adapter combos may leave c.req.raw unset even though it's
-  // typed as Request — degrade to a bare id pair (no signal/ip/ua/locale)
-  // instead of letting req.headers.get() throw on every request.
-  if (!c.req.raw) {
-    const requestId = requestContext.generateId();
-    return { requestId, correlationId: requestId, startedAt: performance.now() };
-  }
-  return buildRequestContextDataFromRequest(c.req.raw, {
-    resolver,
-    socketAddress: extractSocketAddress(c.env),
-  });
-}
-
-/**
- * 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(options?: {
-  // Shared resolver instance — pass buildServer's single clientIpResolver
-  // here so the whole server shares one warn-once flag.
-  // Takes precedence over `trustedProxyHops`, which only exists for
-  // standalone callers (no buildServer).
-  readonly resolver?: ClientIpResolver;
-  readonly trustedProxyHops?: number;
-}) {
-  // Created once per middleware mount (not per request) so the warn-once
-  // flag in the resolver actually fires only once per server boot.
-  const resolver =
-    options?.resolver ??
-    createClientIpResolver(options?.trustedProxyHops ?? 0, "requestIdMiddleware");
-  return async (c: Context, next: Next) => {
-    const data = buildRequestContextData(c, resolver);
-    c.header(REQUEST_ID_HEADER, data.requestId);
-    c.header(CORRELATION_ID_HEADER, data.correlationId);
-    c.set("requestId", data.requestId);
-
-    await requestContext.run(data, () => next());
-  };
-}