@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/api/auth-middleware.ts

@@ -17,9 +17,9 @@ export const CSRF_COOKIE_NAME = "kumiko_csrf";
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
 
 // Prefix that marks a bearer token as a long-lived Personal Access Token
-// rather than a JWT session. The PAT feature mints tokens with this prefix;
-// the middleware uses it to route to patResolver instead of jwt.verify. Kept
-// here so both sides import the same literal.
+// rather than a JWT session. The personal-access-tokens feature mints tokens
+// with this prefix and declares it as its tokenVerifier shape (kind:
+// "prefix") — kept here so both sides import the same literal.
 export const PAT_TOKEN_PREFIX = "kpat_";
 
 // Which wire the current request authenticated over. Downstream
@@ -47,13 +47,13 @@ export type AuthSessionChecker = (
   expectedUserId: string,
 ) => Promise<AuthSessionStatus>;
 
-// Resolves a raw Personal Access Token (bearer, prefixed PAT_TOKEN_PREFIX)
-// into a SessionUser, or null when the token is unknown/revoked/expired. The
-// PAT feature owns the DB-backed implementation: hash the token, look up the
-// row, resolve the user's CURRENT roles live (not a snapshot), and expand the
-// token's granted scopes into `pat.allowedQns`. Middleware just consults it
-// and short-circuits the JWT path on a hit.
-export type PatResolver = (rawToken: string) => Promise<SessionUser | null>;
+// Resolves a raw bearer token into a SessionUser, or null when no registered
+// provider claims it (or the claiming provider rejects it as unknown/revoked/
+// expired). Wired generically from the auth-foundation `tokenVerifier`
+// extension-point registry — the middleware has no PAT/JWT-specific
+// knowledge, it just consults whatever the app wired in and short-circuits
+// the JWT path on a hit.
+export type TokenVerifier = (rawToken: string) => Promise<SessionUser | null>;
 
 export type TenantLifecycleStatusResolver = (
   tenantId: TenantId,
@@ -64,15 +64,13 @@ export type AuthMiddlewareOptions = {
   // reports anything other than "live", the request is rejected with 401.
   // Omit to run in stateless-JWT mode (any valid JWT is accepted).
   readonly sessionChecker?: AuthSessionChecker;
-  // Called for bearer tokens carrying the PAT prefix, BEFORE jwt.verify. On a
-  // hit the middleware sets the returned SessionUser and skips the JWT path
-  // entirely. Omit to disable PAT auth (bearer PATs then fail jwt.verify → 401).
-  readonly patResolver?: PatResolver;
-  // When true, a JWT WITHOUT a sid is rejected. Leave false during rollout
-  // so already-issued stateless JWTs keep working until they expire; flip
-  // to true once the server has been emitting sid for longer than the JWT
-  // TTL. Has no effect when sessionChecker is undefined.
-  readonly strictMode?: boolean;
+  // Called for bearer tokens, BEFORE jwt.verify. On a hit the middleware
+  // sets the returned SessionUser and skips the JWT path entirely; on a
+  // miss (null) falls through to jwt.verify. Wired from the auth-foundation
+  // `tokenVerifier` extension-point registry — generic across providers
+  // (PAT, future JWT-provider, ...), the middleware itself has no
+  // provider-specific knowledge. Omit to disable non-JWT bearer auth.
+  readonly tokenVerifier?: TokenVerifier;
   // Opt-in: when set, requests without a JWT are treated as anonymous
   // callers instead of being rejected with 401. The middleware synthesises
   // a SessionUser with id="anonymous" and roles=["anonymous"], scoped to a
@@ -222,13 +220,7 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const {
-    sessionChecker,
-    strictMode = false,
-    anonymousAccess,
-    patResolver,
-    resolveTenantLifecycleStatus,
-  } = options;
+  const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus } = options;
 
   // Fail loud at boot, not silently at request time: a tenantResolver
   // without a declared resolverTrust is an ambiguous trust decision no
@@ -282,11 +274,17 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
     const { token, transport } = extracted;
 
-    // PAT path: a bearer token carrying the PAT prefix is a long-lived
-    // Personal Access Token, not a JWT. Short-circuit the JWT path entirely.
-    // Cookie transport is never a PAT (the browser holds the JWT).
-    if (patResolver && transport === "bearer" && token.startsWith(PAT_TOKEN_PREFIX)) {
-      return await handlePat(c, patResolver, token, next, resolveTenantLifecycleStatus);
+    // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
+    // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
+    // entirely; a miss (null — no provider's shape matched, or the matching
+    // provider rejected the token) falls through to the normal JWT flow below,
+    // which rejects it uniformly as invalid_token. Cookie transport is never
+    // routed here (the browser holds the JWT).
+    if (tokenVerifier && transport === "bearer") {
+      const verifiedUser = await tokenVerifier(token);
+      if (verifiedUser) {
+        return await handleVerifiedBearerUser(c, verifiedUser, next, resolveTenantLifecycleStatus);
+      }
     }
 
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
@@ -302,15 +300,16 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
 
     // Session liveness check — only when both a checker is wired AND the
-    // token carries a sid. strictMode governs the no-sid case below so that
-    // both old JWTs (no sid) and rolling-deploy gaps can be handled.
+    // token carries a sid.
+    // A checker wired without a sid on the token means the token predates
+    // session tracking (or the JWT was forged) — reject.
     if (sessionChecker) {
       if (payload.jti) {
         const status = await sessionChecker(payload.jti, payload.sub);
         if (status !== "live") {
           return sessionInvalid(c, status);
         }
-      } else if (strictMode) {
+      } else {
         return sessionInvalid(c, "no_sid");
       }
     }
@@ -360,49 +359,39 @@ export function getAuthTransport(c: Context): AuthTransport | undefined {
   return c.get(AUTH_TRANSPORT_KEY) as AuthTransport | undefined;
 }
 
-// PAT request flow. Resolve the hashed token → SessionUser (live roles +
-// granted scopes), then apply the same X-Tenant-mismatch guard as the JWT
-// path before continuing. A null resolve is an invalid/revoked/expired token
-// → 401. Structured like handleAnonymous so authMiddleware stays flat.
-async function handlePat(
+// Verified-bearer request flow. `user` was already resolved by the wired
+// tokenVerifier (PAT today, future JWT-provider). Apply the same
+// X-Tenant-mismatch guard as the JWT path before continuing. Structured like
+// handleAnonymous so authMiddleware stays flat.
+async function handleVerifiedBearerUser(
   c: Context,
-  patResolver: PatResolver,
-  token: string,
+  user: SessionUser,
   next: Next,
   resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
-  const patUser = await patResolver(token);
-  if (!patUser) {
-    return middlewareReject(c, {
-      code: "invalid_token",
-      status: 401,
-      message: "personal access token invalid, revoked or expired",
-      i18nKey: "auth.errors.invalidToken",
-    });
-  }
-  // The PAT carries its own tenant; an X-Tenant header pointing elsewhere is a
-  // confused client — reject loudly, same stance as the JWT path.
+  // The token carries its own tenant; an X-Tenant header pointing elsewhere is
+  // a confused client — reject loudly, same stance as the JWT path.
   const headerTenant = c.req.header(TENANT_HEADER_NAME);
-  if (headerTenant !== undefined && headerTenant !== patUser.tenantId) {
+  if (headerTenant !== undefined && headerTenant !== user.tenantId) {
     return middlewareReject(c, {
       code: "tenant_mismatch",
       status: 400,
-      message: "PAT tenantId and X-Tenant header disagree",
+      message: "token tenantId and X-Tenant header disagree",
       i18nKey: "auth.errors.tenantMismatch",
-      details: { patTenantId: patUser.tenantId, headerTenantId: headerTenant },
+      details: { tokenTenantId: user.tenantId, headerTenantId: headerTenant },
     });
   }
-  c.set(USER_KEY, patUser);
+  c.set(USER_KEY, user);
   c.set(AUTH_TRANSPORT_KEY, "bearer");
   const lifecycleReject = await rejectIfTenantTeardown(
     c,
-    patUser.tenantId,
+    user.tenantId,
     resolveTenantLifecycleStatus,
   );
   if (lifecycleReject) return lifecycleReject;
   await next();
-  // skip: PAT path completed — next() ran; explicit return keeps the
-  // Response|undefined union honest (same as handleAnonymous).
+  // skip: verified-bearer path completed — next() ran; explicit return keeps
+  // the Response|undefined union honest (same as handleAnonymous).
   return;
 }
 

package/src/api/auth-routes.ts

@@ -1,6 +1,7 @@
 import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
+import type Redis from "ioredis";
 import { z } from "zod";
 import { buildSessionRoles } from "../engine/membership-roles";
 import { createSystemUser } from "../engine/system-user";
@@ -15,17 +16,11 @@ import {
   type AuthSessionStatus,
   CSRF_COOKIE_NAME,
   getUser,
-  type PatResolver,
+  type TokenVerifier,
 } from "./auth-middleware";
 import type { JwtHelper } from "./jwt";
 import { generateToken } from "./tokens";
 
-// Cookie lifetime must track the JWT's exp claim — both are issued together,
-// both reference the same session. jwt.ts's createJwtHelper hardcodes
-// setExpirationTime("24h"); if that ever becomes configurable this constant
-// follows it.
-const JWT_TTL_SECONDS = 24 * 60 * 60;
-
 // Resolves the Secure cookie flag. Locked off in dev/test so Playwright
 // against http://localhost:… can actually receive the cookie. Production
 // flips it on — browsers drop Secure cookies on http, so a misconfigured
@@ -47,6 +42,10 @@ function setAuthCookies(
     csrfToken: string;
     sameSite: "lax" | "strict";
     domain?: string | undefined;
+    // Cookie lifetime must track the JWT's exp claim — both are issued
+    // together, both reference the same session. Callers pass jwt.ttlSeconds
+    // so the two never drift apart.
+    ttlSeconds: number;
   },
 ): void {
   const sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
@@ -54,7 +53,7 @@ function setAuthCookies(
     secure: cookieSecure(),
     sameSite,
     path: "/",
-    maxAge: JWT_TTL_SECONDS,
+    maxAge: opts.ttlSeconds,
     ...(opts.domain !== undefined && { domain: opts.domain }),
   } as const;
 
@@ -261,14 +260,11 @@ export type AuthRoutesConfig = {
   // at login, check it here on every request. Leaving this empty disables
   // the revocation path — old JWTs stay valid until they expire naturally.
   sessionChecker?: SessionChecker;
-  // When true, a JWT WITHOUT a sid is rejected. Use during deploy-rollouts
-  // once all fresh JWTs emit a sid and the legacy stateless tokens are
-  // expected to have expired. Default false keeps old tokens working.
-  sessionStrictMode?: boolean;
-  // Resolves bearer Personal Access Tokens (PAT_TOKEN_PREFIX) into a
-  // SessionUser, consulted BEFORE jwt.verify. Wired by the
-  // personal-access-tokens feature; unwired = PAT auth disabled.
-  patResolver?: PatResolver;
+  // Resolves bearer tokens (any registered auth-foundation `tokenVerifier`
+  // provider — PAT today, future JWT-provider), consulted BEFORE jwt.verify.
+  // Wired by run-prod-app/run-dev-app when at least one provider feature is
+  // mounted; unwired = no non-JWT bearer auth.
+  tokenVerifier?: TokenVerifier;
   // Per-token request-rate limiter for PAT-authenticated requests, keyed by
   // the token id (SessionUser.pat.tokenId). Cookie/JWT requests are unaffected.
   // Reuses the LoginRateLimiter shape (a generic keyed check/reset limiter).
@@ -287,6 +283,12 @@ export type AuthRoutesConfig = {
   passwordReset?: PasswordResetConfig;
   // Email-verification flow. Symmetric to passwordReset.
   emailVerification?: EmailVerificationConfig;
+  // Account-unlock flow (#1266). When wired, POST
+  // /auth/request-account-unlock + /auth/confirm-account-unlock are
+  // mounted as public routes. Confirm needs no extra body field
+  // (token-only, like email-verification) — the handler only clears the
+  // Redis lockout state, no entity write.
+  accountUnlock?: AccountUnlockConfig;
   // Self-Signup (Magic-Link). Wenn wired, mountet POST
   // /auth/signup-request + /auth/signup-confirm. Confirm returnt JWT-
   // Cookie + Session-Body wie login.
@@ -357,6 +359,13 @@ export type EmailVerificationConfig = {
   confirmHandler: string;
 };
 
+export type AccountUnlockConfig = {
+  requestHandler: string;
+  // Token-only body (mirrors EmailVerificationConfig) — no entity write, so
+  // there's no newPassword-equivalent field.
+  confirmHandler: string;
+};
+
 // Tenant-Invite Magic-Link. Drei Accept-Branches für klare Separation:
 //   - acceptHandler: logged-in User akzeptiert via JWT (Branch 1)
 //   - acceptWithLoginHandler: anon User mit existing email (Branch 2)
@@ -461,6 +470,37 @@ export function createInMemoryLoginRateLimiter(
   };
 }
 
+// Redis-backed sibling of createInMemoryLoginRateLimiter — same fixed-window
+// semantics (count <= maxAttempts allows, window anchored on first hit), but
+// shared across replicas via INCR/PEXPIRE instead of an in-process Map.
+// runProdApp defaults to this: an in-memory limiter only rate-limits within
+// a single instance, so a multi-replica prod deployment would silently give
+// 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).
+export function createRedisLoginRateLimiter(
+  redis: Redis,
+  maxAttempts = 10,
+  windowMs = 5 * 60_000,
+  namespace = "login",
+): LoginRateLimiter {
+  const prefix = `kumiko:auth:ratelimit:${namespace}:`;
+
+  return {
+    async check(key) {
+      const redisKey = `${prefix}${key}`;
+      const count = await redis.incr(redisKey);
+      if (count === 1) {
+        await redis.pexpire(redisKey, windowMs);
+      }
+      return count <= maxAttempts;
+    },
+    async reset(key) {
+      await redis.del(`${prefix}${key}`);
+    },
+  };
+}
+
 export function createAuthRoutes(
   dispatcher: Dispatcher,
   jwt: JwtHelper,
@@ -486,7 +526,13 @@ export function createAuthRoutes(
     }
     const token = await jwt.sign(sessionForJwt);
     const csrfToken = generateToken();
-    setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
+    setAuthCookies(c, {
+      token,
+      csrfToken,
+      sameSite: cookieSameSite,
+      domain: cookieDomain,
+      ttlSeconds: jwt.ttlSeconds,
+    });
     return token;
   }
 
@@ -697,6 +743,26 @@ export function createAuthRoutes(
     });
   }
 
+  // Account-unlock mirrors email-verification (token-only confirm body) —
+  // clears the Redis lockout state instead of an entity field, see
+  // confirm-account-unlock.write.ts.
+  if (config.accountUnlock) {
+    const au = config.accountUnlock;
+    registerTokenRequestRoute({
+      api,
+      dispatcher,
+      path: Routes.authRequestAccountUnlock,
+      requestHandler: au.requestHandler,
+    });
+    registerTokenConfirmRoute({
+      api,
+      dispatcher,
+      path: Routes.authConfirmAccountUnlock,
+      confirmHandler: au.confirmHandler,
+      schema: VerifyEmailBody,
+    });
+  }
+
   // Self-Signup (Magic-Link). Request mountet wie reset/verify den
   // silent-success-Pfad mit Token-Mail. Confirm ist anders: returnt
   // SessionUser → die Route mintet JWT + setzt Cookies (Auto-Login

package/src/api/index.ts

@@ -5,10 +5,10 @@ export type {
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,
-  PatResolver,
   TenantExists,
   TenantLifecycleStatusResolver,
   TenantResolver,
+  TokenVerifier,
 } from "./auth-middleware";
 export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";
 export type {
@@ -19,7 +19,11 @@ export type {
   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,
@@ -30,8 +34,8 @@ 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";

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,19 +108,27 @@ 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: valid sig ≠ well-formed claims; malformed payload → throw → 401
       const tenantId = parseTenantId(payload["tenantId"]);
@@ -84,5 +164,66 @@ 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 || !value) continue;
+    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.`,
+    );
+  }
+  return { keys, signKid };
+}

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

@@ -2,7 +2,10 @@ import type { MiddlewareHandler } from "hono";
 import { configuredPiiSubjectKms, PII_CIPHERTEXT_PREFIX } from "../crypto";
 
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
-const CIPHERTEXT_RE = /kumiko-pii:v1:[^"\s<>\\]*/g;
+// 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
@@ -19,7 +22,7 @@ export function piiCiphertextResponseGuard(): MiddlewareHandler {
     if (!contentType.includes("application/json")) return;
     const text = await c.res.clone().text();
     // skip: clean response — the common case
-    if (!text.includes(PII_CIPHERTEXT_PREFIX)) return;
+    if (!text.includes(CIPHERTEXT_MARKER)) return;
 
     const detail =
       `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +

package/src/api/server.ts

@@ -50,7 +50,7 @@ import { PUBLIC_API_PATHS } from "./api-constants";
 import { type AnonymousAccessConfig, authMiddleware, getUser } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
-import { createJwtHelper, type JwtHelper } from "./jwt";
+import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
@@ -69,8 +69,13 @@ import { createSseRoute } from "./sse-route";
 export type ServerOptions = {
   registry: Registry;
   context: AppContext;
-  jwtSecret: string;
+  jwtSecret: string | JwtKeyring;
   jwtIssuer?: string;
+  // JWT lifetime in seconds. Explicit always wins. When omitted, the default
+  // depends on `auth.sessionChecker`: wired (revocation possible) keeps the
+  // long-lived 24h default; unwired (stateless JWTs, no revocation) drops to
+  // 1h so a leaked stateless token has a much smaller exposure window.
+  jwtTtl?: number;
   dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
   systemHooks?: SystemHooks;
   eventDedup?: EventDedup;
@@ -94,6 +99,8 @@ export type ServerOptions = {
     pollIntervalMs?: number;
     batchSize?: number;
     maxAttempts?: number;
+    rearmCooldownMs?: number;
+    maxRearmCount?: number;
     // Opt out of building the dispatcher even if consumers exist — e.g. ops
     // runs a dedicated dispatcher process, or a test needs to control the
     // consumer lifecycle manually.
@@ -238,7 +245,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
     );
   }
 
-  const jwt = createJwtHelper(options.jwtSecret, options.jwtIssuer);
+  // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
+  // TTL than session-backed ones, since a leaked stateless token can't be
+  // revoked and stays valid until it expires. Explicit jwtTtl always wins.
+  const defaultJwtTtl = options.auth?.sessionChecker ? 24 * 60 * 60 : 60 * 60;
+  const jwt = createJwtHelper(
+    options.jwtSecret,
+    options.jwtIssuer,
+    options.jwtTtl ?? defaultJwtTtl,
+  );
   const sseBroker = options.sseBroker ?? createSseBroker();
 
   // Resolve the per-process instance identifier. Prefer explicit
@@ -566,8 +581,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // middleware can reject revoked sids on every request.
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
-    ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
-    ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
+    ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
     ...(options.auth?.resolveTenantLifecycleStatus
       ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
       : {}),