@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/api/index.ts

@@ -2,22 +2,30 @@ export type { SetTenantCookieOptions } from "./anonymous-cookie";
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie";
 export type {
   AnonymousAccessConfig,
+  AnonymousAccessResolved,
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,
   TenantExists,
+  TenantLifecycleStatusResolver,
   TenantResolver,
+  TokenVerifier,
 } from "./auth-middleware";
-export { authMiddleware, getUser } from "./auth-middleware";
+export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";
 export type {
   AuthRoutesConfig,
   LoginRateLimiter,
   SessionChecker,
   SessionCreator,
+  SessionMassRevoker,
   SessionMetadata,
   SessionRevoker,
 } from "./auth-routes";
-export { createAuthRoutes, createInMemoryLoginRateLimiter } from "./auth-routes";
+export {
+  createAuthRoutes,
+  createInMemoryLoginRateLimiter,
+  createRedisLoginRateLimiter,
+} from "./auth-routes";
 export type { CachedResponseInit, CachePolicy } from "./http-cache";
 export {
   cacheControlHeader,
@@ -28,8 +36,9 @@ export {
   etagMatches,
   parseIfNoneMatch,
 } from "./http-cache";
-export type { JwtHelper, JwtPayload } from "./jwt";
-export { createJwtHelper } from "./jwt";
+export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt";
+export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt";
+export { patAllows, qnMatches } from "./pat-scope";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";

package/src/api/jwt.ts

@@ -23,10 +23,82 @@ export type JwtPayload = {
 export type JwtHelper = {
   sign(user: SessionUser): Promise<string>;
   verify(token: string): Promise<JwtPayload>;
+  // The TTL this helper signs tokens with, in seconds — the single source for
+  // callers (e.g. the auth-cookie's maxAge) that must stay coupled to the JWT's exp.
+  readonly ttlSeconds: number;
 };
 
-export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
-  const encodedSecret = new TextEncoder().encode(secret);
+// kid → secret. All entries verify; `signKid` picks the sign-key. Rotation:
+// add the new kid, flip signKid, keep the old kid around until in-flight
+// tokens expire.
+export type JwtKeyring = {
+  readonly keys: Readonly<Record<string, string>>;
+  readonly signKid: string;
+};
+
+type NormalizedKeyring = {
+  readonly verifyKeys: ReadonlyMap<string, Uint8Array>;
+  readonly signKid: string | undefined;
+  readonly signKey: Uint8Array;
+};
+
+function normalizeKeyring(secretOrKeyring: string | JwtKeyring): NormalizedKeyring {
+  if (typeof secretOrKeyring === "string") {
+    const key = new TextEncoder().encode(secretOrKeyring);
+    return { verifyKeys: new Map(), signKid: undefined, signKey: key };
+  }
+
+  const verifyKeys = new Map<string, Uint8Array>();
+  for (const [kid, secret] of Object.entries(secretOrKeyring.keys)) {
+    verifyKeys.set(kid, new TextEncoder().encode(secret));
+  }
+  const signKey = verifyKeys.get(secretOrKeyring.signKid);
+  if (!signKey) {
+    throw new Error(
+      `createJwtHelper: signKid "${secretOrKeyring.signKid}" is not present in the keyring`,
+    );
+  }
+  return { verifyKeys, signKid: secretOrKeyring.signKid, signKey };
+}
+
+// Tokens carry `kid` in the protected header when signed from a keyring — pick the
+// matching verify-key directly. Tokens without `kid` (single-secret form, or in-flight
+// tokens signed before a rotation) fall back to trying every verify-key.
+async function verifyWithKeyring(token: string, keyring: NormalizedKeyring, issuer: string) {
+  const { kid } = jose.decodeProtectedHeader(token);
+  if (typeof kid === "string" && keyring.verifyKeys.size > 0) {
+    const key = keyring.verifyKeys.get(kid);
+    if (!key) {
+      throw new Error(`JWT verification failed: unknown kid "${kid}"`);
+    }
+    return jose.jwtVerify(token, key, { issuer });
+  }
+
+  // ponytail: tries every key in the ring (O(keys) per legacy-token verify) — fine for a
+  // rotation window of a handful of keys, revisit if the keyring ever grows large.
+  const candidates =
+    keyring.verifyKeys.size > 0 ? [...keyring.verifyKeys.values()] : [keyring.signKey];
+  let lastError: unknown;
+  for (const key of candidates) {
+    try {
+      return await jose.jwtVerify(token, key, { issuer });
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new Error("JWT verification failed: no matching key");
+}
+
+const DEFAULT_JWT_TTL_SECONDS = 24 * 60 * 60;
+
+export function createJwtHelper(
+  secretOrKeyring: string | JwtKeyring,
+  issuer = "kumiko",
+  ttlSeconds = DEFAULT_JWT_TTL_SECONDS,
+): JwtHelper {
+  const keyring = normalizeKeyring(secretOrKeyring);
 
   return {
     async sign(user) {
@@ -36,24 +108,29 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       };
       if (user.claims) body.claims = { ...user.claims };
 
+      const header: jose.JWTHeaderParameters = keyring.signKid
+        ? { alg: "HS256", kid: keyring.signKid }
+        : { alg: "HS256" };
+
+      // iat/exp share one `now` — jose's setIssuedAt()/setExpirationTime(Date)
+      // each read the clock separately, letting `exp - iat` drift by a
+      // second and making TTL-precision tests flaky.
+      const nowSec = Math.floor(Date.now() / 1000);
       const builder = new jose.SignJWT(body)
-        .setProtectedHeader({ alg: "HS256" })
+        .setProtectedHeader(header)
         .setSubject(String(user.id))
         .setIssuer(issuer)
-        .setIssuedAt()
-        .setExpirationTime("24h");
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + ttlSeconds);
       if (user.sid) builder.setJti(user.sid);
 
-      return builder.sign(encodedSecret);
+      return builder.sign(keyring.signKey);
     },
 
     async verify(token) {
-      const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
+      const { payload } = await verifyWithKeyring(token, keyring, issuer);
 
-      // Defence in depth: a valid signature does not guarantee well-formed claims. A
-      // leaked secret, key confusion, or a hand-crafted token can still carry junk —
-      // validate the claim shape and reject (verify() throws → 401 in auth-middleware)
-      // instead of casting blindly.
+      // defence-in-depth: valid sig ≠ well-formed claims; malformed payload → throw → 401
       const tenantId = parseTenantId(payload["tenantId"]);
       if (tenantId === null) {
         throw new Error("JWT payload validation failed: tenantId claim is missing or malformed");
@@ -87,5 +164,87 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       }
       return result;
     },
+    ttlSeconds,
   };
 }
+
+const JWT_KEY_VAR_PATTERN = /^JWT_SECRET_V(\d+)$/;
+const JWT_CURRENT_VERSION_VAR = "JWT_SECRET_CURRENT_VERSION";
+// Mirrors authEmailPasswordEnvSchema's JWT_SECRET.min(32) — HS256 minimum.
+// JWT_SECRET_V<n> bypasses that zod schema entirely (it only validates the
+// plain JWT_SECRET name), so this loader is the only gate for the rotation path.
+const MIN_JWT_SECRET_LENGTH = 32;
+
+function assertMinLength(name: string, value: string): void {
+  if (value.length < MIN_JWT_SECRET_LENGTH) {
+    throw new Error(`[jwt] ${name} must be ≥${MIN_JWT_SECRET_LENGTH} chars (HS256 minimum)`);
+  }
+}
+
+// Env-loader for createJwtHelper's secret-or-keyring param, analog to
+// secrets' loadKeyring: JWT_SECRET_V<n> (+ JWT_SECRET_CURRENT_VERSION picking
+// the active signKid) for rotation, falling back to plain JWT_SECRET when no
+// JWT_SECRET_V<n> is set — so a non-rotating deployment needs no new env vars.
+export function loadJwtSecretOrKeyring(
+  env: Readonly<Record<string, string | undefined>>,
+): string | JwtKeyring {
+  const keys: Record<string, string> = {};
+  for (const [name, value] of Object.entries(env)) {
+    const match = name.match(JWT_KEY_VAR_PATTERN);
+    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;
+  }
+
+  // skip: no JWT_SECRET_V<n> found — single-secret fallback.
+  if (Object.keys(keys).length === 0) {
+    const secret = env["JWT_SECRET"];
+    if (!secret) {
+      throw new Error(
+        "[jwt] JWT_SECRET not set — set JWT_SECRET for a single key, or " +
+          "JWT_SECRET_V1 (+ JWT_SECRET_CURRENT_VERSION=1) for a rotatable keyring.",
+      );
+    }
+    assertMinLength("JWT_SECRET", secret);
+    return secret;
+  }
+
+  const currentRaw = env[JWT_CURRENT_VERSION_VAR];
+  if (!currentRaw) {
+    throw new Error(
+      `[jwt] ${JWT_CURRENT_VERSION_VAR} not set — explicit current-version required ` +
+        "so adding a new JWT_SECRET_V<n> doesn't auto-promote it to the sign key.",
+    );
+  }
+  const signKid = `v${currentRaw}`;
+  if (!keys[signKid]) {
+    throw new Error(
+      `[jwt] ${JWT_CURRENT_VERSION_VAR}="${currentRaw}" not present in the keyring ` +
+        `(have versions: ${Object.keys(keys).sort().join(", ")}). ` +
+        `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/pat-scope.ts

@@ -0,0 +1,14 @@
+// QN scope-matching for Personal Access Tokens. A token's granted scopes
+// expand (in the PAT feature's resolver) to QN globs like "credit:write:*" or
+// "credit:query:credit:list". A glob ending in "*" matches any dispatch type
+// sharing the prefix; otherwise it is an exact match. Fail-closed: an empty
+// allow-list matches nothing, so a PAT with no scopes can call nothing.
+
+export function qnMatches(pattern: string, type: string): boolean {
+  if (pattern.endsWith("*")) return type.startsWith(pattern.slice(0, -1));
+  return pattern === type;
+}
+
+export function patAllows(allowedQns: readonly string[], type: string): boolean {
+  return allowedQns.some((pattern) => qnMatches(pattern, type));
+}

package/src/api/pii-leak-guard.ts

@@ -0,0 +1,47 @@
+import type { MiddlewareHandler } from "hono";
+import { configuredPiiSubjectKms, PII_CIPHERTEXT_PREFIX } from "../crypto";
+
+const isProductionEnv = () => process.env["NODE_ENV"] === "production";
+// Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
+// older/decrypt-only format version still present in unmigrated rows.
+const CIPHERTEXT_MARKER = "kumiko-pii:v";
+const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
+
+// A PII subject ciphertext never belongs in an API response — its presence
+// means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
+// fail loud (500) so a forgotten decrypt turns the first integration test
+// red; prod redacts + logs instead of shipping the blob. Skipped entirely
+// when no subject KMS is configured (no ciphertexts can exist).
+export function piiCiphertextResponseGuard(): MiddlewareHandler {
+  return async (c, next) => {
+    await next();
+    // skip: no subject KMS configured — no ciphertexts can exist, nothing to scan
+    if (configuredPiiSubjectKms() === undefined) return;
+    const contentType = c.res.headers.get("content-type") ?? "";
+    // skip: only JSON bodies carry handler data — streams/zips stay untouched
+    if (!contentType.includes("application/json")) return;
+    const text = await c.res.clone().text();
+    // skip: clean response — the common case
+    if (!text.includes(CIPHERTEXT_MARKER)) return;
+
+    const detail =
+      `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +
+      `("${PII_CIPHERTEXT_PREFIX}…") — a raw DB read leaked to the API surface. ` +
+      `Decrypt before returning (decryptStoredPii / executor read path).`;
+    if (!isProductionEnv()) {
+      c.res = Response.json(
+        { error: { code: "pii_ciphertext_leak", httpStatus: 500, message: detail } },
+        { status: 500 },
+      );
+      // skip: response replaced with the loud 500 above — nothing left to do
+      return;
+    }
+    console.error(detail);
+    const headers = new Headers(c.res.headers);
+    headers.delete("content-length");
+    c.res = new Response(text.replace(CIPHERTEXT_RE, "[pii-redacted]"), {
+      status: c.res.status,
+      headers,
+    });
+  };
+}

package/src/api/request-context.ts

@@ -30,6 +30,9 @@ export type RequestContextData = {
   // Populated by requestIdMiddleware from x-forwarded-for or the
   // socket address. Undefined 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;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();

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

@@ -37,12 +37,14 @@ export function requestIdMiddleware() {
     // than fabricate one.
     const xff = c.req.header("x-forwarded-for");
     const ip = xff?.split(",")[0]?.trim();
+    const userAgent = c.req.header("user-agent");
     await requestContext.run(
       {
         requestId,
         correlationId,
         ...(signal ? { signal } : {}),
         ...(ip && ip.length > 0 ? { ip } : {}),
+        ...(userAgent !== undefined ? { userAgent } : {}),
       },
       () => next(),
     );

package/src/api/routes.ts

@@ -1,6 +1,9 @@
 import { type Context, Hono } from "hono";
+import { streamSSE } from "hono/streaming";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { SessionUser } from "../engine/types/handlers";
 import {
+  AccessDeniedError,
   type KumikoError,
   reraiseAsKumikoError,
   serializeError,
@@ -12,9 +15,29 @@ import type { Dispatcher } from "../pipeline/dispatcher";
 import { stringifyJson } from "../utils/safe-json";
 import { Routes } from "./api-constants";
 import { getUser } from "./auth-middleware";
+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 (framework-owned; dispatcher-live
+// has no dependency on this package and keeps its own copy in sse-stream.ts —
+// a drift between the two fails the real-HTTP frame assertions in api.test.ts).
+export const StreamFrame = {
+  chunk: "chunk",
+  ping: "ping",
+  done: "done",
+  error: "error",
+} as const;
+
+export type ApiRoutesOptions = {
+  // Override the SSE heartbeat interval (ms). Production uses
+  // SSE_HEARTBEAT_INTERVAL_MS; tests pass a short value so the pre-pull
+  // race + ping path can be exercised without a 15s wait.
+  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) => {
@@ -22,6 +45,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown; requestId?: string }>();
 
     try {
+      assertPatAllowed(user, body.type);
       const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
       if (!result.isSuccess) {
         return writeErrorResponse(c, reraiseAsKumikoError(result.error), body.type);
@@ -59,6 +83,9 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     }
 
     try {
+      if (user.pat) {
+        for (const cmd of body.commands) assertPatAllowed(user, cmd.type);
+      }
       const result = await dispatcher.batch(body.commands, user, body.requestId);
       if (!result.isSuccess) {
         const err = reraiseAsKumikoError(result.error);
@@ -83,7 +110,8 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       }
       return c.json(result);
     } catch (e) {
-      return writeErrorResponse(c, toKumiko(e));
+      // single "type" doesn't apply to a batch; command types keep the fault context.
+      return writeErrorResponse(c, toKumiko(e), body.commands?.map((cmd) => cmd.type).join(","));
     }
   });
 
@@ -92,6 +120,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPatAllowed(user, body.type);
       const result = await dispatcher.query(body.type, body.payload, user);
       return jsonResponse(c, { data: result });
     } catch (e) {
@@ -104,6 +133,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPatAllowed(user, body.type);
       await dispatcher.command(body.type, body.payload, user);
       return c.json({ ok: true }, 202);
     } catch (e) {
@@ -111,15 +141,152 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     }
   });
 
+  // Dispatcher-driven SSE, full auth/CSRF/rate-limit chain (unlike the
+  // 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) => {
+      stream.onAbort(() => {
+        void generator.return(undefined);
+      });
+
+      try {
+        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: StreamFrame.error, data: stringifyJson(error) });
+      }
+    });
+  });
+
   return api;
 }
 
+export type SseWriter = {
+  readonly writeSSE: (message: { readonly event: string; readonly data: string }) => Promise<void>;
+};
+
+// 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 = 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: StreamFrame.ping, data: "" });
+        continue;
+      }
+      if (outcome.done) break;
+      await stream.writeSSE({
+        event: StreamFrame.chunk,
+        data: stringifyJson(outcome.value ?? null),
+      });
+      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(() => {});
+  }
+}
+
 function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode = 200) {
   return c.body(stringifyJson(body), status, { "Content-Type": "application/json" });
 }
 
 const toKumiko = toKumikoError;
 
+// PAT scope enforcement at the API boundary. No-op for cookie/JWT users
+// (user.pat undefined → unrestricted). For a PAT-authenticated request the
+// dispatch type must match one of the token's granted-scope QN globs, else
+// 403 — fail-closed, thrown so each route's existing catch shapes the body.
+function assertPatAllowed(user: SessionUser, type: string): void {
+  if (user.pat && !patAllows(user.pat.allowedQns, type)) {
+    throw new AccessDeniedError({
+      message: `personal access token scope does not permit ${type}`,
+      details: { handler: type, scopes: user.pat.scopes },
+    });
+  }
+}
+
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero