@simple-auth-kit/cli 1.0.0

package/registry/admin-apps/react/variants/workspaces/src/stores/store-context.tsx

@@ -0,0 +1,43 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { authClient, bindActiveWorkspace } from "@/lib/auth-client";
+import { AuthStore } from "./auth-store";
+import { WorkspaceStore } from "./workspace-store";
+
+export const workspaceStore = new WorkspaceStore(authClient);
+
+/**
+ * The one place the two stores are joined, and the only place that knows the order they depend
+ * on each other in:
+ *
+ *   • a session isn't usable until the workspace list has loaded, because `/auth/me` reports the
+ *     caller's roles and permissions *in the active workspace* and answers empty without one;
+ *   • switching workspaces invalidates those permissions, so it re-reads the session.
+ */
+export const authStore = new AuthStore(authClient, {
+  onSessionEstablished: () => workspaceStore.load(),
+  onSessionEnded: () => workspaceStore.reset(),
+});
+
+workspaceStore.bindOnActiveChanged(() => authStore.refreshCurrentUser());
+
+// From here on every workspace-scoped call carries whichever workspace the store says is active.
+bindActiveWorkspace(() => workspaceStore.activeWorkspaceId);
+
+interface Stores {
+  auth: AuthStore;
+  workspaces: WorkspaceStore;
+}
+
+const StoreContext = createContext<Stores>({ auth: authStore, workspaces: workspaceStore });
+
+export function StoreProvider({ children }: { children: ReactNode }) {
+  return <StoreContext.Provider value={{ auth: authStore, workspaces: workspaceStore }}>{children}</StoreContext.Provider>;
+}
+
+export function useAuthStore(): AuthStore {
+  return useContext(StoreContext).auth;
+}
+
+export function useWorkspaceStore(): WorkspaceStore {
+  return useContext(StoreContext).workspaces;
+}

package/registry/admin-apps/react/variants/workspaces/src/stores/workspace-store.ts

