@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/api/__tests__/jwt.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import * as jose from "jose";
 import type { SessionUser } from "../../engine/types";
-import { createJwtHelper } from "../jwt";
+import { createJwtHelper, loadJwtSecretOrKeyring } from "../jwt";
 
 const SECRET = "test-secret-at-least-32-characters-long-aa";
 const TENANT = "11111111-1111-4111-8111-111111111111";
@@ -83,3 +83,152 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
     await expect(jwt.verify(token)).rejects.toThrow(/sub/);
   });
 });
+
+describe("createJwtHelper — keyring form", () => {
+  it("sets kid in the protected header when signing from a keyring", async () => {
+    const jwt = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await jwt.sign(user);
+    expect(jose.decodeProtectedHeader(token).kid).toBe("v1");
+  });
+
+  it("verifies a keyring-signed token against a string-form helper on the same secret", async () => {
+    const keyringSigner = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await keyringSigner.sign(user);
+
+    const stringVerifier = createJwtHelper(SECRET);
+    const payload = await stringVerifier.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("omits kid when signing from a plain secret (string form)", async () => {
+    const jwt = createJwtHelper(SECRET);
+    const token = await jwt.sign(user);
+    expect(jose.decodeProtectedHeader(token).kid).toBeUndefined();
+  });
+
+  it("verifies a token signed under an old kid after rotating signKid", async () => {
+    const OLD_SECRET = "old-secret-at-least-32-characters-long-aa";
+    const before = createJwtHelper({ keys: { v1: OLD_SECRET }, signKid: "v1" });
+    const token = await before.sign(user);
+
+    const after = createJwtHelper({ keys: { v1: OLD_SECRET, v2: SECRET }, signKid: "v2" });
+    const payload = await after.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("verifies a legacy no-kid token against a multi-key keyring", async () => {
+    const legacy = createJwtHelper(SECRET);
+    const token = await legacy.sign(user);
+
+    const rotated = createJwtHelper({
+      keys: { v1: "unrelated-secret-32-characters-longg", v2: SECRET },
+      signKid: "v2",
+    });
+    const payload = await rotated.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("rejects a token whose kid is not in the keyring", async () => {
+    const signer = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await signer.sign(user);
+
+    const verifier = createJwtHelper({ keys: { v2: SECRET }, signKid: "v2" });
+    await expect(verifier.verify(token)).rejects.toThrow(/kid/);
+  });
+
+  it("throws at creation when signKid is not present in the keyring", () => {
+    expect(() => createJwtHelper({ keys: { v1: SECRET }, signKid: "v2" })).toThrow(/signKid/);
+  });
+});
+
+describe("loadJwtSecretOrKeyring", () => {
+  it("no JWT_SECRET_V<n> → falls back to plain JWT_SECRET", () => {
+    expect(loadJwtSecretOrKeyring({ JWT_SECRET: SECRET })).toBe(SECRET);
+  });
+
+  it("neither JWT_SECRET_V<n> nor JWT_SECRET set → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({})).toThrow(/JWT_SECRET not set/);
+  });
+
+  it("JWT_SECRET_V1 + JWT_SECRET_CURRENT_VERSION=1 → single-key keyring, signKid v1", () => {
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET }, signKid: "v1" });
+  });
+
+  it("rotation: two versions, current-version picks the sign key, both stay verifiable", () => {
+    const OLD_SECRET = "old-secret-at-least-32-characters-long!!";
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: OLD_SECRET,
+        JWT_SECRET_V2: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "2",
+      }),
+    ).toEqual({ keys: { v1: OLD_SECRET, v2: SECRET }, signKid: "v2" });
+  });
+
+  it("JWT_SECRET_V<n> present but JWT_SECRET_CURRENT_VERSION missing → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({ JWT_SECRET_V1: SECRET })).toThrow(
+      /JWT_SECRET_CURRENT_VERSION not set/,
+    );
+  });
+
+  it("JWT_SECRET_CURRENT_VERSION points at a version with no matching JWT_SECRET_V<n> → throws", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "2",
+      }),
+    ).toThrow(/not present in the keyring/);
+  });
+
+  it("plain JWT_SECRET is ignored once a keyring is present", () => {
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: "should-be-ignored-once-keyring-present-aa",
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET }, signKid: "v1" });
+  });
+
+  it("plain JWT_SECRET under 32 chars → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({ JWT_SECRET: "too-short" })).toThrow(
+      /JWT_SECRET must be ≥32 chars/,
+    );
+  });
+
+  it("JWT_SECRET_V<n> under 32 chars → throws (bypasses the env-schema check otherwise)", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: "too-short",
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET_V1 must be ≥32 chars/);
+  });
+});
+
+describe("createJwtHelper — ttlSeconds", () => {
+  it("defaults to 24h", () => {
+    const jwt = createJwtHelper(SECRET);
+    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+  });
+
+  it("exposes a custom ttlSeconds", () => {
+    const jwt = createJwtHelper(SECRET, ISSUER, 60 * 60);
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  it("signs a token whose exp - iat exactly equals ttlSeconds", async () => {
+    const ttlSeconds = 60 * 60;
+    const jwt = createJwtHelper(SECRET, ISSUER, ttlSeconds);
+    const token = await jwt.sign(user);
+    const claims = jose.decodeJwt(token);
+    expect(claims.exp).toBeDefined();
+    expect(claims.iat).toBeDefined();
+    expect(claims.exp! - claims.iat!).toBe(ttlSeconds);
+  });
+});

package/src/api/__tests__/login-rate-limiter-sweep.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { createInMemoryLoginRateLimiter } from "../auth-routes";
+
+describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
+  test("sweepExpired drops windows that already reset before accepting a new key", async () => {
+    // Tiny thresholds so the Map hits the sweep path without flooding.
+    const limiter = createInMemoryLoginRateLimiter(10, 50, {
+      maxEntries: 100,
+      sweepThreshold: 2,
+    });
+
+    expect(await limiter.check("a")).toBe(true);
+    expect(await limiter.check("b")).toBe(true);
+    // Wait for both windows to expire, then a third check must sweep a+b
+    // (hits.size >= sweepThreshold) before inserting "c".
+    await Bun.sleep(60);
+    expect(await limiter.check("c")).toBe(true);
+    // Fresh window for "a" after sweep — not rate-limited.
+    expect(await limiter.check("a")).toBe(true);
+  });
+
+  test("enforceCap drops oldest entries when the map exceeds maxEntries", async () => {
+    const limiter = createInMemoryLoginRateLimiter(100, 60_000, {
+      maxEntries: 3,
+      sweepThreshold: 10_000, // never sweep — only the hard cap matters
+    });
+
+    expect(await limiter.check("k1")).toBe(true);
+    expect(await limiter.check("k2")).toBe(true);
+    expect(await limiter.check("k3")).toBe(true);
+    // 4th insert trips enforceCap → drops oldest (k1).
+    expect(await limiter.check("k4")).toBe(true);
+
+    // k1 was dropped — a fresh check starts a new window (allowed).
+    expect(await limiter.check("k1")).toBe(true);
+    // k2/k3/k4 still live in the map (cap=3 after k1 drop + k1 reinsert may
+    // drop another). Reset proves the API still works for survivors.
+    await limiter.reset("k4");
+    expect(await limiter.check("k4")).toBe(true);
+  });
+});

