@michaelthielemann/kestrel 1.2.1

package/layers/admin/app/utils/reauth.ts

@@ -0,0 +1,68 @@
+import { safeRedirect } from './safe-redirect'
+
+// The auth bootstrap endpoints the server always permits (login/session/logout). A 401 from these is
+// not a stale session — a wrong-password login 401s — so it must not trigger a re-auth redirect. Matched
+// exactly (not by `/api/auth/` prefix) so a guarded endpoint under a consumer collection named `auth`
+// (e.g. `/api/auth/5`) still re-authenticates.
+const BOOTSTRAP_PATHS = new Set(['/api/auth/login', '/api/auth/session', '/api/auth/logout'])
+
+/**
+ * Decide whether a failed `$fetch` should bounce the user to the login screen, and to which URL.
+ *
+ * Returns the login redirect target for a 401 raised by a guarded `/api/*` call made from inside the
+ * admin SPA — but stays null for:
+ *  - non-401 statuses and non-`/api` requests (nothing to re-authenticate);
+ *  - the auth-bootstrap endpoints (`/api/auth/*`): a wrong-password login 401s and must stay put;
+ *  - any location that isn't a safe admin redirect target — which also rules out the login page itself
+ *    (no redirect loop) and public/SSG pages (the static site never logs in).
+ */
+export function reauthTarget(input: { status: number; url: string; currentPath: string }): string | null {
+  if (input.status !== 401) return null
+  const path = apiPath(input.url)
+  if (!path.startsWith('/api/') || BOOTSTRAP_PATHS.has(path)) return null
+  // The current location must itself be a valid place to return to. `safeRedirect` rejects the login
+  // page and any non-admin path, so this single check guards both the loop and the public site.
+  const back = safeRedirect(input.currentPath)
+  if (!back) return null
+  return `/admin/login?redirect=${encodeURIComponent(back)}`
+}
+
+function apiPath(url: string): string {
+  // Tolerate absolute URLs (SSR/base-prefixed) and relative ones alike; fall back to the raw string.
+  try { return new URL(url, 'http://localhost').pathname } catch { return url }
+}
+
+/** Minimal shape of the ofetch `onResponseError` context this interceptor reads. */
+export interface ReauthContext {
+  request?: string | { url?: string } | URL
+  response?: { status?: number }
+}
+
+/**
+ * Build an `onResponseError` handler that re-authenticates on a stale-session 401. Pure dependency
+ * injection (current path / reset / navigate) keeps it unit-testable away from the Nuxt runtime; the
+ * client plugin wires it to the real router, `useAuth().reset` and `navigateTo`.
+ */
+export function makeReauthInterceptor(deps: {
+  currentPath: () => string
+  reset: () => void
+  navigate: (to: string) => void
+}) {
+  return (ctx: ReauthContext): void => {
+    const target = reauthTarget({
+      status: ctx.response?.status ?? 0,
+      url: requestUrl(ctx.request),
+      currentPath: deps.currentPath(),
+    })
+    if (!target) return
+    deps.reset()
+    deps.navigate(target)
+  }
+}
+
+function requestUrl(request: ReauthContext['request']): string {
+  if (typeof request === 'string') return request
+  if (request instanceof URL) return request.href
+  if (request && typeof request === 'object' && typeof request.url === 'string') return request.url
+  return ''
+}

package/layers/admin/app/utils/record-title.ts

@@ -0,0 +1,15 @@
+/**
+ * The text the editor header shows for a saved record: the `title` text field if present, else the first
+ * text field — the SAME pick `slugSourceValue` (core/page-slug) derives the auto-slug from, so the heading
+ * and the URL never disagree about which field is "the title".
+ *
+ * Returns `''` when there is no such field or its value is blank/non-string; the header then falls back to
+ * the generic "Edit {collection} #{id}" (an id is all a brand-new record has).
+ */
+export function recordTitle(fields: Record<string, { type: string }>, values: Record<string, unknown>): string {
+  const entries = Object.entries(fields)
+  const pick = entries.find(([k, f]) => k === 'title' && f.type === 'text') ?? entries.find(([, f]) => f.type === 'text')
+  if (!pick) return ''
+  const v = values[pick[0]]
+  return typeof v === 'string' ? v.trim() : ''
+}

package/layers/admin/app/utils/register-builtin-editors.ts