@@ -0,0 +1,120 @@
+import { makeAutoObservable, runInAction } from "mobx";
+import type { AuthClient, WorkspaceSummary } from "@simple-auth-kit/auth-client";
+
+const ACTIVE_WORKSPACE_KEY = "simple-auth-kit-active-workspace";
+
+/**
+ * Owns "which workspace am I in". `AuthClient` is configured with a resolver pointing at
+ * `activeWorkspaceId` (see `src/lib/auth-client.ts`), so this store is the single source of the
+ * `X-Workspace-Id` header on every scoped call — nothing else passes a workspace per call.
+ *
+ * The active workspace also decides what the caller may do: roles and permissions are per
+ * membership, so `/auth/me` answers differently in each workspace. Switching therefore has to
+ * re-read the session, which is what `bindOnActiveChanged` is for — the app wires it to
+ * `AuthStore.refreshCurrentUser` once, rather than every switch site remembering to.
+ */
+export class WorkspaceStore {
+  workspaces: WorkspaceSummary[] = [];
+  activeWorkspaceId: string | null = null;
+  /** True while the workspace list is being (re)loaded — distinct from "loaded and empty". */
+  loading = false;
+  loaded = false;
+
+  #client: AuthClient;
+  #onActiveChanged: () => Promise<void> = async () => {};
+
+  constructor(client: AuthClient) {
+    this.#client = client;
+    this.activeWorkspaceId = readStoredWorkspaceId();
+    makeAutoObservable(this, {}, { autoBind: true });
+  }
+
+  bindOnActiveChanged(handler: () => Promise<void>): void {
+    this.#onActiveChanged = handler;
+  }
+
+  get activeWorkspace(): WorkspaceSummary | null {
+    return this.workspaces.find((workspace) => workspace.id === this.activeWorkspaceId) ?? null;
+  }
+
+  get hasWorkspace(): boolean {
+    return this.activeWorkspace !== null;
+  }
+
+  /**
+   * Loads the caller's workspaces and settles the active one: the workspace they were last in if
+   * they are still a member of it, otherwise their first. Called on every session start, so a
+   * membership removed while they were away can't leave a dead id in the header.
+   */
+  async load(): Promise<void> {
+    runInAction(() => {
+      this.loading = true;
+    });
+    try {
+      const workspaces = await this.#client.listWorkspaces();
+      runInAction(() => {
+        this.workspaces = workspaces;
+        const stillAMember = workspaces.some((workspace) => workspace.id === this.activeWorkspaceId);
+        this.activeWorkspaceId = stillAMember ? this.activeWorkspaceId : (workspaces[0]?.id ?? null);
+        storeWorkspaceId(this.activeWorkspaceId);
+      });
+    } finally {
+      runInAction(() => {
+        this.loading = false;
+        this.loaded = true;
+      });
+    }
+  }
+
+  /** Switches workspaces and re-reads the session, because permissions are per membership. */
+  async setActive(workspaceId: string): Promise<void> {
+    if (workspaceId === this.activeWorkspaceId) return;
+    runInAction(() => {
+      this.activeWorkspaceId = workspaceId;
+      storeWorkspaceId(workspaceId);
+    });
+    await this.#onActiveChanged();
+  }
+
+  /** Creates a workspace and switches to it. The backend makes the creator its administrator in the same transaction. */
+  async create(name: string): Promise<WorkspaceSummary> {
+    const workspace = await this.#client.createWorkspace(name);
+    runInAction(() => {
+      this.workspaces = [...this.workspaces, workspace];
+      this.activeWorkspaceId = workspace.id;
+      storeWorkspaceId(workspace.id);
+    });
+    await this.#onActiveChanged();
+    return workspace;
+  }
+
+  /** Re-reads the workspace list without changing which one is active (roles may have changed). */
+  async reload(): Promise<void> {
+    await this.load();
+  }
+
+  reset(): void {
+    this.workspaces = [];
+    this.activeWorkspaceId = null;
+    this.loaded = false;
+    storeWorkspaceId(null);
+  }
+}
+
+function readStoredWorkspaceId(): string | null {
+  try {
+    return window.localStorage.getItem(ACTIVE_WORKSPACE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function storeWorkspaceId(workspaceId: string | null): void {
+  try {
+    if (workspaceId === null) window.localStorage.removeItem(ACTIVE_WORKSPACE_KEY);
+    else window.localStorage.setItem(ACTIVE_WORKSPACE_KEY, workspaceId);
+  } catch {
+    // A private-mode browser with storage disabled just loses the remembered workspace between
+    // page loads; `load()` falls back to the first one.
+  }
+}

package/registry/admin-apps/react/variants/workspaces/vite.config.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath, URL } from "node:url";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+  server: {
+    port: 5174,
+  },
+});

package/registry/combos/express-drizzle/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@simple-auth-kit/combo-express-drizzle",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Structural diff of the nestjs-prisma reference combo: Express + Drizzle, no NestJS at all. Two variants (base, workspaces) composed from shared/ + variants/<variant>/.",
+  "type": "module",
+  "scripts": {
+    "materialize": "node scripts/materialize.mjs",
+    "typecheck": "node scripts/materialize.mjs --all && tsc -p .variant/base && tsc -p .variant/workspaces",
+    "prove-cycle": "node scripts/prove-cycle.mjs",
+    "migrate": "node scripts/migrate.mjs",
+    "seed": "node scripts/seed.mjs"
+  },
+  "dependencies": {
+    "@casl/ability": "^7.0.1",
+    "drizzle-orm": "^0.45.2",
+    "express": "^5.2.1",
+    "pg": "^8.23.0",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.2.0",
+    "@types/pg": "^8.21.0",
+    "@types/swagger-ui-express": "^4.1.8",
+    "dotenv": "^17.4.2",
+    "drizzle-kit": "^0.31.10",
+    "tsx": "^4.23.11",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}