package/src/api/__tests__/server-boot-guards.test.ts

@@ -0,0 +1,71 @@
+// buildServer boot-time guards + httpRoute verb wiring (PUT branch).
+
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createFileField,
+  createRegistry,
+  createTextField,
+  defineFeature,
+} from "../../engine";
+import { buildServer } from "../server";
+
+const JWT_SECRET = "server-boot-guards-test-secret-min-32-chars";
+
+describe("buildServer — file-storage provider guard", () => {
+  const fileFieldFeature = defineFeature("needs-files", (r) => {
+    r.entity(
+      "doc",
+      createEntity({
+        table: "boot_guard_docs",
+        fields: { title: createTextField(), attachment: createFileField() },
+      }),
+    );
+  });
+
+  test("throws when registry declares file fields but no provider is mounted", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([fileFieldFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      }),
+    ).toThrow(/no file-storage provider is mounted/);
+  });
+});
+
+describe("buildServer — rateLimit resolver guard", () => {
+  test("throws when L1 global middleware requested without resolver", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+        rateLimit: { global: { limit: 100, windowSeconds: 60 } },
+      }),
+    ).toThrow(/rateLimit middleware requested but no resolver available/);
+  });
+});
+
+describe("buildServer — feature httpRoute PUT mounting", () => {
+  const putFeature = defineFeature("put-route", (r) => {
+    r.httpRoute({
+      method: "PUT",
+      path: "/resource/42",
+      anonymous: true,
+      handler: (c) => c.json({ method: "PUT", ok: true }),
+    });
+  });
+
+  const { app } = buildServer({
+    registry: createRegistry([putFeature]),
+    context: {},
+    jwtSecret: JWT_SECRET,
+  });
+
+  test("PUT /resource/42 reaches the declared handler", async () => {
+    const res = await app.request("/resource/42", { method: "PUT" });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ method: "PUT", ok: true });
+  });
+});

