@simple-auth-kit/cli 1.0.0

package/registry/combos/express-drizzle/shared/src/permission-cache.ts

@@ -0,0 +1,191 @@
+// The caching seam in front of permission resolution.
+//
+// Authorization is resolved from the database on every authorized request — that is what makes a
+// grant or a revocation take effect on the caller's *next request* rather than their next token.
+// Left naked, that puts one multi-join read on the hot path of every call. This module is the
+// seam that keeps the semantics and removes the read, and it is here from the start because
+// retrofitting a cache into a hot path is exactly the change that is expensive later.
+//
+// Three decisions, all of which a consumer can see and none of which they have to accept:
+//
+//   1. **Version-key invalidation, never eviction.** Nothing hunts down and deletes cache entries.
+//      A cache key contains two generation counters, and bumping a counter makes every key that
+//      embedded the old value unreachable in one write. That matters because one role change can
+//      affect an unbounded number of users, and there is no scan that scales.
+//
+//   2. **Two counters, not one.**
+//        • a *subject* counter per principal (`userId`, or `userId:workspaceId`), bumped by the
+//          frequent, narrow operations: this user's role assignments and direct grants;
+//        • a *policy* counter, global, bumped by the rare, wide ones: what a role carries, and
+//          whether a permission is active at all.
+//      A single global counter would be simpler but would flush every user's entry every time an
+//      administrator touched one user's grants. Per-role counters would be more surgical still,
+//      but resolving them needs the role→user fan-out this scheme exists to avoid, on the read
+//      path, for every request. The cost of what is chosen here is honest and bounded: a role
+//      composition change or a permission being deactivated re-resolves everyone once. Those are
+//      administrator actions measured in per-day, not per-second.
+//
+//   3. **The store is an injected interface with an in-memory default.** Same style as
+//      `TokenStorage` in packages/auth-client: a consumer swaps in Redis by passing a store to
+//      `createAuthApp`, without editing a line of this library. Keys are namespaced
+//      (`simpleauthkit:authz:*`) so a shared Redis stays separable. No Redis dependency is added here.
+//
+// What is deliberately *not* cached: authentication. Whether a token is valid, denylisted, or
+// belongs to a blocked user is decided on the authentication path (`AuthGuard`), which never
+// reads this cache — so blocking a user or revoking a session cannot be defeated by a warm entry.
+// Negative results are not cached either: "not a member of this workspace" is re-read every time,
+// so being added to a workspace is effective immediately rather than after a TTL.
+import type { AuthConfig } from "./auth.config.js";
+
+/** Every key this library writes starts here, so a shared Redis can be separated by prefix. */
+export const CACHE_NAMESPACE = "simpleauthkit:authz";
+
+/**
+ * The four operations a permission cache needs. Deliberately small and string-valued: every one
+ * maps onto a single Redis command (`GET`, `MGET`, `SET ... EX`, `INCR`), so the Redis
+ * implementation is a dozen lines and needs no transaction.
+ */
+export interface PermissionCacheStore {
+  get(key: string): Promise<string | undefined>;
+  getMany(keys: readonly string[]): Promise<Array<string | undefined>>;
+  set(key: string, value: string, ttlSeconds: number): Promise<void>;
+  /** Atomic increment, returning the new value. `INCR` in Redis; correct here because Node is single-threaded. */
+  bump(key: string): Promise<number>;
+}
+
+/**
+ * The default store: a `Map` with expiry, scoped to one process.
+ *
+ * Correct for a single-instance deployment and for development. Across several instances each
+ * keeps its own copy, and a version bumped on one is not seen by the others — so a multi-instance
+ * deployment should pass a shared store. That is the whole reason the interface exists.
+ *
+ * `stats` is not decoration: it is how `prove-cycle` asserts that N identical authorized requests
+ * cause one database resolution rather than N. A cache nobody can prove is working is a bug
+ * surface.
+ */
+export class InMemoryPermissionCacheStore implements PermissionCacheStore {
+  readonly stats = { hits: 0, misses: 0, writes: 0 };
+  private readonly entries = new Map<string, { value: string; expiresAt: number }>();
+
+  async get(key: string): Promise<string | undefined> {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      this.stats.misses += 1;
+      return undefined;
+    }
+    if (entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      this.stats.misses += 1;
+      return undefined;
+    }
+    this.stats.hits += 1;
+    return entry.value;
+  }
+
+  async getMany(keys: readonly string[]): Promise<Array<string | undefined>> {
+    // Version reads are bookkeeping, not cache traffic — counting them in hits/misses would make
+    // the hit rate meaningless, and `prove-cycle` asserts on that number.
+    return keys.map((key) => {
+      const entry = this.entries.get(key);
+      return entry && entry.expiresAt > Date.now() ? entry.value : undefined;
+    });
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    this.stats.writes += 1;
+    this.entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+  }
+
+  async bump(key: string): Promise<number> {
+    const entry = this.entries.get(key);
+    const next = Number(entry && entry.expiresAt > Date.now() ? entry.value : 0) + 1;
+    // Version counters outlive entries on purpose: a counter that expired back to 0 would make
+    // every superseded entry reachable again.
+    this.entries.set(key, { value: String(next), expiresAt: Number.MAX_SAFE_INTEGER });
+    return next;
+  }
+}
+
+/**
+ * The two version counters. Exported because anything writing RBAC rows *outside* this
+ * application — a second service, a migration, a `psql` session — is outside the invalidation
+ * protocol, and bumping the counter is how such a writer says so. Without that, an out-of-band
+ * write is picked up when the entry expires (`permissionCacheTtlSeconds`), not immediately.
+ */
+export const POLICY_VERSION_KEY = `${CACHE_NAMESPACE}:policy-version`;
+export const subjectVersionKey = (subject: string) => `${CACHE_NAMESPACE}:subject-version:${subject}`;
+const entryKey = (subject: string, policy: string, subjectVersion: string) => `${CACHE_NAMESPACE}:entry:${subject}:p${policy}:s${subjectVersion}`;
+
+/**
+ * Reads through to the database, once per (principal, policy version, subject version).
+ *
+ * Used by each variant's authz middleware. The variants differ only in what a "subject" is — a user
+ * id in `base`, a `userId:workspaceId` pair in `workspaces` — which is why this file can be
+ * shared while the guards cannot.
+ */
+export class PermissionCache {
+  constructor(
+    private readonly store: PermissionCacheStore,
+    private readonly config: AuthConfig,
+  ) {}
+
+  /**
+   * Concurrent misses on the same key collapse into one `load()`.
+   *
+   * In-process, which is enough for the default store: a cold key under load costs one database
+   * read per instance rather than one per request. A distributed single-flight (a short-lived
+   * lock key in the shared store) replaces this without touching callers — the seam is that
+   * `load` is a thunk and the map is private.
+   */
+  private readonly inFlight = new Map<string, Promise<unknown>>();
+
+  /**
+   * @param subject the identity these permissions belong to — the cache key's principal
+   * @param load    resolves from the database on a miss. Returning `null` is not cached.
+   */
+  async resolve<T>(subject: string, load: () => Promise<T | null>): Promise<T | null> {
+    const ttl = this.config.permissionCacheTtlSeconds;
+    if (ttl <= 0) return load(); // caching off; the semantics are identical, only the cost differs
+
+    const [policy = "0", version = "0"] = await this.store.getMany([POLICY_VERSION_KEY, subjectVersionKey(subject)]);
+    const key = entryKey(subject, policy, version);
+
+    const cached = await this.store.get(key);
+    if (cached !== undefined) return JSON.parse(cached) as T;
+
+    const existing = this.inFlight.get(key);
+    if (existing) return (await existing) as T | null;
+
+    const pending = (async () => {
+      const resolved = await load();
+      // A negative result is not written: see the module comment. Only a real answer is cached.
+      if (resolved !== null) await this.store.set(key, JSON.stringify(resolved), ttl);
+      return resolved;
+    })();
+
+    this.inFlight.set(key, pending);
+    try {
+      return await pending;
+    } finally {
+      this.inFlight.delete(key);
+    }
+  }
+
+  /**
+   * Invalidates one principal: their role assignments or their direct grants changed. One write,
+   * no fan-out, and every entry that embedded the old counter is unreachable from that moment.
+   */
+  async invalidateSubject(subject: string): Promise<void> {
+    await this.store.bump(subjectVersionKey(subject));
+  }
+
+  /**
+   * Invalidates everyone: what a role carries changed, or a permission was activated or
+   * deactivated. One write, whatever the number of users affected — which is the point, because
+   * the alternative is enumerating them.
+   */
+  async invalidatePolicy(): Promise<void> {
+    await this.store.bump(POLICY_VERSION_KEY);
+  }
+}