@@ -0,0 +1,9 @@
+import { registerCollectionEditor } from './editor-registry'
+import FieldsBody from '../components/FieldsBody.vue'
+import BlocksBody from '../components/BlocksBody.vue'
+
+// Built-in editor bodies. Registered as an import side-effect (CollectionEditor imports this module), so
+// they are present before any editor renders — the same guarantee the field registry's static map gives.
+// Extensions add their own types via a `*.client.ts` plugin (auto-discovered through `extends`).
+registerCollectionEditor('fields', FieldsBody)
+registerCollectionEditor('blocks', BlocksBody)

package/layers/admin/app/utils/safe-redirect.ts

@@ -0,0 +1,12 @@
+/**
+ * Validate a post-login redirect target. Only local `/admin` paths are allowed —
+ * never external/protocol-relative URLs, and never `/admin/login` (no redirect loop).
+ */
+export function safeRedirect(target: unknown): string | null {
+  if (typeof target !== 'string') return null
+  if (target.startsWith('//')) return null
+  const local = target === '/admin' || target.startsWith('/admin/') || target.startsWith('/admin?')
+  if (!local) return null
+  if (target === '/admin/login' || target.startsWith('/admin/login?') || target.startsWith('/admin/login/')) return null
+  return target
+}

package/layers/admin/nuxt.config.ts

@@ -0,0 +1,17 @@
+export default defineNuxtConfig({
+  routeRules: {
+    // The admin is a client-rendered SPA.
+    '/admin/**': { ssr: false },
+  },
+  modules: [
+    // The field-widget gallery (/admin/gallery) is a dev-only showcase — strip it from the
+    // production admin SPA so it never ships to end users.
+    (_options, nuxt) => {
+      nuxt.hook('pages:extend', (pages) => {
+        if (nuxt.options.dev) return
+        const i = pages.findIndex((p) => p.file?.endsWith('/admin/gallery.vue'))
+        if (i !== -1) pages.splice(i, 1)
+      })
+    },
+  ],
+})

package/layers/auth/nuxt.config.ts

@@ -0,0 +1 @@
+export default defineNuxtConfig({})

package/layers/auth/server/api/auth/login.post.ts

@@ -0,0 +1,38 @@
+export default defineEventHandler(async (event) => {
+  const ip = clientIp(event)
+  const key = throttleKey(ip)
+  const now = Date.now()
+  assertBodyLimit(getRequestHeader(event, 'content-length'))
+  // Reserve the attempt up front (assert-not-locked + record, atomically — no await in between) so
+  // concurrent in-flight guesses from the same IP all count toward the cap before the slow hash runs.
+  // The failure is already recorded here; a successful login clears it below.
+  reserveLoginAttempt(key, now)
+  const body = await readBody(event)
+  const password = typeof body?.password === 'string' ? body.password : ''
+
+  let stored: string
+  try {
+    // No hash configured → login is impossible: surface a distinct 503 instead of a confusing 401.
+    stored = requireAdminHash()
+  } catch (error) {
+    // A server-side misconfiguration nobody can guess their way past: refund the reservation so the admin
+    // isn't still locked out once they set the hash. The slot-busy 503 below stays billable by contrast —
+    // it IS attacker-triggerable, and charging it is what makes a flood run into the lockout.
+    releaseLoginAttempt(key, now)
+    throw error
+  }
+  acquireHashSlot()
+  let ok: boolean
+  try {
+    ok = await verifyPassword(password, stored)
+  } finally {
+    releaseHashSlot()
+  }
+
+  if (!ok) {
+    throw createError({ statusCode: 401, statusMessage: 'Invalid credentials' })
+  }
+  clearLoginFailures(key)
+  const exp = setAuthSession(event)
+  return { ok: true, exp }
+})

package/layers/auth/server/api/auth/logout.post.ts

@@ -0,0 +1,9 @@
+export default defineEventHandler((event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  // Clear the cookie for THIS client AND bump the revocation epoch so any other copy of the token (a synced
+  // backup, a leaked log, another device) is invalidated server-side immediately — a real logout, not just a
+  // cookie clear. Single admin ⇒ logout = logout-everywhere, which is the expected behaviour.
+  clearAuthSession(event)
+  bumpSessionEpoch()
+  return { ok: true }
+})

package/layers/auth/server/api/auth/session.get.ts

@@ -0,0 +1 @@
+export default defineEventHandler((event) => getAuthSession(event))