package/src/api/__tests__/server-jwt-ttl.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { createRegistry } from "../../engine";
+import { buildServer } from "../server";
+
+const JWT_SECRET = "x".repeat(40);
+const registry = createRegistry([]);
+
+describe("buildServer — jwtTtl default depends on sessionChecker wiring", () => {
+  test("no auth config → stateless default (1h)", () => {
+    const { jwt } = buildServer({ registry, context: {}, jwtSecret: JWT_SECRET });
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  test("auth without sessionChecker → stateless default (1h)", () => {
+    const { jwt } = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      auth: { membershipQuery: "unused:query" },
+    });
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  test("auth with sessionChecker → session-backed default (24h)", () => {
+    const { jwt } = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      auth: {
+        membershipQuery: "unused:query",
+        sessionChecker: async () => "live",
+      },
+    });
+    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+  });
+
+  test("explicit jwtTtl wins regardless of sessionChecker wiring", () => {
+    const withChecker = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      jwtTtl: 42,
+      auth: {
+        membershipQuery: "unused:query",
+        sessionChecker: async () => "live",
+      },
+    });
+    expect(withChecker.jwt.ttlSeconds).toBe(42);
+
+    const withoutChecker = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      jwtTtl: 42,
+    });
+    expect(withoutChecker.jwt.ttlSeconds).toBe(42);
+  });
+});

package/src/api/api-constants.ts

@@ -10,6 +10,7 @@ export const Routes = {
   query: "/query",
   command: "/command",
   sse: "/sse",
+  stream: "/stream",
   auth: "/auth",
   authLogin: "/auth/login",
   authMfaVerify: "/auth/mfa/verify",
@@ -20,6 +21,8 @@ export const Routes = {
   authResetPassword: "/auth/reset-password",
   authRequestEmailVerification: "/auth/request-email-verification",
   authVerifyEmail: "/auth/verify-email",
+  authRequestAccountUnlock: "/auth/request-account-unlock",
+  authConfirmAccountUnlock: "/auth/confirm-account-unlock",
   authSignupRequest: "/auth/signup-request",
   authSignupConfirm: "/auth/signup-confirm",
   // Tenant-Invite (Magic-Link): 3 separate accept-Endpoints für klare
@@ -42,6 +45,8 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authResetPassword}`,
   `/api${Routes.authRequestEmailVerification}`,
   `/api${Routes.authVerifyEmail}`,
+  `/api${Routes.authRequestAccountUnlock}`,
+  `/api${Routes.authConfirmAccountUnlock}`,
   `/api${Routes.authSignupRequest}`,
   `/api${Routes.authSignupConfirm}`,
   // invite-accept braucht JWT (logged-in User, Branch 1) — NICHT public.

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

@@ -16,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
@@ -48,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";
@@ -55,7 +53,7 @@ function setAuthCookies(
     secure: cookieSecure(),
     sameSite,
     path: "/",
-    maxAge: JWT_TTL_SECONDS,
+    maxAge: opts.ttlSeconds,
     ...(opts.domain !== undefined && { domain: opts.domain }),
   } as const;
 
@@ -262,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).
@@ -288,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.
@@ -358,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)
@@ -518,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;
   }
 
@@ -729,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