package/registry/combos/express-drizzle/shared/src/rate-limit.store.ts

@@ -0,0 +1,24 @@
+import type { RateLimitDeps } from "@/lib/auth/core/rate-limit.js";
+
+/**
+ * In-memory window counter — fine for a single instance / the reference combo's proof.
+ * Swap for Redis (INCR + PEXPIRE) behind this same `increment` signature once you run
+ * more than one instance; nothing above this layer needs to change.
+ *
+ * Plain class, no decorators — identical logic to the NestJS combos' equivalent, just
+ * constructed directly instead of registered as an injectable provider.
+ */
+export class InMemoryRateLimitStore implements RateLimitDeps {
+  private readonly windows = new Map<string, { count: number; resetAt: number }>();
+
+  async increment(key: string, windowMs: number): Promise<number> {
+    const now = Date.now();
+    const existing = this.windows.get(key);
+    if (!existing || existing.resetAt <= now) {
+      this.windows.set(key, { count: 1, resetAt: now + windowMs });
+      return 1;
+    }
+    existing.count += 1;
+    return existing.count;
+  }
+}

package/registry/combos/express-drizzle/shared/src/request-context.ts

@@ -0,0 +1,35 @@
+// The three request-scoped objects every middleware and route handler in this combo reads.
+//
+//   req.auth    — the verified access-token claims. Identity only: which user, which session.
+//   req.authz   — the authorization context resolved for *this* request: the roles and
+//                 permissions that apply to it.
+//   req.ability — the same authorization, as the CASL ability the routes are gated on. Derived
+//                 from `req.authz.permissions` in the same middleware that resolves them, so it
+//                 costs no extra lookup of any kind. `GET /auth/me` returns the permission slugs
+//                 rather than a serialised ability, and a client rebuilds the identical object
+//                 from them with the same `defineAbilitiesFor`.
+//
+// Keeping authentication and authorization separate means a route handler never has to care *how*
+// authorization was decided, only what it decided — see authz.middleware.ts. Importing this
+// module for its side effect installs the Express `Request` augmentation.
+//
+// Express has no request-scoped DI container, so where the reference combo's guards hand a
+// resolved object to the framework, here each middleware attaches it to the request itself.
+// The augmentation is written in Express's own declaration-merging style (`declare global` on
+// the `Express` namespace, see @types/express-serve-static-core) rather than the reference's
+// `declare module "express"`.
+import type { AccessTokenClaims } from "@/lib/auth/core/types.js";
+import type { AppAbility } from "./ability.js";
+import type { AuthzContext } from "./authz.middleware.js";
+
+declare global {
+  namespace Express {
+    interface Request {
+      auth?: AccessTokenClaims;
+      authz?: AuthzContext;
+      ability?: AppAbility;
+    }
+  }
+}
+
+export {};

