@simple-auth-kit/cli 1.0.0

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

@@ -0,0 +1,196 @@
+// 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
+//      `AuthModule.forRoot`, 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 { Inject, Injectable } from "@nestjs/common";
+import { AUTH_CONFIG, AuthConfig } from "./auth.config.js";
+
+/** DI token for the store. Provide your own to `AuthModule.forRoot({ permissionCacheStore })`. */
+export const PERMISSION_CACHE_STORE = Symbol("PERMISSION_CACHE_STORE");
+
+/** 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 `AuthzGuard`. 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.
+ */
+@Injectable()
+export class PermissionCache {
+  constructor(
+    @Inject(PERMISSION_CACHE_STORE) private readonly store: PermissionCacheStore,
+    @Inject(AUTH_CONFIG) 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/nestjs-drizzle/shared/src/rate-limit.store.ts

@@ -0,0 +1,26 @@
+import { Injectable } from "@nestjs/common";
+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.
+ */
+@Injectable()
+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;
+  }
+}
+
+/** DI token for the store. Provide your own to `AuthModule.forRoot({ rateLimitStore })` — mirrors `PERMISSION_CACHE_STORE`. */
+export const RATE_LIMIT_STORE = Symbol("RATE_LIMIT_STORE");

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

@@ -0,0 +1,25 @@
+// The three request-scoped objects every guard and controller 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 guard 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 controller never has to care *how*
+// authorization was decided, only what it decided — see authz.guard.ts. Importing this module
+// for its side effect installs the Express `Request` augmentation.
+import type { AccessTokenClaims } from "@/lib/auth/core/types.js";
+import type { AppAbility } from "./ability.js";
+import type { AuthzContext } from "./authz.guard.js";
+
+declare module "express" {
+  interface Request {
+    auth?: AccessTokenClaims;
+    authz?: AuthzContext;
+    ability?: AppAbility;
+  }
+}

package/registry/combos/nestjs-drizzle/shared/src/response.interceptor.ts

@@ -0,0 +1,48 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from "@nestjs/common";
+import { Observable, map } from "rxjs";
+import type { Request, Response } from "express";
+
+/**
+ * Every successful response is wrapped the same way: the real HTTP status alongside the payload,
+ * so a client never has to special-case "was this a 200 or a 201" by inspecting the body — the
+ * envelope's `statusCode` and the transport's own status line always agree.
+ */
+export interface Envelope<T> {
+  success: true;
+  statusCode: number;
+  message: string;
+  data: T;
+}
+
+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";
+  }
+}
+
+@Injectable()
+export class ResponseInterceptor<T> implements NestInterceptor<T, Envelope<T>> {
+  intercept(context: ExecutionContext, next: CallHandler<T>): Observable<Envelope<T>> {
+    const http = context.switchToHttp();
+    const req = http.getRequest<Request>();
+    const res = http.getResponse<Response>();
+    return next.handle().pipe(
+      map((data) => ({
+        success: true,
+        statusCode: res.statusCode,
+        message: deriveMessage(req.method),
+        data,
+      })),
+    );
+  }
+}

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

