@cosmicdrift/kumiko-framework 0.165.0 → 0.165.2

package/src/api/auth-routes.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
@@ -217,6 +218,12 @@ export type SessionCreator = (user: SessionUser, meta: SessionMetadata) => Promi
 // there's nothing to revoke.
 export type SessionRevoker = (sid: string) => Promise<void>;
 
+// Mass-revoke every live session for a user. Used by password-change and
+// "sign out everywhere" (sessions feature) and by auth-foundation's
+// SessionStore extension point — canonical home so both can re-export
+// the same type instead of restating it.
+export type SessionMassRevoker = (userId: string) => Promise<number>;
+
 // Status reported by the session-store to the auth-middleware. The concrete
 // type lives on auth-middleware to keep the tight coupling visible there;
 // auth-routes just re-uses the alias for the AuthRoutesConfig surface.
@@ -274,15 +281,21 @@ export type AuthRoutesConfig = {
   // /auth/mfa/preauth-enable-start dispatches { preauthSetupToken,
   // accountLabel } to this handler with a guest identity — no session is
   // minted, the response is just { setupToken, otpauthUri, recoveryCodes }
-  // (same shape as auth-mfa's own enable-start.write.ts). No dedicated
-  // rate-limiter here (unlike mfaVerifyRateLimit): the route already
-  // inherits the generic L2 authEndpointRateLimit on /api/auth/*, and this
-  // handler checks no TOTP code, so there's no per-account guessing
-  // surface to cap — that cap belongs on the later confirm handler.
+  // (same shape as auth-mfa's own enable-start.write.ts).
   mfaPreauthEnableStartHandler?: string;
   // Maps mfaPreauthEnableStartHandler error codes to HTTP status codes,
   // same pattern as mfaVerifyErrorStatusMap.
   mfaPreauthEnableStartErrorStatusMap?: Readonly<Record<string, number>>;
+  // Rate-limit for POST /auth/mfa/preauth-enable-start, keyed by client IP.
+  // Defaults to in-memory 10/5min. Pass `null` to disable. This route does
+  // NOT inherit the generic L2 authEndpointRateLimit on /api/auth/* by
+  // default (that's opt-in per-app via runProdApp's rateLimit.auth), and a
+  // preauthSetupToken is valid for the full setup-token TTL and not
+  // single-use until preauth-confirm burns it — an unrate-limited replay
+  // means every hit re-derives a fresh TOTP secret + 8 argon2id recovery-
+  // code hashes (recovery-codes.ts, Promise.all), a memory-hard CPU
+  // amplifier reachable from a single stolen/leaked token.
+  mfaPreauthEnableStartRateLimit?: LoginRateLimiter | null;
   // Optional: qualified write handler completing the enrollment started by
   // mfaPreauthEnableStartHandler — takes the secret-carrying setupToken
   // from that step plus a TOTP code. When set, POST /auth/mfa/preauth-
@@ -398,6 +411,20 @@ export type AuthRoutesConfig = {
   // subdomain can then forge authenticated state-changing requests. Prefer
   // setting `allowedOrigins`.
   unsafeSkipOriginCheck?: boolean;
+  // Number of trusted reverse-proxy hops between the client and this
+  // process that APPEND (not overwrite) their peer address to
+  // `x-forwarded-for` (e.g. nginx `$proxy_add_x_forwarded_for`). Used to
+  // derive the client IP for every auth rate-limiter (login, mfa-verify,
+  // preauth-enable-start, preauth-confirm) and for requestMeta's session
+  // IP — kumiko-framework#1539. Default 0 = legacy behavior, trust the
+  // first XFF entry (or x-real-ip) unconditionally; spoofable by design,
+  // kept as the default so unconfigured deployments don't regress into a
+  // shared "unknown" bucket (mfa-verify/preauth-confirm key on bare IP, no
+  // email composite — collapsing everyone into one bucket is a DoS worse
+  // than the spoofing hole). Set this to your real proxy hop count (1 for
+  // a single ingress/reverse-proxy, 2 for edge-LB + ingress, etc.) to close
+  // the hole; see clientIpOf's doc comment for the extraction algorithm.
+  trustedProxyHops?: number;
 };
 
 export type PasswordResetConfig = {
@@ -452,15 +479,86 @@ export type SignupConfig = {
   confirmHandler: string;
 };
 
+// Derives the caller IP from proxy headers, single source for the
+// rate-limiter keys below and requestMeta. kumiko-framework#1523/#1522/#1539:
+// `x-forwarded-for` is attacker-controlled unless we know how many trusted
+// proxy hops sit between the client and this process — `trustedProxyHops`
+// (AuthRoutesConfig) is that count.
+//
+//   hops === 0 (default): legacy behavior — trust the first XFF entry (or
+//   x-real-ip) at face value. Kept as the default so unconfigured
+//   deployments don't regress: collapsing everyone into a single "unknown"
+//   bucket would turn mfa-verify/preauth-confirm's pure-IP-keyed limiter
+//   into a one-request-locks-out-everyone DoS, which is worse than the
+//   spoofing hole this issue is about. Apps behind a proxy MUST set this to
+//   close the hole — see AuthRoutesConfig.trustedProxyHops.
+//
+//   hops >= 1: each trusted proxy appends (not overwrites) its peer address
+//   to XFF (e.g. nginx `$proxy_add_x_forwarded_for`), so the last `hops`
+//   entries are proxy-supplied and everything before them — including the
+//   real client — sits at `entries[length - hops]`. Anything the client
+//   itself prepended lands further left and is ignored. If the header has
+//   fewer entries than `hops`, the proxy chain is shorter than configured
+//   (misconfiguration or a bypassed hop) — fall back to x-real-ip when present,
+//   else "unknown". x-real-ip has no hop-count semantics (so it isn't used for
+//   hop math), but a shared "unknown" bucket is worse than trusting the
+//   proxy-set header when XFF is absent (common nginx X-Real-IP-only setups).
+//
+// Callers that need a hard boundary regardless of this config
+// (preauth-enable-start) additionally key on something the caller can't
+// freely choose (see preauthTokenKeyOf below).
+let warnedUnknownClientIp = false;
+function clientIpOf(
+  c: { req: { header(name: string): string | undefined } },
+  trustedProxyHops = 0,
+): string {
+  if (trustedProxyHops <= 0) {
+    return (
+      c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+      c.req.header("x-real-ip") ??
+      "unknown"
+    );
+  }
+  const entries = (c.req.header("x-forwarded-for") ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  if (entries.length < trustedProxyHops) {
+    // nginx often sets only X-Real-IP (no XFF). Prefer that over a shared
+    // "unknown" rate-limit bucket (fw#1555) — hop-count math still doesn't
+    // apply to X-Real-IP, but a shared bucket is worse than trusting the
+    // proxy-set header when the XFF chain is shorter than configured.
+    const realIp = c.req.header("x-real-ip")?.trim();
+    if (realIp) return realIp;
+    if (!warnedUnknownClientIp) {
+      warnedUnknownClientIp = true;
+      console.warn(
+        "[kumiko] trustedProxyHops>=1 but XFF chain too short and no x-real-ip — " +
+          'all such clients share the "unknown" rate-limit bucket. Check proxy headers.',
+      );
+    }
+    return "unknown";
+  }
+  return entries[entries.length - trustedProxyHops] ?? "unknown";
+}
+
+// Second rate-limit axis for preauth-enable-start: unlike the IP, a
+// preauthSetupToken isn't freely choosable by the attacker (it's minted by
+// login.write.ts), so hashing it into a bucket key still caps the replay
+// even when the IP-based bucket is bypassed via header rotation.
+function preauthTokenKeyOf(token: string): string {
+  return `preauth-token:${createHash("sha256").update(token).digest("hex")}`;
+}
+
 // Extract `ip` and `user-agent` for the sessionCreator.
 // Hono's `c.req.header(...)` returns undefined for missing headers; we coerce
 // them to "unknown" rather than throwing because auth-routes are a public
 // surface and we don't want header-sniffing bugs to break login.
-function requestMeta(c: { req: { header(name: string): string | undefined } }): SessionMetadata {
-  const ip =
-    c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-    c.req.header("x-real-ip") ??
-    "unknown";
+function requestMeta(
+  c: { req: { header(name: string): string | undefined } },
+  trustedProxyHops = 0,
+): SessionMetadata {
+  const ip = clientIpOf(c, trustedProxyHops);
   const userAgent = c.req.header("user-agent") ?? "unknown";
   return { ip, userAgent };
 }
@@ -534,6 +632,12 @@ export function createInMemoryLoginRateLimiter(
 // each replica its own bucket. namespace separates the login-key keyspace
 // from the mfa-verify one (they share the same LoginRateLimiter shape but
 // key on different values).
+// Fail-closed on Redis outage, unlike the in-memory limiter (which never
+// throws): `check`/`reset` propagate any Redis error, so callers 500
+// instead of falling back to unlimited attempts. Deliberate — Redis is
+// already required infra for a multi-replica deployment, and for a
+// security-relevant limiter "briefly unavailable" should read as "briefly
+// down", not "briefly unlimited".
 export function createRedisLoginRateLimiter(
   redis: Redis,
   maxAttempts = 10,
@@ -545,10 +649,26 @@ export function createRedisLoginRateLimiter(
   return {
     async check(key) {
       const redisKey = `${prefix}${key}`;
-      const count = await redis.incr(redisKey);
-      if (count === 1) {
-        await redis.pexpire(redisKey, windowMs);
-      }
+      // INCR then PEXPIRE was two round-trips: a crash/network blip between
+      // them (only possible right after count===1, when the key is fresh)
+      // left the key permanently without a TTL — the window never resets,
+      // the counter only grows, and the bucket is locked out until an
+      // operator manually resets/deletes the key. One atomic eval closes
+      // the gap: the TTL is set in the same script invocation that creates
+      // the key, so no observer (including a crash) can see count===1
+      // without the expiry already applied. The `PTTL < 0` branch also
+      // heals keys that already exist without a TTL from before this fix
+      // shipped (PTTL returns -1 for "no expiry set, key exists") — without
+      // it, those pre-existing keys would grow forever with no way back to
+      // a normal window.
+      const count = (await redis.eval(
+        `local c = redis.call('INCR', KEYS[1])
+         if c == 1 or redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+         return c`,
+        1,
+        redisKey,
+        windowMs,
+      )) as number;
       return count <= maxAttempts;
     },
     async reset(key) {
@@ -568,6 +688,21 @@ export function createAuthRoutes(
   // working. High-security apps can opt into "strict" — see AuthRoutesConfig.
   const cookieSameSite = config.cookieSameSite ?? "lax";
   const cookieDomain = config.cookieDomain;
+  // Single hop-count-aware IP getter for every rate-limit call site below —
+  // see AuthRoutesConfig.trustedProxyHops / clientIpOf's doc comment. Fail
+  // loud on a non-finite/negative value rather than letting it silently
+  // reach clientIpOf, where NaN/negative behaves like "chain too short"
+  // and collapses every request into the shared "unknown" bucket.
+  if (
+    config.trustedProxyHops !== undefined &&
+    (!Number.isInteger(config.trustedProxyHops) || config.trustedProxyHops < 0)
+  ) {
+    throw new Error(
+      `createAuthRoutes: trustedProxyHops must be a non-negative integer, got ${config.trustedProxyHops}.`,
+    );
+  }
+  const trustedProxyHops = config.trustedProxyHops ?? 0;
+  const getClientIp = (c: Context): string => clientIpOf(c, trustedProxyHops);
 
   // Shared tail of every route that ends a request logged-in: create the
   // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
@@ -577,7 +712,7 @@ export function createAuthRoutes(
   async function mintSessionAndRespond(c: Context, session: SessionUser): Promise<string> {
     let sessionForJwt = session;
     if (config.sessionCreator) {
-      const sid = await config.sessionCreator(session, requestMeta(c));
+      const sid = await config.sessionCreator(session, requestMeta(c, trustedProxyHops));
       sessionForJwt = { ...session, sid };
     }
     const token = await jwt.sign(sessionForJwt);
@@ -612,13 +747,7 @@ export function createAuthRoutes(
       }
       const body = parsed.data;
 
-      // Client IP derivation is shared between rate-limit check and reset,
-      // so compute once. Falls back to "unknown" when no proxy header is
-      // present — consistent bucket for direct-to-server test setups.
-      const clientIp =
-        c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-        c.req.header("x-real-ip") ??
-        "unknown";
+      const clientIp = getClientIp(c);
       const rateLimitKey = `${clientIp}|${body.email.toLowerCase()}`;
 
       if (rateLimiter) {
@@ -719,10 +848,7 @@ export function createAuthRoutes(
       }
       const body = parsed.data;
 
-      const clientIp =
-        c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-        c.req.header("x-real-ip") ??
-        "unknown";
+      const clientIp = getClientIp(c);
 
       if (rateLimiter) {
         const allowed = await rateLimiter.check(clientIp);
@@ -771,12 +897,17 @@ export function createAuthRoutes(
   // No JWT is minted here (unlike /auth/login and /auth/mfa/verify) — the
   // handler's response carries a secret-bearing setupToken that a later
   // pre-auth confirm step (the same shape auth-mfa's own enable-confirm
-  // consumes) verifies. No dedicated rate-limiter: see
-  // AuthRoutesConfig.mfaPreauthEnableStartHandler's doc comment for why
-  // the generic L2 /api/auth/* limiter is enough here.
+  // consumes) verifies. Rate-limited like mfaVerifyRateLimit/
+  // mfaPreauthConfirmRateLimit — a preauthSetupToken is valid and
+  // not-single-use for its whole TTL, so without this cap a replay is a
+  // memory-hard CPU amplifier (see AuthRoutesConfig doc comment).
   if (config.mfaPreauthEnableStartHandler) {
     const mfaPreauthEnableStartQn = config.mfaPreauthEnableStartHandler;
     const statusMap = config.mfaPreauthEnableStartErrorStatusMap ?? {};
+    const rateLimiter =
+      config.mfaPreauthEnableStartRateLimit === null
+        ? null
+        : (config.mfaPreauthEnableStartRateLimit ?? createInMemoryLoginRateLimiter());
 
     api.post(Routes.authMfaPreauthEnableStart, async (c) => {
       const raw = await c.req.json().catch(() => null);
@@ -786,6 +917,23 @@ export function createAuthRoutes(
       }
       const body = parsed.data;
 
+      const clientIp = getClientIp(c);
+
+      if (rateLimiter) {
+        const allowed = await rateLimiter.check(clientIp);
+        if (!allowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+        // Second axis, independent of the IP-derived bucket above: the
+        // preauthSetupToken is minted by login.write.ts and not freely
+        // choosable, so this cap survives an attacker rotating
+        // x-forwarded-for to bypass the IP bucket (kumiko-framework#1522).
+        const tokenAllowed = await rateLimiter.check(preauthTokenKeyOf(body.preauthSetupToken));
+        if (!tokenAllowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+      }
+
       const result = await dispatcher.write(mfaPreauthEnableStartQn, body, GUEST_USER);
 
       if (!result.isSuccess) {
@@ -839,10 +987,7 @@ export function createAuthRoutes(
       }
       const body = parsed.data;
 
-      const clientIp =
-        c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-        c.req.header("x-real-ip") ??
-        "unknown";
+      const clientIp = getClientIp(c);
 
       if (rateLimiter) {
         const allowed = await rateLimiter.check(clientIp);

package/src/api/index.ts

@@ -17,6 +17,7 @@ export type {
   LoginRateLimiter,
   SessionChecker,
   SessionCreator,
+  SessionMassRevoker,
   SessionMetadata,
   SessionRevoker,
 } from "./auth-routes";

package/src/api/jwt.ts

@@ -191,7 +191,13 @@ export function loadJwtSecretOrKeyring(
   const keys: Record<string, string> = {};
   for (const [name, value] of Object.entries(env)) {
     const match = name.match(JWT_KEY_VAR_PATTERN);
-    if (!match || !value) continue;
+    if (!match) continue;
+    if (!value) {
+      throw new Error(
+        `[jwt] ${name} is set but empty — an empty versioned secret is almost certainly a ` +
+          "deploy mistake, not an intentional skip. Unset the var entirely if it's unused.",
+      );
+    }
     assertMinLength(name, value);
     // biome-ignore lint/style/noNonNullAssertion: regex group 1 always present
     keys[`v${match[1]!}`] = value;
@@ -225,5 +231,20 @@ export function loadJwtSecretOrKeyring(
         `Check JWT_SECRET_V${currentRaw} is set.`,
     );
   }
+  // Carry the pre-rotation plain JWT_SECRET into the ring as a verify-only
+  // legacy key: sessions signed before JWT_SECRET_V<n> was first set have no
+  // `kid`, so verifyWithKeyring's no-kid fallback tries every key in `keys` —
+  // if the plain secret isn't one of them, every in-flight session breaks the
+  // moment rotation is adopted, exactly the mass-invalidation this keyring
+  // exists to avoid. Never becomes signKid — only JWT_SECRET_V<n> can sign.
+  // Retirement: has no automatic expiry — verifies unbounded as long as
+  // JWT_SECRET stays set. Operators must explicitly unset JWT_SECRET once
+  // max token TTL (`ttlSeconds`) has elapsed since cutover to actually
+  // retire a rotated-out secret (see run-prod-app.ts boot warning).
+  const legacySecret = env["JWT_SECRET"];
+  if (legacySecret) {
+    assertMinLength("JWT_SECRET", legacySecret);
+    keys["legacy"] = legacySecret;
+  }
   return { keys, signKid };
 }

package/src/api/routes.ts

@@ -19,7 +19,25 @@ import { patAllows } from "./pat-scope";
 import { requestContext } from "./request-context";
 import { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";
 
-export function createApiRoutes(dispatcher: Dispatcher) {
+// SSE frame event names for POST /api/stream. Parallel definition lives in
+// @cosmicdrift/kumiko-headless (dispatcher-live imports that one) — framework
+// cannot depend on headless for four string literals.
+export const StreamFrame = {
+  chunk: "chunk",
+  ping: "ping",
+  done: "done",
+  error: "error",
+} as const;
+
+export type ApiRoutesOptions = {
+  // Override the SSE heartbeat interval (ms). Default SSE_HEARTBEAT_INTERVAL_MS.
+  // Deployment-tunable for proxies with different idle timeouts — also used
+  // by tests with a short value to exercise the pre-pull race + ping path.
+  readonly sseHeartbeatMs?: number;
+};
+
+export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOptions = {}) {
+  const heartbeatMs = options.sseHeartbeatMs ?? SSE_HEARTBEAT_INTERVAL_MS;
   const api = new Hono();
 
   api.post(Routes.write, async (c) => {
@@ -124,35 +142,76 @@ export function createApiRoutes(dispatcher: Dispatcher) {
   });
 
   // Dispatcher-driven SSE, full auth/CSRF/rate-limit chain (unlike the
-  // broker-based /sse route). Frame contract for clients: "chunk" (one per
-  // yielded value, JSON-encoded), "ping" (heartbeat, empty data), "done"
-  // (terminal, empty data), "error" (terminal, JSON error envelope — the
-  // response status stays 200 since SSE headers are already flushed before
-  // dispatch gates run on the generator's first pull).
+  // broker-based /sse route). Frame contract for clients: StreamFrame.chunk
+  // (one per yielded value, JSON-encoded), .ping (heartbeat, empty data),
+  // .done (terminal, empty data), .error (terminal, JSON error envelope —
+  // only reachable once the stream is already open, i.e. failures from the
+  // second chunk onward). The generator's first `.next()` — which runs the
+  // dispatch gates (feature/rate-limit/access/validation) plus the handler's
+  // first yield — is raced against a heartbeat timeout BEFORE streamSSE, so
+  // a gate failure that settles in time maps to its real HTTP status via
+  // queryErrorResponse instead of a flushed-200 error frame (framework#1517).
   api.post(Routes.stream, async (c) => {
     const user = getUser(c);
     const body = await c.req.json<{ type: string; payload: unknown }>();
     const requestId = requestContext.get()?.requestId;
 
+    const generator = dispatcher.stream(body.type, body.payload, user);
     try {
       assertPatAllowed(user, body.type);
     } catch (e) {
       return queryErrorResponse(c, toKumiko(e), body.type);
     }
 
+    // stream.onAbort() only exists once streamSSE opens the response below.
+    // Hook the raw request signal directly so a client disconnect during the
+    // pre-pull still reclaims the generator instead of leaking a Redis
+    // subscription/DB cursor held open inside its still-unresolved first
+    // `.next()` (framework#1528).
+    const signal = c.req.raw.signal;
+    const onPrePullAbort = () => void generator.return(undefined);
+    signal.addEventListener("abort", onPrePullAbort);
+
+    const firstPull = generator.next();
+    let prePullTimer: ReturnType<typeof setTimeout> | undefined;
+    const settledInTime = await Promise.race([
+      firstPull.then(() => true).catch(() => true),
+      new Promise<false>((resolve) => {
+        prePullTimer = setTimeout(() => resolve(false), heartbeatMs);
+      }),
+    ]);
+    clearTimeout(prePullTimer);
+    signal.removeEventListener("abort", onPrePullAbort);
+
+    if (settledInTime) {
+      try {
+        await firstPull;
+      } catch (e) {
+        return queryErrorResponse(c, toKumiko(e), body.type);
+      }
+    }
+
+    if (signal.aborted) {
+      // Fire-and-forget: settledInTime === false means firstPull is by
+      // definition still pending — V8 queues a .return() request behind an
+      // in-flight .next(), so awaiting here would block the response until
+      // that pending pull resolves (which may be never for an idle stream).
+      void generator.return(undefined).catch(() => {});
+      return c.body(null, 499 as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+    }
+
     return streamSSE(c, async (stream) => {
-      const generator = dispatcher.stream(body.type, body.payload, user);
       stream.onAbort(() => {
         void generator.return(undefined);
       });
 
       try {
-        await pumpStream(stream, generator, SSE_HEARTBEAT_INTERVAL_MS);
+        await pumpStream(stream, generator, heartbeatMs, firstPull);
       } catch (e) {
         const err = toKumiko(e);
         logServerFault(err, requestId, body.type);
         const { error } = serializeError(err, requestId);
-        await stream.writeSSE({ event: "error", data: stringifyJson(error) });
+        await stream.writeSSE({ event: StreamFrame.error, data: stringifyJson(error) });
       }
     });
   });
@@ -164,40 +223,49 @@ export type SseWriter = {
   readonly writeSSE: (message: { readonly event: string; readonly data: string }) => Promise<void>;
 };
 
-// Pull loop for /api/stream: races each generator.next() against a
-// heartbeat timer so a slow/idle handler still keeps the connection alive
-// ("ping" frames), forwards yielded chunks as "chunk" frames, and emits
-// "done" once the generator completes. Factored out of the route handler
-// so the heartbeat/ping and abort/cleanup paths are unit-testable with a
-// fast heartbeatMs instead of only reachable through SSE_HEARTBEAT_INTERVAL_MS
-// (15s) in a full HTTP round-trip.
+// Races each generator.next() against a heartbeat timer so an idle handler keeps the SSE connection alive.
 export async function pumpStream(
   stream: SseWriter,
   generator: AsyncGenerator<unknown>,
   heartbeatMs: number,
+  // Pending (or already-settled) first `.next()` — see the /api/stream route,
+  // which races this against a heartbeat timeout before opening streamSSE.
+  firstPull?: Promise<IteratorResult<unknown>>,
 ): Promise<void> {
-  let pending = generator.next();
-  while (true) {
-    let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
-    const heartbeat = new Promise<"heartbeat">((resolve) => {
-      heartbeatTimer = setTimeout(() => resolve("heartbeat"), heartbeatMs);
-    });
-    let outcome: Awaited<typeof pending> | "heartbeat";
-    try {
-      outcome = await Promise.race([pending, heartbeat]);
-    } finally {
-      clearTimeout(heartbeatTimer);
-    }
+  let pending = firstPull ?? generator.next();
+  try {
+    while (true) {
+      let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
+      const heartbeat = new Promise<"heartbeat">((resolve) => {
+        heartbeatTimer = setTimeout(() => resolve("heartbeat"), heartbeatMs);
+      });
+      let outcome: Awaited<typeof pending> | "heartbeat";
+      try {
+        outcome = await Promise.race([pending, heartbeat]);
+      } finally {
+        clearTimeout(heartbeatTimer);
+      }
 
-    if (outcome === "heartbeat") {
-      await stream.writeSSE({ event: "ping", data: "" });
-      continue;
+      if (outcome === "heartbeat") {
+        await stream.writeSSE({ event: StreamFrame.ping, data: "" });
+        continue;
+      }
+      if (outcome.done) break;
+      await stream.writeSSE({
+        event: StreamFrame.chunk,
+        data: stringifyJson(outcome.value ?? null),
+      });
+      pending = generator.next();
     }
-    if (outcome.done) break;
-    await stream.writeSSE({ event: "chunk", data: stringifyJson(outcome.value) });
-    pending = generator.next();
+    await stream.writeSSE({ event: StreamFrame.done, data: "" });
+  } finally {
+    // Fire-and-forget: if writeSSE threw mid-loop, `pending` (the last
+    // generator.next()) may still be unresolved — V8 queues .return()
+    // behind an in-flight .next(), so awaiting here would hang until that
+    // pull settles (which may be never for a handler stuck on a dead
+    // Redis/DB subscription the disconnect just orphaned).
+    void generator.return(undefined).catch(() => {});
   }
-  await stream.writeSSE({ event: "done", data: "" });
 }
 
 function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode = 200) {

package/src/api/server.ts

@@ -34,6 +34,7 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher";
 import { createLifecycleHooks, type SystemHooks } from "../pipeline/lifecycle-pipeline";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context";
 import {
+  createAccessInvalidationEventConsumer,
   createJobTriggerEventConsumer,
   createSearchEventConsumer,
   createSseBroadcastEventConsumer,
@@ -113,7 +114,12 @@ export type ServerOptions = {
     // search enabled when the respective dependency (sseBroker /
     // context.searchAdapter) is available; jobTrigger enabled when a
     // jobRunner is wired via dispatcherOptions.
-    systemConsumers?: { sse?: boolean; search?: boolean; jobTrigger?: boolean };
+    systemConsumers?: {
+      sse?: boolean;
+      search?: boolean;
+      jobTrigger?: boolean;
+      accessInvalidation?: boolean;
+    };
     // Raw postgres.js client for LISTEN/NOTIFY wake-up (Sprint E.4). When
     // present, `.start()` subscribes to EVENTS_PUBSUB_CHANNEL — delivery
     // latency drops from pollIntervalMs to TCP-round-trip. The poll timer
@@ -153,6 +159,9 @@ export type ServerOptions = {
   // `undefined` → 1 MB default. `0` disables the limit entirely (tests
   // or bespoke deployments with a reverse-proxy that caps upstream).
   maxRequestBytes?: number;
+  // SSE heartbeat interval for POST /api/stream (ms). Omit → framework default.
+  // Tune down behind proxies with aggressive idle timeouts.
+  sseHeartbeatMs?: number;
   // Process lifecycle. When present:
   //   - GET /health/ready reflects lifecycle.state() (200 ready / 503 else)
   //   - eventDispatcher.stop() is auto-registered as a shutdown hook, so
@@ -379,6 +388,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const dispatcher = createDispatcher(options.registry, contextWithObservability, {
     ...options.dispatcherOptions,
     lifecycle,
+    sseBroker,
   });
 
   // Async event-dispatcher — the replacement for the old transactional
@@ -414,6 +424,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
   if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
     systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
   }
+  // Default ON (#1524 global-by-default). Tests that opt out of SSE via
+  // systemConsumers.accessInvalidation=false (test-stack mirrors sse off)
+  // skip the row so retention prune suites are not blocked by a lagging
+  // cursor=0 consumer they never drain.
+  const accessInvalidationEnabled =
+    options.eventDispatcher?.systemConsumers?.accessInvalidation ?? true;
+  if (accessInvalidationEnabled) {
+    systemConsumers.push(createAccessInvalidationEventConsumer(sseBroker));
+  }
 
   // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
   // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but
@@ -664,7 +683,12 @@ export function buildServer(options: ServerOptions): KumikoServer {
   if (options.auth) {
     app.route("/api", createAuthRoutes(dispatcher, jwt, options.auth));
   }
-  app.route("/api", createApiRoutes(dispatcher));
+  app.route(
+    "/api",
+    createApiRoutes(dispatcher, {
+      ...(options.sseHeartbeatMs !== undefined ? { sseHeartbeatMs: options.sseHeartbeatMs } : {}),
+    }),
+  );
   app.route("/api", createSseRoute(sseBroker));
 
   // Mount upload/download routes whenever a file provider is resolvable (a