package/layers/auth/server/utils/admin-credential.ts

@@ -0,0 +1,42 @@
+import { createError } from 'h3'
+
+type Env = Record<string, string | undefined>
+
+/** The configured admin password hash, or `undefined` when `KESTREL_ADMIN_PASSWORD_HASH` is unset/empty. */
+export function adminPasswordHash(env: Env = process.env): string | undefined {
+  const stored = env.KESTREL_ADMIN_PASSWORD_HASH
+  return typeof stored === 'string' && stored.length > 0 ? stored : undefined
+}
+
+let warned = false
+function warnNotConfigured(): void {
+  if (warned) return
+  warned = true
+  console.warn(
+    '[kestrel auth] admin login is not configured — set KESTREL_ADMIN_PASSWORD_HASH to enable sign-in',
+  )
+}
+
+/**
+ * Resolve the admin password hash for a login attempt, or fail loudly when it is unset.
+ *
+ * A missing `KESTREL_ADMIN_PASSWORD_HASH` means login is *impossible*, not that a credential was wrong —
+ * answering with the generic 401 makes an operator who simply forgot to set the hash chase a phantom
+ * "wrong password". So we surface a distinct **503** (plus a one-time server warning) for that case only.
+ *
+ * Security: this distinguishes solely the *unconfigured* server. A configured server still answers every
+ * bad credential with an opaque 401, so it never leaks which part (user/password) failed. Short-circuiting
+ * here is safe — a 503 already states plainly that login is unconfigured, so there is no timing signal to
+ * protect.
+ */
+export function requireAdminHash(env: Env = process.env, warn: () => void = warnNotConfigured): string {
+  const stored = adminPasswordHash(env)
+  if (!stored) {
+    warn()
+    throw createError({
+      statusCode: 503,
+      statusMessage: 'admin login is not configured (set KESTREL_ADMIN_PASSWORD_HASH)',
+    })
+  }
+  return stored
+}

package/layers/auth/server/utils/client-ip.ts