package/registry/combos/express-drizzle/shared/src/response-envelope.middleware.ts

@@ -0,0 +1,46 @@
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+
+function deriveMessage(method: string): string {
+  switch (method) {
+    case "GET":
+      return "Fetched successfully";
+    case "POST":
+      return "Created successfully";
+    case "PATCH":
+    case "PUT":
+      return "Updated successfully";
+    case "DELETE":
+      return "Deleted successfully";
+    default:
+      return "Request successful";
+  }
+}
+
+/**
+ * Wraps every `res.json(...)` call made after this middleware runs, so no individual route
+ * handler needs to know the envelope exists. Distinguishes success from error purely by
+ * `res.statusCode` (already set via `res.status(x)` before `.json()` is ever called, by every
+ * call site in this codebase) — a body from an error path is spread with `success: false` rather
+ * than nested under `data`, since it's already shaped as `{statusCode, message, ...}`.
+ *
+ * Skips `/docs` and `/docs-json` regardless of where those routes are mounted relative to this
+ * middleware — the raw OpenAPI JSON must stay unwrapped.
+ */
+export function responseEnvelope(): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (req.path === "/docs-json" || req.path.startsWith("/docs")) {
+      next();
+      return;
+    }
+
+    const originalJson = res.json.bind(res);
+    res.json = ((body: unknown) => {
+      if (res.statusCode >= 400) {
+        const shaped = body && typeof body === "object" ? (body as Record<string, unknown>) : { message: body };
+        return originalJson({ success: false, statusCode: res.statusCode, ...shaped });
+      }
+      return originalJson({ success: true, statusCode: res.statusCode, message: deriveMessage(req.method), data: body });
+    }) as typeof res.json;
+    next();
+  };
+}

