@cosmicdrift/kumiko-framework 0.158.2 → 0.159.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.158.2",
+  "version": "0.159.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -147,6 +147,10 @@
       "types": "./src/schema-cli.ts",
       "default": "./src/schema-cli.ts"
     },
+    "./consumer-cli": {
+      "types": "./src/consumer-cli.ts",
+      "default": "./src/consumer-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"
@@ -178,6 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@cosmicdrift/kumiko-types": "0.159.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -193,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.158.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.159.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/consumer-cli.integration.test.ts

@@ -0,0 +1,110 @@
+// Integration test for `runConsumerCli` (kumiko-framework#1351).
+//
+// Recovery semantics themselves are already covered by
+// event-dispatcher-recovery — this only exercises the CLI layer: argv
+// parsing, DB-connection handling, exit codes, output formatting.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
+import { type ConsumerCliOut, runConsumerCli } from "../consumer-cli";
+import { insertConsumerIfAbsent, markConsumerRebuildFailed } from "../db/queries/event-consumer";
+import { asRawClient } from "../db/query";
+import { createEventConsumerStateTable } from "../pipeline";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const SHARED = "__shared__";
+
+let testDb: BunTestDb;
+let testUrl: string;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  const baseUrl = process.env["TEST_DATABASE_URL"];
+  if (!baseUrl) throw new Error("TEST_DATABASE_URL not set — required for this test file");
+  testUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+afterEach(async () => {
+  await asRawClient(testDb.db).unsafe(`TRUNCATE TABLE "kumiko_event_consumers"`);
+  if (prevDbUrl === undefined) delete process.env["DATABASE_URL"];
+  else process.env["DATABASE_URL"] = prevDbUrl;
+});
+
+function captureOut(): { out: ConsumerCliOut; lines: string[] } {
+  const lines: string[] = [];
+  return {
+    out: { log: (l: string) => lines.push(l), err: (l: string) => lines.push(`ERR ${l}`) },
+    lines,
+  };
+}
+
+describe("runConsumerCli status", () => {
+  test("unknown consumer → exit 1, not-found message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "no-such-consumer"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not found");
+  });
+
+  test("known consumer → exit 0, reports status/cursor/attempts", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:foo", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:foo"], out);
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain("test:consumer:foo");
+    expect(joined).toContain("status:      idle");
+  });
+
+  test("missing <name> → exit 1, usage message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Usage:");
+  });
+
+  test("missing DATABASE_URL → exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    delete process.env["DATABASE_URL"];
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "whatever"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("DATABASE_URL not set");
+  });
+});
+
+describe("runConsumerCli restart", () => {
+  test("dead consumer → idle, exit 0", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:bar", SHARED);
+    await markConsumerRebuildFailed(testDb.db, "test:consumer:bar", SHARED, "boom");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:bar"], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("→ idle");
+  });
+
+  test("non-dead consumer → propagated error, exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:baz", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:baz"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not dead");
+  });
+});

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -52,8 +52,11 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
 async function buildApp(
   overrides: Partial<AuthRoutesConfig> = {},
   dispatcher: Dispatcher = createStubDispatcher(),
+  ttlSeconds?: number,
 ): Promise<{ app: Hono; validToken: string }> {
-  const jwt = createJwtHelper(JWT_SECRET);
+  const jwt = ttlSeconds
+    ? createJwtHelper(JWT_SECRET, undefined, ttlSeconds)
+    : createJwtHelper(JWT_SECRET);
   const validToken = await jwt.sign(TestUsers.user);
   const config: AuthRoutesConfig = {
     membershipQuery: "tenant:query:memberships",
@@ -128,6 +131,18 @@ describe("auth-routes cookie behaviour on /auth/login", () => {
     expect(typeof body.token).toBe("string");
     expect(body.token.length).toBeGreaterThan(20);
   });
+
+  test("cookie maxAge tracks the jwt helper's ttlSeconds, not a hardcoded default", async () => {
+    const customTtl = 60 * 60; // 1h — distinct from the 24h default
+    const { app } = await buildApp({}, undefined, customTtl);
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+  });
 });
 
 describe("auth-routes cookie behaviour on /auth/logout", () => {

package/src/api/__tests__/csrf-constants-sync.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CSRF_COOKIE_NAME as DISPATCHER_CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME as DISPATCHER_CSRF_HEADER_NAME,
+} from "@cosmicdrift/kumiko-dispatcher-live";
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+
+// dispatcher-live keeps its own literal copies of these two constants
+// (see packages/dispatcher-live/src/csrf.ts) because it must stay
+// server-dep-free for browser/React Native bundles. This test is the
+// guardrail that catches drift in CI instead of at runtime.
+describe("CSRF constant sync between framework and dispatcher-live", () => {
+  test("cookie name matches", () => {
+    expect(DISPATCHER_CSRF_COOKIE_NAME).toBe(CSRF_COOKIE_NAME);
+  });
+
+  test("header name matches", () => {
+    expect(DISPATCHER_CSRF_HEADER_NAME).toBe(CSRF_HEADER_NAME);
+  });
+});

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__/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

@@ -20,6 +20,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 +44,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;
 }