@@ -0,0 +1,88 @@
+import { getRequestIP, getRequestHeader } from 'h3'
+import type { H3Event } from 'h3'
+
+type Env = Record<string, string | undefined>
+
+/**
+ * How many reverse-proxy hops to trust in front of the app, parsed from `KESTREL_TRUST_PROXY`.
+ *
+ * Default **0** == trust nothing == ignore `X-Forwarded-For` entirely (without a proxy in front, XFF is
+ * fully attacker-controlled). `true`/`on`/`yes`/`1` == one trusted proxy; a positive integer == that many
+ * chained trusted proxies (e.g. CDN → load balancer). Anything else (`false`/`0`/blank/garbage) == 0.
+ */
+export function trustProxyDepth(env: Env = process.env): number {
+  const raw = (env.KESTREL_TRUST_PROXY ?? '').trim().toLowerCase()
+  if (!raw) return 0
+  if (raw === 'true' || raw === 'on' || raw === 'yes') return 1
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : 0
+}
+
+/**
+ * Pick the client address from an `X-Forwarded-For` chain, counting `depth` hops from the RIGHT.
+ *
+ * XFF is appended left-to-right (`client, proxy1, proxy2`), so the entries a client can forge sit on the
+ * LEFT and the right-most entry is the address our nearest trusted proxy actually observed. With one
+ * trusted proxy (depth 1) we take the right-most entry; with N chained trusted proxies we skip the N-1
+ * proxy hops and take the Nth-from-right. (h3's own `getRequestIP({ xForwardedFor: true })` takes the
+ * LEFT-most — spoofable — value, which is exactly why we don't use it.)
+ *
+ * If the chain is shorter than the trusted depth, it didn't traverse the expected proxies → untrustworthy,
+ * so we return `undefined` and let the caller fall back to the socket peer rather than honour a forged value.
+ */
+export function forwardedForHop(header: string | undefined, depth: number): string | undefined {
+  if (depth < 1) return undefined
+  const parts = (header ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+  const idx = parts.length - depth
+  return idx >= 0 ? parts[idx] : undefined
+}
+
+/**
+ * The client IP used to key the login throttle.
+ *
+ * Trusting `X-Forwarded-For` unconditionally lets a direct client rotate the header to dodge the per-IP
+ * limit, so by default we key on the socket peer address and ignore XFF. Only when `KESTREL_TRUST_PROXY`
+ * declares a trusted proxy depth do we honour the correct (right-most) XFF hop; a missing/too-short chain
+ * still falls back to the peer.
+ */
+export function clientIp(event: H3Event, env: Env = process.env): string {
+  const depth = trustProxyDepth(env)
+  if (depth > 0) {
+    const forwarded = forwardedForHop(getRequestHeader(event, 'x-forwarded-for'), depth)
+    if (forwarded) return forwarded
+  }
+  return getRequestIP(event) ?? 'unknown'
+}
+
+/** Expand a syntactically valid IPv6 address (optionally `::`-compressed) into its 8 hextets, or `null`. */
+function ipv6Hextets(ip: string): string[] | null {
+  const compressAt = ip.indexOf('::')
+  if (compressAt === -1) {
+    const groups = ip.split(':')
+    return groups.length === 8 ? groups : null
+  }
+  if (ip.indexOf('::', compressAt + 1) !== -1) return null // more than one '::' is not valid IPv6
+  const left = ip.slice(0, compressAt)
+  const right = ip.slice(compressAt + 2)
+  const leftGroups = left === '' ? [] : left.split(':')
+  const rightGroups = right === '' ? [] : right.split(':')
+  const missing = 8 - leftGroups.length - rightGroups.length
+  if (missing < 0) return null
+  return [...leftGroups, ...Array(missing).fill('0'), ...rightGroups]
+}
+
+/**
+ * The key used to bucket the login throttle: an IPv4 (and IPv4-mapped `::ffff:a.b.c.d`) address stays a
+ * full /32 — NAT already shares those legitimately, so widening the bucket there would throttle unrelated
+ * users behind the same NAT. A real IPv6 address is coarsened to its first four hextets (a /64), the block
+ * an ISP typically routes to a single customer — otherwise an attacker on a routed /64 binds a fresh source
+ * address per request and `recentFails` never sees the same key twice, so the throttle bounds nothing.
+ * Anything that isn't well-formed IPv4 or IPv6 (including the `unknown` fallback) is returned unchanged,
+ * which is only ever as permissive as the pre-existing full-address key.
+ */
+export function throttleKey(ip: string): string {
+  if (ip.includes('.') || !ip.includes(':')) return ip
+  const hextets = ipv6Hextets(ip)
+  if (!hextets) return ip
+  return hextets.slice(0, 4).join(':') + '::/64'
+}

package/layers/auth/server/utils/login-throttle.ts

@@ -0,0 +1,126 @@
+import { createError } from 'h3'
+
+export const MAX_LOGIN_BODY = 4096
+export const MAX_INFLIGHT_HASHES = 4
+
+export function assertBodyLimit(contentLength: string | undefined, maxBytes = MAX_LOGIN_BODY): void {
+  const len = Number(contentLength)
+  // A missing/garbage Content-Length means a chunked transfer, which readBody would buffer with no
+  // ceiling — refuse it. The only legitimate login body is a tiny JSON object with a known length.
+  if (contentLength === undefined || !Number.isFinite(len) || len < 0) {
+    throw createError({ statusCode: 411, statusMessage: 'Length required' })
+  }
+  if (len > maxBytes) {
+    throw createError({ statusCode: 413, statusMessage: 'Payload too large' })
+  }
+}
+
+export const MAX_LOGIN_FAILS = 10
+export const LOGIN_WINDOW_MS = 15 * 60 * 1000
+// Hard ceiling on the number of distinct IPs tracked at once. A login POST is anonymously reachable and
+// seeds an entry BEFORE the expensive scrypt runs, so without a bound a spray from many distinct source
+// addresses (e.g. a routed IPv6 /64 or a botnet) could grow this map without limit and OOM the process.
+// Generous vs any real login volume for a single-admin CMS; eviction (below) keeps memory bounded.
+export const MAX_TRACKED_IPS = 10_000
+
+// Per-IP failed-attempt timestamps (in-memory, per-process: resets on restart, fine for a
+// single-instance private CMS). Bounds online brute-force; the admin password entropy is the
+// primary defense. The keying IP comes from `clientIp` (socket peer by default; trusted
+// X-Forwarded-For hop only when KESTREL_TRUST_PROXY is set). Bounded by MAX_TRACKED_IPS + eviction.
+const loginFails = new Map<string, number[]>()
+
+function recentFails(ip: string, nowMs: number): number[] {
+  const fresh = (loginFails.get(ip) ?? []).filter((t) => nowMs - t < LOGIN_WINDOW_MS)
+  // DELETE rather than persist an empty array: an IP whose failures have all aged out (or that only ever
+  // hit the read-path lockout check) must not leave a permanent entry — otherwise a distinct-IP flood of
+  // one-shot addresses grows the map forever (every key would be reclaimed only by a *successful* login).
+  if (fresh.length === 0) loginFails.delete(ip)
+  else loginFails.set(ip, fresh)
+  return fresh
+}
+
+/** Reclaim every entry whose newest failure has aged past the window (a cheap sweep run under pressure). */
+function evictExpired(nowMs: number): void {
+  for (const [ip, times] of loginFails) {
+    const newest = times[times.length - 1]
+    if (newest === undefined || nowMs - newest >= LOGIN_WINDOW_MS) loginFails.delete(ip)
+  }
+}
+
+export function assertNotLockedOut(ip: string, nowMs: number): void {
+  if (recentFails(ip, nowMs).length >= MAX_LOGIN_FAILS) {
+    throw createError({ statusCode: 429, statusMessage: 'Too many attempts, try again later' })
+  }
+}
+
+export function recordFailedLogin(ip: string, nowMs: number): void {
+  const fails = recentFails(ip, nowMs)
+  fails.push(nowMs)
+  loginFails.set(ip, fails)
+  // Enforce the ceiling: first reclaim anything already expired, then, if still over budget, evict the
+  // oldest-inserted entries (Map preserves insertion order → FIFO). Evicting a live entry merely resets that
+  // IP's throttle — acceptable under memory pressure; the primary brute-force defense is password entropy.
+  if (loginFails.size > MAX_TRACKED_IPS) {
+    evictExpired(nowMs)
+    while (loginFails.size > MAX_TRACKED_IPS) {
+      const oldest = loginFails.keys().next().value
+      if (oldest === undefined) break
+      loginFails.delete(oldest)
+    }
+  }
+}
+
+export function clearLoginFailures(ip: string): void {
+  loginFails.delete(ip)
+}
+
+/** Test/introspection helpers: current tracked-IP count and a full reset (the store is a module singleton). */
+export function loginFailIpCount(): number {
+  return loginFails.size
+}
+export function clearAllLoginFailures(): void {
+  loginFails.clear()
+}
+
+/**
+ * Atomically reserve a login attempt: assert the IP isn't locked out AND record the attempt in one
+ * synchronous step (no await between the check and the record). This makes the throttle a true
+ * reservation — concurrent in-flight guesses, each awaiting a slow scrypt verify, all count toward the
+ * cap up front, instead of every one passing the gate on the same pre-increment count. The handler
+ * clears the reservation on a successful login; a failed login leaves it recorded.
+ */
+export function reserveLoginAttempt(ip: string, nowMs: number): void {
+  assertNotLockedOut(ip, nowMs)
+  recordFailedLogin(ip, nowMs)
+}
+
+/**
+ * Undo a `reserveLoginAttempt` reservation for an outage no caller could have caused or guessed past (no
+ * admin hash configured) — otherwise a misconfigured deployment leaves the admin throttled once they fix
+ * it. Deliberately NOT used for attacker-triggerable rejections: charging those is what makes a flood run
+ * into the lockout. Removes one entry equal to `nowMs` (there is at most one per call, recorded
+ * synchronously by the reservation this undoes; entries are interchangeable by value, so it doesn't
+ * matter which one a concurrent same-millisecond request added).
+ */
+export function releaseLoginAttempt(ip: string, nowMs: number): void {
+  const fails = loginFails.get(ip)
+  if (!fails) return
+  const idx = fails.lastIndexOf(nowMs)
+  if (idx === -1) return
+  fails.splice(idx, 1)
+  if (fails.length === 0) loginFails.delete(ip)
+  else loginFails.set(ip, fails)
+}
+
+let inFlight = 0
+
+export function acquireHashSlot(): void {
+  if (inFlight >= MAX_INFLIGHT_HASHES) {
+    throw createError({ statusCode: 503, statusMessage: 'Busy, try again' })
+  }
+  inFlight++
+}
+
+export function releaseHashSlot(): void {
+  if (inFlight > 0) inFlight--
+}

package/layers/auth/server/utils/password.ts

@@ -0,0 +1,52 @@
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const scryptAsync = promisify(scrypt) as (
+  password: string | Buffer,
+  salt: string | Buffer,
+  keylen: number,
+  options: { N: number; r: number; p: number; maxmem: number },
+) => Promise<Buffer>
+
+const N = 2 ** 17
+const R = 8
+const P = 1
+const KEYLEN = 64
+const MAXMEM = 256 * 1024 * 1024
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16)
+  const hash = await scryptAsync(password, salt, KEYLEN, { N, r: R, p: P, maxmem: MAXMEM })
+  return `scrypt$${N}$${R}$${P}$${salt.toString('base64url')}$${hash.toString('base64url')}`
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const parts = stored.split('$')
+  if (parts.length !== 6 || parts[0] !== 'scrypt') return false
+  const n = Number(parts[1])
+  const r = Number(parts[2])
+  const p = Number(parts[3])
+  if (!Number.isInteger(n) || !Number.isInteger(r) || !Number.isInteger(p)) return false
+
+  let salt: Buffer
+  let expected: Buffer
+  try {
+    salt = Buffer.from(parts[4], 'base64url')
+    expected = Buffer.from(parts[5], 'base64url')
+  } catch {
+    return false
+  }
+  if (expected.length === 0) return false
+
+  let actual: Buffer
+  try {
+    actual = await scryptAsync(password, salt, expected.length, { N: n, r, p, maxmem: MAXMEM })
+  } catch {
+    return false
+  }
+  if (actual.length !== expected.length) {
+    timingSafeEqual(actual, actual)
+    return false
+  }
+  return timingSafeEqual(actual, expected)
+}