package/registry/combos/express-drizzle/shared/src/route-tiers.ts

@@ -0,0 +1,148 @@
+// Every route in this combo belongs to exactly one of three tiers, and says so at the point it is
+// registered.
+//
+//   1. public(...)              — no authentication at all. Signup, login, refresh, password
+//                                 reset, the OAuth redirect endpoints.
+//   2. authenticated(...)       — any logged-in user, no permission. /auth/me, logout, sessions,
+//                                 2FA enrolment, and (in the workspace variant) creating or
+//                                 listing your own workspaces and seeing who else is in one you
+//                                 belong to.
+//   3. ability(...slugs)        — the administrative surface. Every named slug must be in the
+//                                 caller's ability or the request is refused.
+//
+// The reference combo says this with decorators and then walks the route table at startup: a
+// handler carrying none of the three markers fails the boot, by name. Plain Express has no
+// metadata-reflection layer, so "what did this handler declare?" cannot be recovered by
+// inspection after the fact. The property is enforced at the point of registration instead, which
+// gets to the same place by a different road:
+//
+//   • `route()` is the only way to put a handler on a tiered router, and its tier argument is
+//     required — a route with no tier is not an ungated route, it is a compile error;
+//   • the finished router is handed back typed as `RequestHandler`, so `.get`/`.post` are not
+//     reachable to sneak a route past `route()`;
+//   • the middleware each tier needs is attached *by* `route()`, from the tier itself, so a route
+//     cannot claim a tier and then not be behind it — the equivalent of the reference's
+//     two-sided "declared tier matches attached guards" check;
+//   • and every slug is checked against `PERMISSION_CATALOG` at registration, i.e. at startup, so
+//     even an untyped (plain-JS) caller fails loudly at boot rather than serving a route gated on
+//     a permission nothing can ever grant.
+import { Router } from "express";
+import type { NextFunction, Request, RequestHandler, Response } from "express";
+import { ABILITY_SUBJECT } from "./ability.js";
+import { PERMISSION_CATALOG, type PermissionSlug } from "./rbac.defaults.js";
+import "./request-context.js";
+
+/** The subset of Express's routing verbs this library's routes use. */
+export type TieredMethod = "get" | "post" | "put" | "patch" | "delete";
+
+/**
+ * What a route declares about itself. There is deliberately no fourth shape and no default: the
+ * union is closed, so adding a route means picking one of these three.
+ */
+export type RouteTier = { kind: "public" } | { kind: "authenticated" } | { kind: "ability"; abilities: PermissionSlug[] };
+
+/** Tier 1: reachable with no token at all. Carries no middleware, which is exactly why it has to be said out loud. */
+export const publicRoute = (): RouteTier => ({ kind: "public" });
+
+/** Tier 2: any authenticated caller, no permission required. */
+export const authenticated = (): RouteTier => ({ kind: "authenticated" });
+
+/**
+ * Tier 3: `ability("users:block")`. Several slugs may be named, and **all** of them must be held —
+ * the check ANDs them.
+ *
+ * This is the half of authorization that has to be code. **A route declares what it demands; the
+ * database decides who is granted it.** The argument is typed as `PermissionSlug`, the catalog in
+ * `rbac.defaults.ts`, so a route cannot be gated on a slug nothing will ever grant. Which *users*
+ * hold the slug is entirely a matter of rows.
+ */
+export const ability = (...abilities: PermissionSlug[]): RouteTier => {
+  if (!abilities.length) throw new Error("ability() names no permission — use authenticated() if any logged-in caller may call the route");
+  for (const slug of abilities) assertInCatalog(slug);
+  return { kind: "ability", abilities };
+};
+
+/**
+ * The authorization boundary for tier-3 routes. This is the *only* thing standing between a caller
+ * and an administrative route — there is deliberately no role-based bypass beside it, so a role
+ * that carries no permissions confers no authority no matter what it is called.
+ *
+ * It asks the caller's `Ability` the same question a client asks after `GET /auth/me`, built by
+ * the same function from the same slugs, which is what makes server enforcement and client UI
+ * incapable of disagreeing.
+ */
+export function requireAbility(abilities: PermissionSlug[]): RequestHandler {
+  return function abilityMiddleware(req: Request, res: Response, next: NextFunction): void {
+    // No ability at all means the authz middleware resolved nothing — fail closed.
+    if (!req.ability) {
+      res.status(403).json({ statusCode: 403, code: "FORBIDDEN", message: "no authorization context for this request" });
+      return;
+    }
+    for (const slug of abilities) {
+      if (!req.ability.can(slug, ABILITY_SUBJECT)) {
+        res.status(403).json({ statusCode: 403, code: "FORBIDDEN", message: `missing permission: ${slug}` });
+        return;
+      }
+    }
+    next();
+  };
+}
+
+/** A router on which naming a tier is not optional. See `createTieredRouter`. */
+export interface TieredRouter {
+  /**
+   * Registers one route. `tier` is a required positional argument, so there is no call shape that
+   * adds a route without one, and the middleware the tier implies is always inserted immediately
+   * before `handler` — the two cannot come apart.
+   */
+  route(method: TieredMethod, path: string, tier: RouteTier, ...handlers: RequestHandler[]): void;
+  /**
+   * The composed middleware, for `app.use(...)`. Deliberately typed as `RequestHandler` and not
+   * as `Router`, even though that is what it is at runtime: the `.get`/`.post`/… methods are
+   * hidden from the type, so `route()` above is the only way to put a handler on this router.
+   */
+  readonly handler: RequestHandler;
+}
+
+export interface TierMiddleware {
+  /** Verifies the access token and populates `req.auth`. Attached for tiers 2 and 3. */
+  authentication: RequestHandler;
+  /** Resolves `req.authz` and `req.ability` from the database. Attached for tiers 2 and 3. */
+  authorization: RequestHandler;
+}
+
+/**
+ * Builds a router whose every route names its tier.
+ *
+ * `middleware.authentication` and `middleware.authorization` are attached per route rather than
+ * with a blanket `router.use`, because that is what makes the public tier genuinely public on a
+ * router that also carries protected routes — and what makes "declares public but sits behind the
+ * auth middleware" unrepresentable rather than merely unlikely.
+ */
+export function createTieredRouter(middleware: TierMiddleware): TieredRouter {
+  const router = Router();
+
+  return {
+    route(method: TieredMethod, path: string, tier: RouteTier, ...handlers: RequestHandler[]): void {
+      router[method](path, ...tierMiddleware(tier, middleware), ...handlers);
+    },
+    handler: router,
+  };
+}
+
+function tierMiddleware(tier: RouteTier, middleware: TierMiddleware): RequestHandler[] {
+  switch (tier.kind) {
+    case "public":
+      return [];
+    case "authenticated":
+      return [middleware.authentication, middleware.authorization];
+    case "ability":
+      return [middleware.authentication, middleware.authorization, requireAbility(tier.abilities)];
+  }
+}
+
+function assertInCatalog(slug: string): void {
+  if (!Object.prototype.hasOwnProperty.call(PERMISSION_CATALOG, slug)) {
+    throw new Error(`"${slug}" is not in PERMISSION_CATALOG — add it to rbac.defaults.ts (the seeder provisions exactly that catalog)`);
+  }
+}