package/registry/combos/express-drizzle/scripts/materialize.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// Composes a runnable copy of one variant of this combo into `.variant/<variant>/`.
+//
+// A variant is `shared/` + `variants/<variant>/` overlaid on top of each other — exactly what
+// `simple-auth-kit add <combo> [--workspaces]` copies into a consumer's project. Composing it here
+// too means the thing this package typechecks and runs `prove-cycle` against is byte-for-byte
+// the thing the CLI emits, rather than a second wiring that can drift from it.
+//
+// Usage:
+//   node scripts/materialize.mjs <variant>|--all
+//
+// Unlike the Prisma combos there is no client-generation step: Drizzle's schema *is* the
+// TypeScript in `src/schema.ts`, so a composed variant is immediately typecheckable.
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const COMBO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const VARIANTS = ["base", "workspaces"];
+
+/** Composed trees are throwaway — every entry a variant owns is replaced wholesale on each run. */
+const REPLACED_ENTRIES = ["src", "drizzle", "test", "drizzle.config.ts", "tsconfig.json", ".env", ".env.example", ".gitignore"];
+
+const TSCONFIG = {
+  // Depth is fixed by the layout: <repo>/registry/combos/<combo>/.variant/<variant>/
+  extends: "../../../../../tsconfig.base.json",
+  compilerOptions: { paths: { "@/lib/auth/core/*": ["../../../../core/*"] } },
+  include: ["src", "test", "drizzle.config.ts"],
+  exclude: ["node_modules"],
+};
+
+/** Each variant owns its own database — their schemas are different shapes, not different states of one. */
+export function databaseUrlFor(variant, baseUrl) {
+  if (variant === "base") return baseUrl;
+  return baseUrl.replace(/^(.*\/)([^/?]+)(\?.*)?$/, (_m, prefix, db, query) => `${prefix}${db}_${variant}${query ?? ""}`);
+}
+
+async function rootEnv() {
+  return readFile(join(COMBO_ROOT, ".env"), "utf8");
+}
+
+export async function baseDatabaseUrl() {
+  const match = (await rootEnv()).match(/^\s*DATABASE_URL\s*=\s*"?([^"\n]+)"?/m);
+  if (!match) throw new Error(`no DATABASE_URL in ${join(COMBO_ROOT, ".env")}`);
+  return match[1];
+}
+
+/**
+ * `drizzle-kit migrate` applies migrations but will not create the database to apply them to
+ * (Prisma's `migrate dev` does, which is why the reference combo needs no equivalent). Both
+ * scripts that touch a database call this first so a clean checkout can prove itself.
+ */
+export async function ensureDatabase(url) {
+  const { Client } = await import("pg");
+  const target = new URL(url);
+  const name = decodeURIComponent(target.pathname.replace(/^\//, ""));
+
+  const admin = new URL(url);
+  admin.pathname = "/postgres";
+  const client = new Client({ connectionString: admin.toString() });
+  await client.connect();
+  try {
+    const { rowCount } = await client.query("SELECT 1 FROM pg_database WHERE datname = $1", [name]);
+    // Identifier, not a value — pg has no placeholder for one, so it is quoted by hand.
+    if (!rowCount) await client.query(`CREATE DATABASE "${name.replace(/"/g, '""')}"`);
+  } finally {
+    await client.end();
+  }
+}
+
+export async function materialize(variant) {
+  if (!VARIANTS.includes(variant)) throw new Error(`unknown variant "${variant}" (expected one of: ${VARIANTS.join(", ")})`);
+  const dest = join(COMBO_ROOT, ".variant", variant);
+
+  await mkdir(dest, { recursive: true });
+  await Promise.all(REPLACED_ENTRIES.map((entry) => rm(join(dest, entry), { recursive: true, force: true })));
+
+  // Order matters: the variant overlay goes last, so `variants/<variant>/test/*` replaces the
+  // shared test scaffolding of the same name (that is how variant-hooks.ts is supplied).
+  await cp(join(COMBO_ROOT, "shared"), dest, { recursive: true });
+  await cp(join(COMBO_ROOT, "test"), join(dest, "test"), { recursive: true });
+  await cp(join(COMBO_ROOT, "variants", variant), dest, { recursive: true });
+
+  await writeFile(join(dest, "tsconfig.json"), JSON.stringify(TSCONFIG, null, 2) + "\n", "utf8");
+  // Forward the whole root `.env` (AUTH_JWT_SECRET and anything else a consumer would set) —
+  // only DATABASE_URL is rewritten, to point at this variant's own database.
+  const withVariantDatabase = (await rootEnv()).replace(
+    /^\s*DATABASE_URL\s*=.*$/m,
+    `DATABASE_URL="${databaseUrlFor(variant, await baseDatabaseUrl())}"`,
+  );
+  await writeFile(join(dest, ".env"), withVariantDatabase, "utf8");
+
+  return dest;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const requested = args.filter((a) => !a.startsWith("--"));
+  const variants = args.includes("--all") || requested.length === 0 ? VARIANTS : requested;
+  for (const variant of variants) {
+    const dest = await materialize(variant);
+    console.log(`materialized ${variant} -> ${dest}`);
+  }
+}

package/registry/combos/express-drizzle/scripts/migrate.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Authors a migration for one variant and copies it back into the registry.
+//
+// `drizzle-kit` resolves `drizzle.config.ts` relative to its working directory, and that config's
+// `schema`/`out` paths are relative too — so the only directory where they line up is the
+// materialized variant. Migrations are therefore generated there and copied back into
+// `variants/<variant>/drizzle`, which is what the CLI actually ships.
+//
+// Migrations are regenerated clean per variant, never amended with drop-column migrations: the
+// CLI copies this directory verbatim into every consumer's repo. Pass `--fresh` to discard the
+// variant's existing migrations first, which is what "regenerate clean" means in practice.
+//
+// Usage: node scripts/migrate.mjs [variant ...] [--name <migration-name>] [--fresh]
+import { execFileSync } from "node:child_process";
+import { cp, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { baseDatabaseUrl, databaseUrlFor, ensureDatabase, materialize, VARIANTS } from "./materialize.mjs";
+
+const COMBO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const args = process.argv.slice(2);
+const nameIndex = args.indexOf("--name");
+const name = nameIndex === -1 ? "init" : args[nameIndex + 1];
+const fresh = args.includes("--fresh");
+const variants = args.filter((a, i) => !a.startsWith("--") && i !== nameIndex + 1);
+
+for (const variant of variants.length ? variants : VARIANTS) {
+  const registryMigrations = join(COMBO_ROOT, "variants", variant, "drizzle");
+  if (fresh) await rm(registryMigrations, { recursive: true, force: true });
+
+  const dest = await materialize(variant);
+  await ensureDatabase(databaseUrlFor(variant, await baseDatabaseUrl()));
+
+  execFileSync("npx", ["drizzle-kit", "generate", "--name", name], { cwd: dest, stdio: "inherit" });
+  execFileSync("npx", ["drizzle-kit", "migrate"], { cwd: dest, stdio: "inherit" });
+
+  await rm(registryMigrations, { recursive: true, force: true });
+  await cp(join(dest, "drizzle"), registryMigrations, { recursive: true });
+  console.log(`\nwrote migrations back to variants/${variant}/drizzle`);
+}

package/registry/combos/express-drizzle/scripts/prove-cycle.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Runs the black-box proof against one or both variants of this combo.
+//
+// Each variant is materialized, its migrations applied to its own database, seeded, and then
+// `test/prove-cycle.ts` is run inside it with AUTH_VARIANT set — the test asserts the shared auth
+// cycle for both, plus the workspace isolation properties for the workspace variant.
+//
+// The seed step is not a convenience. "The seeder is a prerequisite, not an extra": until it has
+// run there is no role flagged `isDefault`, so a signup is given nothing and the very first
+// assertion about database-resolved roles fails. Running it here means the proof states that
+// dependency instead of inheriting it from whatever the developer's database happened to contain.
+//
+// Usage: node scripts/prove-cycle.mjs [variant ...]   (default: every variant)
+import { execFileSync } from "node:child_process";
+import { baseDatabaseUrl, databaseUrlFor, ensureDatabase, materialize, VARIANTS } from "./materialize.mjs";
+
+const requested = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+const variants = requested.length ? requested : VARIANTS;
+
+for (const variant of variants) {
+  console.log(`\n=== prove-cycle: ${variant} ===\n`);
+  const dest = await materialize(variant);
+  await ensureDatabase(databaseUrlFor(variant, await baseDatabaseUrl()));
+  execFileSync("npx", ["drizzle-kit", "migrate"], { cwd: dest, stdio: "inherit" });
+  // The consumer-facing seeder, run exactly as a consumer runs it. Idempotent, so a database that
+  // has already been seeded is unaffected.
+  execFileSync("npx", ["tsx", "src/seed.ts"], { cwd: dest, stdio: "inherit" });
+  execFileSync("npx", ["tsx", "test/prove-cycle.ts"], { cwd: dest, stdio: "inherit", env: { ...process.env, AUTH_VARIANT: variant } });
+}

package/registry/combos/express-drizzle/scripts/seed.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Runs a variant's seeder against this combo's own dev database.
+//
+// The seeder is consumer-facing source (`variants/<variant>/src/seed.ts`, copied into every
+// project the CLI installs into), so it is run here the same way a consumer runs it: from the
+// materialized variant, with that variant's `.env` supplying DATABASE_URL. Nothing about the
+// seeder is test scaffolding, and there is no second copy of it living in `scripts/`.
+//
+// Usage:
+//   node scripts/seed.mjs [variant ...]                  (default: every variant)
+//   SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... node scripts/seed.mjs base
+//
+// Variables set in the environment win over the variant's `.env` — see seed.ts.
+import { execFileSync } from "node:child_process";
+import { baseDatabaseUrl, databaseUrlFor, ensureDatabase, materialize, VARIANTS } from "./materialize.mjs";
+
+const requested = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+const variants = requested.length ? requested : VARIANTS;
+
+for (const variant of variants) {
+  console.log(`\n=== seed: ${variant} ===\n`);
+  const dest = await materialize(variant);
+  await ensureDatabase(databaseUrlFor(variant, await baseDatabaseUrl()));
+  execFileSync("npx", ["tsx", "src/seed.ts"], { cwd: dest, stdio: "inherit" });
+}

package/registry/combos/express-drizzle/shared/drizzle.config.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config as loadDotenv } from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+
+// Plain `import "dotenv/config"` only loads `.env` relative to the process's cwd, which misses
+// the project's real `.env` at the root. Resolve from this file's own location instead and walk
+// up until a `.env` is found.
+function loadNearestEnv(startDir: string): void {
+  let dir = startDir;
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = join(dir, ".env");
+    if (existsSync(candidate)) {
+      loadDotenv({ path: candidate });
+      return;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+loadNearestEnv(thisDir);
+
+// The CLI installs this file at the project root (<targetRoot>/drizzle.config.ts, alongside
+// drizzle/) — Drizzle's own convention, so `npx drizzle-kit ...` need no `cd` and find it
+// automatically. schema.ts itself stays inside the merged auth-lib directory with the rest of
+// this combo's source, so its directory can't be a fixed relative string once this file moves.
+//
+// Two contexts share this file, and they disagree about where that directory is:
+//   - registry/combos/*/scripts/materialize.mjs (this combo's own dev/typecheck/prove-cycle
+//     loop) flatly composes shared/+variants/<v>/ into one directory, so schema.ts's directory
+//     is right next to this file — no .simple-auth-kit.json is ever written there.
+//   - a real consumer install: this file lives at the project root while schema.ts stays nested
+//     under the merged auth-lib directory, whose path is recorded in .simple-auth-kit.json
+//     (falling back to the CLI's own default when that file is absent).
+// Probing for the sibling first covers both without hardcoding either shape.
+function resolveSchemaDir(): string {
+  const sibling = join(thisDir, "src");
+  if (existsSync(join(sibling, "schema.ts"))) return sibling;
+
+  let authLibPath = "src/lib/auth";
+  try {
+    const parsed = JSON.parse(readFileSync(join(thisDir, ".simple-auth-kit.json"), "utf8")) as { path?: string };
+    if (parsed.path) authLibPath = parsed.path;
+  } catch {
+    // no .simple-auth-kit.json (defaults apply) — fall through with the CLI's own default path
+  }
+  return join(thisDir, authLibPath, "src");
+}
+
+const schemaDir = resolveSchemaDir();
+
+export default defineConfig({
+  dialect: "postgresql",
+  // schema.ts is the CLI-managed file — never edit it directly, it's overwritten on every
+  // update. Add your own tables in a sibling file named *.schema.ts in this same directory
+  // (e.g. billing.schema.ts) instead: drizzle-kit merges every matched file's exports into one
+  // schema, and the CLI only ever tracks schema.ts by exact name, so your file is never touched.
+  schema: [join(schemaDir, "schema.ts"), join(schemaDir, "*.schema.ts")],
+  out: join(thisDir, "drizzle"),
+  dbCredentials: {
+    url: process.env["DATABASE_URL"]!,
+  },
+});

package/registry/combos/express-drizzle/shared/src/ability.ts

@@ -0,0 +1,44 @@
+// The whole ability model, in one function. Deliberately tiny, and deliberately not a Nest
+// provider: it has no dependencies, does no I/O, and is imported by the server *and* by whatever
+// renders the admin UI, so it must be usable outside a DI container and outside Node.
+//
+//   server:  const ability = defineAbilitiesFor(await permissions.forUser(userId))
+//            ability.can("users:read", ABILITY_SUBJECT)     ← AbilityGuard
+//   client:  const ability = defineAbilitiesFor(me.permissions)   ← from GET /auth/me
+//            ability.can("users:read", ABILITY_SUBJECT)     ← show/hide a button
+//
+// Both sides build the ability from the same input (a flat list of permission slugs) with the
+// same function, so the console cannot offer an action the API will refuse. `GET /auth/me` ships
+// the slugs, not a serialised ability: the wire format is the permission list a human can read in
+// a log, and the ability is a local derivation on either side.
+//
+// A permission slug is used as CASL's *action* and the subject is a constant empty string.
+// That is what makes the model flat: there is no subject taxonomy to keep in sync with the
+// database, no `(action, subject)` pairing to get wrong, and no conditions — which in turn means
+// there is no such thing as a rule the route guard can only *partially* evaluate. What a slug
+// means is decided entirely by which routes name it.
+import { AbilityBuilder, createMongoAbility, type MongoAbility } from "@casl/ability";
+
+/**
+ * The subject every rule is written against. CASL needs one; this model does not use subjects, so
+ * there is exactly one, and it is a constant rather than a string literal repeated at each call
+ * site — `can("users:read", "")` in one place and `can("users:read", "all")` in another would
+ * silently never match.
+ */
+export const ABILITY_SUBJECT = "";
+
+/** Actions are permission slugs; the subject is always `ABILITY_SUBJECT`. */
+export type AppAbility = MongoAbility<[string, typeof ABILITY_SUBJECT]>;
+
+/**
+ * Builds the ability for a set of permission slugs.
+ *
+ * An empty list builds an ability with no rules at all, which denies everything — the fail-closed
+ * answer for "we could not resolve any permissions", and the same answer as "this user genuinely
+ * has none". There is no default-allow branch anywhere in this file.
+ */
+export function defineAbilitiesFor(permissions: readonly string[] = []): AppAbility {
+  const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+  for (const permission of permissions) can(permission, ABILITY_SUBJECT);
+  return build();
+}

package/registry/combos/express-drizzle/shared/src/auth-core-error.middleware.ts

@@ -0,0 +1,31 @@
+import type { NextFunction, Request, Response } from "express";
+import { AuthCoreError } from "@/lib/auth/core/types.js";
+import { HttpError } from "./http-error.js";
+
+/**
+ * Replaces the reference combo's `AuthCoreErrorFilter` (a Nest global `@Catch` exception
+ * filter). Express has no filter system, so this is a standard 4-arg error-handling
+ * middleware — mount it last, after the routers. Maps `AuthCoreError` (thrown deep
+ * inside `registry/core/session-policy.ts`/`token-service.ts`, e.g. a stale/reused
+ * refresh token) to a 401 JSON response instead of falling through to a bare 500, and
+ * maps this combo's own `HttpError` to its intended status code — the plain-Express stand-in
+ * for the NestJS exception classes the reference throws.
+ */
+export function authCoreErrorMiddleware(err: unknown, _req: Request, res: Response, next: NextFunction): void {
+  if (res.headersSent) {
+    next(err);
+    return;
+  }
+
+  if (err instanceof AuthCoreError) {
+    res.status(401).json({ statusCode: 401, code: err.code, message: err.message });
+    return;
+  }
+
+  if (err instanceof HttpError) {
+    res.status(err.statusCode).json({ statusCode: err.statusCode, code: err.name, message: err.message });
+    return;
+  }
+
+  next(err);
+}

package/registry/combos/express-drizzle/shared/src/auth.config.ts

@@ -0,0 +1,63 @@
+import type { RateLimitDeps } from "@/lib/auth/core/rate-limit.js";
+import type { PermissionCacheStore } from "./permission-cache.js";
+
+export interface GoogleOAuthCredentials {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}
+
+export interface AppleOAuthCredentials {
+  clientId: string;
+  teamId: string;
+  keyId: string;
+  privateKey: string;
+  redirectUri: string;
+}
+
+export interface AuthConfig {
+  accessTokenTtlSeconds: number;
+  refreshTokenTtlSeconds: number;
+  /**
+   * A session's absolute lifetime, written to `sessions.expires_at` when it is created and
+   * **never extended**. Refresh rotation issues a new refresh token each time, so without this a
+   * continuously-active client could hold one session open forever; this is the cap that makes
+   * "log in again after N days" true regardless of activity. `rotateRefreshToken` enforces it.
+   */
+  sessionTtlSeconds: number;
+  /** App name shown inside authenticator apps next to the account (issuer part of the otpauth:// URI). */
+  twoFactorIssuer: string;
+  oauthProviders: {
+    google?: GoogleOAuthCredentials;
+    apple?: AppleOAuthCredentials;
+  };
+  /**
+   * How long a resolved permission set may sit in the cache. This is a safety net, not the
+   * invalidation mechanism: correctness comes from the version counters in permission-cache.ts,
+   * which make a stale entry unreachable the instant anything changes. Set to 0 to resolve from
+   * the database on every request — same answers, more queries.
+   */
+  permissionCacheTtlSeconds: number;
+  /**
+   * Where resolved permissions are cached. Defaults to an in-process `Map`, which is correct for
+   * a single instance; pass a Redis-backed implementation of `PermissionCacheStore` for several.
+   * Keys are namespaced `simpleauthkit:authz:*`.
+   */
+  permissionCacheStore?: PermissionCacheStore;
+  /**
+   * Where rate-limit counters live. Defaults to an in-process `Map`, which is correct for a
+   * single instance; pass a Redis-backed implementation of `RateLimitDeps` for several.
+   */
+  rateLimitStore?: RateLimitDeps;
+  /** Wire your own mailer here — if unset, requestPasswordReset() just returns the token without emailing it. */
+  sendPasswordResetEmail?: (email: string, token: string) => Promise<void>;
+}
+
+export const defaultAuthConfig: AuthConfig = {
+  accessTokenTtlSeconds: 900,
+  permissionCacheTtlSeconds: 300,
+  refreshTokenTtlSeconds: 60 * 60 * 24 * 30,
+  sessionTtlSeconds: 60 * 60 * 24 * 30,
+  twoFactorIssuer: "simple-auth-kit",
+  oauthProviders: {},
+};

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

@@ -0,0 +1,38 @@
+import type { NextFunction, Request, Response } from "express";
+import { verifyAccessToken } from "@/lib/auth/core/token-service.js";
+import { KeyProviderService } from "./key-provider.js";
+import "./request-context.js";
+import { SessionRepository } from "./session.repository.js";
+
+/**
+ * Authentication only — proves who the caller is and populates `req.auth`. Authorization
+ * (`req.authz`) is a deliberately separate step: pair this with the authz middleware on any
+ * route that checks roles or permissions.
+ *
+ * Express middleware equivalent of the reference combo's auth.guard.ts (a NestJS
+ * `CanActivate`). Express has no guard/decorator system, so this is a plain factory function
+ * returning a request handler — mount it directly on whichever routes need it.
+ */
+export function createAuthMiddleware(keys: KeyProviderService, sessions: SessionRepository) {
+  return async function authMiddleware(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const header = req.headers["authorization"];
+    if (!header?.startsWith("Bearer ")) {
+      res.status(401).json({ statusCode: 401, code: "UNAUTHORIZED", message: "missing bearer token" });
+      return;
+    }
+
+    try {
+      req.auth = await verifyAccessToken(
+        { secret: keys.secret, isDenylisted: (jti) => sessions.isDenylisted(jti) },
+        header.slice("Bearer ".length),
+      );
+      next();
+    } catch (err) {
+      res.status(401).json({
+        statusCode: 401,
+        code: "UNAUTHORIZED",
+        message: err instanceof Error ? err.message : "invalid access token",
+      });
+    }
+  };
+}