package/layers/auth/server/utils/session-cookie.ts

@@ -0,0 +1,44 @@
+import { getCookie, setCookie, type H3Event } from 'h3'
+import { signSession, verifySession, sessionSettings, shouldRefreshSession } from './session'
+
+/** Shared session-cookie attributes; only `maxAge` differs between set and clear. */
+const baseCookieOptions = (secure: boolean) => ({
+  httpOnly: true,
+  secure,
+  sameSite: 'strict' as const,
+  path: '/',
+})
+
+export function setAuthSession(event: H3Event): number {
+  const { secret, maxAge, secureCookies, cookieName } = sessionSettings()
+  const exp = Date.now() + maxAge * 1000
+  setCookie(event, cookieName, signSession(secret, exp), { ...baseCookieOptions(secureCookies), maxAge })
+  return exp
+}
+
+export function clearAuthSession(event: H3Event): void {
+  const { secureCookies, cookieName } = sessionSettings()
+  setCookie(event, cookieName, '', { ...baseCookieOptions(secureCookies), maxAge: 0 })
+}
+
+export function getAuthSession(event: H3Event): { authenticated: boolean; exp?: number } {
+  const { secret, cookieName } = sessionSettings()
+  const result = verifySession(secret, getCookie(event, cookieName), Date.now())
+  return result.valid ? { authenticated: true, exp: result.exp } : { authenticated: false }
+}
+
+/**
+ * Sliding-expiry: on an authenticated request whose session has passed the halfway point of the idle
+ * window, re-issue the cookie with a fresh exp — so activity keeps the admin logged in and inactivity
+ * longer than `maxAge` auto-logs-out (the cookie AND the embedded exp lapse). No-op when there is no valid
+ * session cookie (anonymous / public requests), so it is safe to call unconditionally on every request.
+ */
+export function refreshAuthSession(event: H3Event): void {
+  const { secret, maxAge, secureCookies, cookieName } = sessionSettings()
+  const now = Date.now()
+  const current = verifySession(secret, getCookie(event, cookieName), now)
+  if (!current.valid || current.exp === undefined) return
+  if (!shouldRefreshSession(current.exp, now, maxAge * 1000)) return
+  const exp = now + maxAge * 1000
+  setCookie(event, cookieName, signSession(secret, exp), { ...baseCookieOptions(secureCookies), maxAge })
+}