package/registry/combos/express-drizzle/shared/src/session.repository.ts

@@ -0,0 +1,130 @@
+import { randomUUID } from "node:crypto";
+import { and, eq, isNull, ne, sql } from "drizzle-orm";
+import type { SessionStoreDeps } from "@/lib/auth/core/session-policy.js";
+import type { AuditEvent, Revoker, SessionRecord } from "@/lib/auth/core/types.js";
+import { AuditLogRepository } from "./audit-log.repository.js";
+import type { AuthConfig } from "./auth.config.js";
+import type { Database } from "./db.js";
+import { denylistedAccessTokens, sessions } from "./schema.js";
+import { toId, toIdOrNull } from "./id.helper.js";
+
+function toSessionRecord(row: typeof sessions.$inferSelect): SessionRecord {
+  return {
+    id: row.id.toString(),
+    userId: row.userId.toString(),
+    sessionVersion: row.sessionVersion,
+    currentRefreshJti: row.currentRefreshJti,
+    provider: row.provider ?? undefined,
+    expiresAt: row.expiresAt.toISOString(),
+    revokedAt: row.revokedAt?.toISOString() ?? null,
+    revokedBy: row.revokedBy?.toString() ?? undefined,
+    revokedByIp: row.revokedByIp ?? undefined,
+    createdAt: row.createdAt.toISOString(),
+    userAgent: row.userAgent ?? undefined,
+    ip: row.ip ?? undefined,
+  };
+}
+
+/**
+ * The revocation columns, written as one block wherever a session is revoked.
+ *
+ * `isRevoked` is derived from `revokedAt` here rather than being a fact of its own: the reference
+ * schema carries both columns, and the only way two columns for one fact stay honest is if
+ * exactly one place computes the second from the first.
+ */
+const revocationFields = (revoker?: Revoker) => ({
+  revokedAt: new Date(),
+  isRevoked: true,
+  isActive: false,
+  revokedBy: toIdOrNull(revoker?.userId),
+  revokedByIp: revoker?.ip ?? null,
+});
+
+export class SessionRepository implements SessionStoreDeps {
+  constructor(
+    private readonly db: Database,
+    private readonly auditLog: AuditLogRepository,
+    private readonly config: AuthConfig,
+  ) {}
+
+  /** Delegates to AuditLogRepository — makes the previously-optional, previously-unwired `SessionStoreDeps.appendAuditEvent` real. */
+  async appendAuditEvent(event: AuditEvent): Promise<void> {
+    await this.auditLog.append(event);
+  }
+
+  async findSession(id: string): Promise<SessionRecord | null> {
+    const [row] = await this.db.select().from(sessions).where(eq(sessions.id, toId(id))).limit(1);
+    return row ? toSessionRecord(row) : null;
+  }
+
+  async saveSession(session: SessionRecord): Promise<void> {
+    const revoked = session.revokedAt !== null;
+    await this.db
+      .update(sessions)
+      .set({
+        sessionVersion: session.sessionVersion,
+        currentRefreshJti: session.currentRefreshJti,
+        revokedAt: session.revokedAt ? new Date(session.revokedAt) : null,
+        isRevoked: revoked,
+        isActive: !revoked,
+        revokedBy: toIdOrNull(session.revokedBy),
+        revokedByIp: session.revokedByIp ?? null,
+      })
+      .where(eq(sessions.id, toId(session.id)));
+  }
+
+  /**
+   * `expiresAt` is this repository's decision, not core's — the store is the half that knows the
+   * deployment's configured session lifetime. It is set once here and never rewritten, which is
+   * what makes it an absolute cap rather than a sliding window: see `sessionTtlSeconds`.
+   *
+   * `createdBy` is the user themselves. A session is only ever created by the person logging in,
+   * so recording it costs nothing and leaves the column meaningful rather than always null.
+   */
+  async createSession(input: { userId: string; userAgent?: string; ip?: string; provider?: string }): Promise<SessionRecord> {
+    const userIdBig = toId(input.userId);
+    const [row] = await this.db
+      .insert(sessions)
+      .values({
+        userId: userIdBig,
+        currentRefreshJti: randomUUID(),
+        provider: input.provider,
+        userAgent: input.userAgent,
+        ip: input.ip,
+        expiresAt: new Date(Date.now() + this.config.sessionTtlSeconds * 1000),
+        createdBy: userIdBig,
+      })
+      .returning();
+    return toSessionRecord(row);
+  }
+
+  /** Bulk revoke for one user. Sessions are user-level, never scoped to anything narrower. */
+  async revokeAllByUser(userId: string, revoker?: Revoker): Promise<void> {
+    await this.db
+      .update(sessions)
+      .set({ ...revocationFields(revoker), sessionVersion: sql`${sessions.sessionVersion} + 1` })
+      .where(and(eq(sessions.userId, toId(userId)), isNull(sessions.revokedAt)));
+  }
+
+  async revokeAllByUserExcept(userId: string, keepSessionId: string, revoker?: Revoker): Promise<void> {
+    await this.db
+      .update(sessions)
+      .set({ ...revocationFields(revoker), sessionVersion: sql`${sessions.sessionVersion} + 1` })
+      .where(and(eq(sessions.userId, toId(userId)), ne(sessions.id, toId(keepSessionId)), isNull(sessions.revokedAt)));
+  }
+
+  async denylistJti(jti: string, ttlSeconds: number): Promise<void> {
+    const expiresAt = new Date(Date.now() + ttlSeconds * 1000);
+    await this.db
+      .insert(denylistedAccessTokens)
+      .values({ jti, expiresAt })
+      .onConflictDoUpdate({ target: denylistedAccessTokens.jti, set: { expiresAt } });
+  }
+
+  async isDenylisted(jti: string): Promise<boolean> {
+    const [row] = await this.db.select().from(denylistedAccessTokens).where(eq(denylistedAccessTokens.jti, jti)).limit(1);
+    if (!row) return false;
+    if (row.expiresAt.getTime() < Date.now()) return false; // expired; a cleanup job reaps these, see Phase 6
+    return true;
+  }
+}