@@ -0,0 +1,144 @@
+// Every route in this combo belongs to exactly one of three tiers, and says so on itself.
+//
+//   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. @CheckAbility(...slugs)  — the administrative surface. Every named slug must be in the
+//                                 caller's ability or the request is refused.
+//
+// The point of making the tier explicit is `assertEveryRouteDeclaresATier` below: a route that
+// declares none of the three **fails at startup, by name**. Forgetting to gate a new admin route
+// is therefore not a security bug that ships — it is an app that will not boot.
+//
+// The check is deliberately two-sided. As well as "declared a tier?", it verifies that the guards
+// actually attached to the route match the tier it declared — a route marked @Authenticated()
+// with no AuthGuard, or @CheckAbility(...) with no AbilityGuard, is the same class of mistake as
+// declaring nothing at all, and would otherwise be an open route that looks closed in the source.
+import { RequestMethod, SetMetadata } from "@nestjs/common";
+import { GUARDS_METADATA, METHOD_METADATA, PATH_METADATA } from "@nestjs/common/constants.js";
+import type { PermissionSlug } from "./rbac.defaults.js";
+
+export const ROUTE_TIER_KEY = "routeTier";
+export const CHECK_ABILITY_KEY = "checkAbility";
+
+/** The three tiers, as stored in route metadata. There is deliberately no fourth value and no default. */
+export type RouteTier = "public" | "authenticated" | "ability";
+
+/**
+ * Tier 1: reachable with no token at all. Carries no guards, which is exactly why it has to be
+ * said out loud — "this route is open" must be a decision someone wrote down, not the absence of
+ * one.
+ */
+export const Public = () => SetMetadata(ROUTE_TIER_KEY, "public" satisfies RouteTier);
+
+/**
+ * Tier 2: any authenticated caller, no permission required. Pair with `@UseGuards(AuthGuard)`
+ * (plus the variant's authorization guard where the handler reads `req.authz`) — the startup
+ * check refuses a route that claims this tier without an authentication guard behind it.
+ */
+export const Authenticated = () => SetMetadata(ROUTE_TIER_KEY, "authenticated" satisfies RouteTier);
+
+/**
+ * Tier 3: `@CheckAbility("users:block")`. Requires `AuthGuard`, then the variant's authorization
+ * guard, then `AbilityGuard`, so `req.ability` is populated and checked. Several slugs may be
+ * named, and **all** of them must be held — the guard 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 — "this route
+ * requires something that does not exist" stays a compile error rather than a 403 nobody can
+ * explain. Which *users* hold the slug is entirely a matter of rows.
+ */
+export const CheckAbility = (...abilities: PermissionSlug[]) =>
+  applyBoth(SetMetadata(ROUTE_TIER_KEY, "ability" satisfies RouteTier), SetMetadata(CHECK_ABILITY_KEY, abilities as string[]));
+
+/** `applyDecorators` from @nestjs/common, minus its class-decorator branch — these two are method decorators. */
+function applyBoth(...decorators: MethodDecorator[]): MethodDecorator {
+  return (target, key, descriptor) => {
+    for (const decorate of decorators) decorate(target, key, descriptor);
+    return descriptor;
+  };
+}
+
+/** A guard entry in `@UseGuards` may be a class or an already-constructed instance; both reduce to a class. */
+type GuardEntry = Function | { constructor: Function };
+
+const guardClassesOn = (target: object): Function[] =>
+  ((Reflect.getMetadata(GUARDS_METADATA, target) as GuardEntry[] | undefined) ?? []).map((g) => (typeof g === "function" ? g : g.constructor));
+
+const joinPath = (...parts: unknown[]) =>
+  "/" +
+  parts
+    .filter((p): p is string => typeof p === "string")
+    .flatMap((p) => p.split("/"))
+    .filter((segment) => segment.length > 0)
+    .join("/");
+
+/** Own methods carrying Nest's route metadata. Controllers here are flat classes; inherited routes are not a shape this combo uses. */
+function routeHandlersOf(controller: Function): Array<{ name: string; handler: Function }> {
+  const prototype = controller.prototype as Record<string, unknown>;
+  return Object.getOwnPropertyNames(prototype)
+    .filter((name) => name !== "constructor")
+    .map((name) => ({ name, handler: prototype[name] }))
+    .filter((entry): entry is { name: string; handler: Function } => typeof entry.handler === "function")
+    .filter((entry) => Reflect.getMetadata(PATH_METADATA, entry.handler) !== undefined);
+}
+
+/**
+ * Fail-closed at startup, over the whole route table this library owns.
+ *
+ * Called from `AuthModule.forRoot` with the very array that populates `controllers:`, so a
+ * controller cannot be added to the module and left out of the check — there is only one list.
+ * It runs before anything else in `forRoot`, so a build with an ungated route creates no database
+ * client, opens no port, and reports every offending route in one message rather than the first.
+ *
+ * Scope note: this covers the combo's own controllers, not the consuming application's. A library
+ * that refused to boot until every route in someone else's app carried one of *its* markers would
+ * be indefensible; what it guarantees is that no route shipped by this library is ungated by
+ * omission.
+ *
+ * @param controllers the module's controller classes
+ * @param guards      the two guard classes whose presence defines tiers 2 and 3
+ */
+export function assertEveryRouteDeclaresATier(controllers: readonly Function[], guards: { authentication: Function; ability: Function }): void {
+  const offenders: string[] = [];
+
+  for (const controller of controllers) {
+    const controllerPath = Reflect.getMetadata(PATH_METADATA, controller);
+    const controllerGuards = guardClassesOn(controller);
+
+    for (const { name, handler } of routeHandlersOf(controller)) {
+      const method = RequestMethod[Reflect.getMetadata(METHOD_METADATA, handler) as RequestMethod] ?? "?";
+      const route = `${method} ${joinPath(controllerPath, Reflect.getMetadata(PATH_METADATA, handler))} (${controller.name}.${name})`;
+
+      const tier: RouteTier | undefined = Reflect.getMetadata(ROUTE_TIER_KEY, handler) ?? Reflect.getMetadata(ROUTE_TIER_KEY, controller);
+      if (!tier) {
+        offenders.push(`${route} — declares no tier: add @Public(), @Authenticated(), or @CheckAbility(slug)`);
+        continue;
+      }
+
+      // A tier is a claim about what protects the route. Check the claim against the guards that
+      // are actually attached, so "marked but not wired" cannot masquerade as "gated".
+      const attached = [...controllerGuards, ...guardClassesOn(handler)];
+      const authenticated = attached.includes(guards.authentication);
+      const ability = attached.includes(guards.ability);
+
+      if (tier === "public" && (authenticated || ability)) offenders.push(`${route} — declares @Public() but is behind ${attached.map((g) => g.name).join(", ")}`);
+      if (tier === "authenticated" && !authenticated) offenders.push(`${route} — declares @Authenticated() but has no ${guards.authentication.name}`);
+      if (tier === "authenticated" && ability) offenders.push(`${route} — declares @Authenticated() but is behind ${guards.ability.name}; use @CheckAbility instead`);
+      if (tier === "ability" && !(authenticated && ability))
+        offenders.push(`${route} — declares @CheckAbility but is not behind ${guards.authentication.name} + ${guards.ability.name}`);
+    }
+  }
+
+  if (offenders.length) {
+    throw new Error(
+      `${offenders.length} route(s) are not correctly tiered — refusing to start:\n  ` +
+        offenders.join("\n  ") +
+        `\n\nEvery route must be exactly one of: @Public() (no auth), @Authenticated() (any logged-in user), @CheckAbility(slug) (a permission).`,
+    );
+  }
+}

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

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+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 { AUTH_CONFIG, AuthConfig } from "./auth.config.js";
+import { DRIZZLE_DB, 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,
+});
+
+@Injectable()
+export class SessionRepository implements SessionStoreDeps {
+  constructor(
+    @Inject(DRIZZLE_DB) private readonly db: Database,
+    @Inject(AuditLogRepository) private readonly auditLog: AuditLogRepository,
+    @Inject(AUTH_CONFIG) 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/nestjs-drizzle/shared/src/two-factor.repository.ts

@@ -0,0 +1,35 @@
+import { Inject, Injectable } from "@nestjs/common";
+import { and, eq, isNull } from "drizzle-orm";
+import { verifyBackupCode } from "@/lib/auth/core/two-factor.js";
+import { DRIZZLE_DB, type Database } from "./db.js";
+import { twoFactorBackupCodes } from "./schema.js";
+
+// 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.
+@Injectable()
+export class TwoFactorRepository {
+  constructor(@Inject(DRIZZLE_DB) private readonly db: Database) {}
+
+  /** Replaces any prior set — re-confirming enrollment invalidates old backup codes. */
+  async saveBackupCodes(userId: bigint, hashes: string[]): Promise<void> {
+    await this.db.delete(twoFactorBackupCodes).where(eq(twoFactorBackupCodes.userId, userId));
+    if (hashes.length === 0) return;
+    await this.db.insert(twoFactorBackupCodes).values(hashes.map((codeHash) => ({ userId, codeHash })));
+  }
+
+  async consumeBackupCode(userId: bigint, code: string): Promise<boolean> {
+    const unused = await this.db
+      .select()
+      .from(twoFactorBackupCodes)
+      .where(and(eq(twoFactorBackupCodes.userId, userId), isNull(twoFactorBackupCodes.usedAt)));
+    const match = unused.find((row) => verifyBackupCode(code, row.codeHash));
+    if (!match) return false;
+
+    await this.db.update(twoFactorBackupCodes).set({ usedAt: new Date() }).where(eq(twoFactorBackupCodes.id, match.id));
+    return true;
+  }
+
+  async clearBackupCodes(userId: bigint): Promise<void> {
+    await this.db.delete(twoFactorBackupCodes).where(eq(twoFactorBackupCodes.userId, userId));
+  }
+}

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

@@ -0,0 +1,49 @@
+import "reflect-metadata";
+import { Module } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { AuthModule } from "../src/auth.module.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();
+
+/**
+ * The app module is built *inside* `bootstrap()`, not at import time.
+ *
+ * `AuthModule.forRoot` is where the startup route-tier check runs, and the proof needs to call
+ * bootstrap twice: once with a deliberately untiered route present, expecting the boot to fail,
+ * and once without. A module built at import time would have run the check before the proof could
+ * arrange either case.
+ */
+export async function bootstrap(port: number) {
+  @Module({
+    imports: [
+      AuthModule.forRoot({
+        // 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);
+        },
+      }),
+    ],
+  })
+  class AppModule {}
+
+  const app = await NestFactory.create(AppModule, { logger: false });
+  await app.listen(port);
+  return app;
+}