package/layers/auth/server/utils/session-epoch.ts

@@ -0,0 +1,96 @@
+import { readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { resolveServerKestrel, serverRuntimeConfig } from '../../../core/server/utils/server-config'
+
+// The session REVOCATION epoch: a monotonic counter folded into the signing key (see deriveSigningKey), so
+// bumping it invalidates every outstanding token at once — the stateless model's server-side "hard logout".
+// Persisted to a file in the data dir so it survives a restart. Cached in-process, but the cache is
+// mtime-validated on read, so a bump by a SIBLING process (a `db:migrate` task, a second worker, a CLI
+// force-logout) is observed on the next request instead of only after a restart.
+
+let cached: number | undefined
+let cachedMtimeMs = -1
+
+/** Where the epoch persists: `KESTREL_SESSION_EPOCH_FILE`, else next to the DB. Null for a `:memory:` DB
+ *  (tests) → the epoch still works in-process, it just doesn't survive a restart. */
+function epochPath(): string | null {
+  const override = process.env.KESTREL_SESSION_EPOCH_FILE?.trim()
+  if (override) return override
+  // Resolve the DB the same way useDb() does — the consumer's `kestrel: { db }` via runtimeConfig first,
+  // Kestrel's own config + env only as the non-Nitro fallback. Landing anywhere else would put revocation
+  // state outside the volume the operator persists, so a restart would resurrect revoked sessions.
+  const fromRc = serverRuntimeConfig()?.kestrel as { dbPath?: string } | undefined
+  const dbPath = fromRc?.dbPath || resolveServerKestrel().dbPath
+  if (!dbPath || dbPath === ':memory:') return null
+  return join(dirname(dbPath), '.kestrel-session-epoch')
+}
+
+/** `null` means "couldn't tell" (unreadable, or present but not a valid epoch) — distinct from the genuine
+ *  ENOENT baseline of 0, so a caller never mistakes "the file is broken" for "never revoked". */
+function readEpoch(path: string): number | null {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return 0
+    console.error('[kestrel auth] could not read the session epoch file (keeping the last known epoch):', (error as Error)?.message ?? error)
+    return null
+  }
+  const n = parseInt(raw.trim(), 10)
+  if (Number.isFinite(n) && n >= 0) return n
+  console.error(`[kestrel auth] session epoch file has unreadable content, ignoring it (keeping the last known epoch): ${JSON.stringify(raw.slice(0, 40))}`)
+  return null
+}
+
+/** The file's mtime in ms, or -1 when absent/unreadable (a stable sentinel distinct from any real mtime). */
+function epochMtime(path: string): number {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return -1
+  }
+}
+
+/** The current epoch. Cached in-process, but re-read from the file whenever its mtime moved — so a
+ *  cross-process bump takes effect on the next call, not only after a restart. The stat is one cheap
+ *  syscall per request (no content read on the common unchanged path). */
+export function currentSessionEpoch(): number {
+  const path = epochPath()
+  if (!path) {
+    // No persistence (`:memory:`): the in-process bump is the only source of truth.
+    if (cached === undefined) cached = 0
+    return cached
+  }
+  const mtime = epochMtime(path)
+  if (cached === undefined || mtime !== cachedMtimeMs) {
+    // A `null` read (broken file) must never regress an already-higher in-process value — take the max
+    // rather than adopting it outright, the same guard bumpSessionEpoch already applies to its own re-read.
+    cached = Math.max(cached ?? 0, readEpoch(path) ?? 0)
+    cachedMtimeMs = mtime
+  }
+  return cached
+}
+
+/** Revoke every currently-issued session (logout / force-logout): increment + persist the epoch so the
+ *  derived signing key changes and all outstanding tokens fail verification immediately. Best-effort
+ *  persistence — a failed write still revokes for this process's lifetime (the in-process bump). */
+export function bumpSessionEpoch(): void {
+  const next = currentSessionEpoch() + 1
+  cached = next
+  const path = epochPath()
+  if (!path) return
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, String(next), 'utf8')
+    // Re-read AFTER writing and take the max: a sibling process may have written a HIGHER epoch between our
+    // write and this read. The epoch is monotonic, so max is correct — and it closes the write→stat TOCTOU
+    // where adopting only our own mtime+value could permanently mask a concurrent revocation.
+    cached = Math.max(next, readEpoch(path) ?? 0)
+    cachedMtimeMs = epochMtime(path)
+  } catch (error) {
+    console.error('[kestrel auth] could not persist session epoch (revocation holds for this process only):', (error as Error)?.message ?? error)
+  }
+}
+
+/** Test hook: drop the in-process cache so a test controls the epoch via its file/env. */
+export function _resetSessionEpochCache(): void { cached = undefined; cachedMtimeMs = -1 }