package/registry/combos/express-drizzle/shared/src/two-factor.repository.ts

@@ -0,0 +1,38 @@
+import { and, eq, isNull } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { verifyBackupCode } from "@/lib/auth/core/two-factor.js";
+import * as schema from "./schema.js";
+
+/**
+ * Plain class, no decorators — Drizzle-specific implementation mirroring the reference
+ * combo's TwoFactorRepository.
+ *
+ * Takes bigint directly, not string: every caller already has the user row's id in hand from
+ * its own database lookup, so there's nothing to parse here.
+ */
+export class TwoFactorRepository {
+  constructor(private readonly db: NodePgDatabase<typeof schema>) {}
+
+  /** Replaces any prior set — re-confirming enrollment invalidates old backup codes. */
+  async saveBackupCodes(userId: bigint, hashes: string[]): Promise<void> {
+    await this.db.delete(schema.twoFactorBackupCodes).where(eq(schema.twoFactorBackupCodes.userId, userId));
+    if (hashes.length === 0) return;
+    await this.db.insert(schema.twoFactorBackupCodes).values(hashes.map((codeHash) => ({ userId, codeHash })));
+  }
+
+  async consumeBackupCode(userId: bigint, code: string): Promise<boolean> {
+    const unused = await this.db
+      .select()
+      .from(schema.twoFactorBackupCodes)
+      .where(and(eq(schema.twoFactorBackupCodes.userId, userId), isNull(schema.twoFactorBackupCodes.usedAt)));
+    const match = unused.find((row) => verifyBackupCode(code, row.codeHash));
+    if (!match) return false;
+
+    await this.db.update(schema.twoFactorBackupCodes).set({ usedAt: new Date() }).where(eq(schema.twoFactorBackupCodes.id, match.id));
+    return true;
+  }
+
+  async clearBackupCodes(userId: bigint): Promise<void> {
+    await this.db.delete(schema.twoFactorBackupCodes).where(eq(schema.twoFactorBackupCodes.userId, userId));
+  }
+}

package/registry/combos/express-drizzle/test/bootstrap.ts

@@ -0,0 +1,40 @@
+import "dotenv/config";
+import type { Server } from "node:http";
+import { createAuthApp } from "../src/create-auth-app.js";
+import { InMemoryPermissionCacheStore } from "../src/permission-cache.js";
+
+// No mailer is wired up for the proof, so this stands in for one — prove-cycle.ts reads the
+// raw token back out of here the same way a test inbox would, to exercise the reset flow.
+export const capturedResetTokens = new Map<string, string>();
+
+/**
+ * The very store the app resolves permissions through. Exposed so `prove-cycle.ts` can assert
+ * that N identical authorized requests cause one database resolution rather than N — a cache
+ * nobody can prove is working is a bug surface, not an optimisation.
+ */
+export const permissionCacheStore = new InMemoryPermissionCacheStore();
+
+export async function bootstrap(port: number): Promise<{ close: () => Promise<void> }> {
+  const app = createAuthApp({
+    // Was 2 seconds, "so the proof can exercise expiry-adjacent paths quickly" — except no
+    // assertion in the proof waits for an access token to expire, so it bought nothing and
+    // cost a real 1-in-10 flake: the admin's token could die mid-section and surface as a
+    // confusing failure two assertions later. Long enough that expiry is never a variable,
+    // short enough to stay realistic. See `renewingToken` in test/harness.ts for the other
+    // half of the fix.
+    accessTokenTtlSeconds: 300,
+    permissionCacheStore,
+    sendPasswordResetEmail: async (email, token) => {
+      capturedResetTokens.set(email, token);
+    },
+  });
+  const server: Server = await new Promise((resolve) => {
+    const s = app.listen(port, () => resolve(s));
+  });
+  return {
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}