@stjoseph/prumo 0.2.0 → 0.3.0

package/.prumo-templates/multi-tenancy/isolation.md

@@ -5,14 +5,16 @@
 Derive the active tenant from the session. **Never from anything the client sends**: not a header, not a
 path parameter, not the `Host`.
 
-Use Better Auth's `organization` plugin with `activeOrganizationId` **persisted in the session**. Do not
-manage the active organization client-side.
+Keep organizations in the `auth` module: an `Organization` entity, and a `Membership` joining a user to one.
+Store the active tenant on the `Session` row, as `active_organization_id`, and copy it into the access token as
+a claim each time one is issued or refreshed. Switch tenants through one route that checks the membership,
+updates the session and issues a new access token. Do not manage the active organization client-side.
 
 Give every tenant-scoped table a `tenant_id` that is `NOT NULL` and carries a foreign key into
 `organization`, with `ON DELETE RESTRICT`.
 
 Register the MikroORM filter with `default: true` and set its parameter once per request, from the
-session.
+verified access token's claim.
 
 **Never accept `tenant_id` as a method argument.** Read it where the filter's parameter is read.
 
@@ -22,7 +24,8 @@ a comment saying it was checked.
 Declare a route that has no tenant. **Treat an absent filter parameter as an error**, never as "no
 filter".
 
-Run Better Auth's migrations before ours.
+When a membership ends, revoke that user's sessions with it, or the departed member keeps the tenant until the
+access token expires.
 
 ## Rationale
 
@@ -32,9 +35,13 @@ forgetting is invisible, because the route works perfectly for someone entitled
 someone who is not. A subdomain is input too: it arrives in a header a client controls and that proxies
 rewrite, so the defence would rest on infrastructure configuration.
 
-Better Auth's own documentation offers managing the active organization client-side, for multiple tabs. For
-a multi-tenant system that means the **tab** decides isolation, so it is refused here by name: somebody
-will find that sentence.
+Keeping the active organization in the client, per tab, is a common suggestion for working in two tenants at
+once. For a multi-tenant system that means the **tab** decides isolation, so it is refused here by name:
+somebody will find that suggestion.
+
+The claim is read from a token whose signature was just verified, so no request touches the database to learn
+its tenant. The cost is the token's lifetime: a membership removed now still reads for up to fifteen minutes,
+unless the sessions go with it, which is why the rule asks for both.
 
 The filter is an application-level guard, and its own documentation says a raw query or a forgotten
 `filters` option reads past it. It leaves three holes and they get different answers, because the problems
@@ -48,8 +55,8 @@ did not load, middleware in the wrong order) into a query that returns the whole
 
 The foreign key exists because without it a `tenant_id` pointing nowhere inserts cleanly and passes tests,
 leaving a row invisible to every filtered query. `RESTRICT` means deleting an organization with business
-data fails, which is wanted: the application should decide what happens to that data rather than a library
-CLI cascading it away.
+data fails, which is wanted: the application should decide what happens to that data rather than a cascade
+deciding for it.
 
 ## Applies to
 
@@ -64,7 +71,7 @@ decision rather than configuration.
 Where the tenant comes from:
 
 ```
-✅  const tenantId = session.activeOrganizationId
+✅  const tenantId = claims.organizationId          // from the verified access token
 ❌  const tenantId = req.headers['x-tenant-id']
 ❌  const tenantId = subdomainOf(req.headers.host)
 ```

package/README.md

@@ -88,9 +88,9 @@ is asked, and the exit code is 0 only when `ok` is true.
 
 | Type | What you get |
 |---|---|
-| `api` | Fastify with a domain/infra structure, tsyringe, Zod, MikroORM on PostgreSQL, Better Auth in a schema of its own, Swagger UI, Vitest with Testcontainers |
+| `api` | Fastify with a domain/infra structure, tsyringe, Zod, MikroORM on PostgreSQL, its own JWT authentication, Swagger UI, Vitest with Testcontainers |
 | `web` | Vite, React, TanStack Router and Query, Tailwind, shadcn/ui, forms validated with Zod |
-| `mobile` | Expo with Expo Router, NativeWind, MMKV, and the session kept in `expo-secure-store` |
+| `mobile` | Expo with Expo Router, NativeWind, MMKV, and the tokens kept in `expo-secure-store` |
 | `site` | Next on the App Router, static by default, for pages that have to be indexed |
 
 One type produces that project on its own. Several produce a pnpm workspace: each application under

package/dist/clean.js

@@ -10,7 +10,7 @@ export const API_DEV_PREFIX = 'node scripts/database.mjs --check && ';
 export const ROOT_DEV_PREFIX = 'node apps/api/scripts/database.mjs --check && ';
 export const SETUP_SCRIPT = 'node scripts/database.mjs';
 export const EXAMPLE_BLOCK = '# MISSING until `pnpm db:setup` creates a database; `pnpm dev` offers to run it.\n' +
-    'DATABASE_URL=MISSING\nAUTH_DATABASE_URL=MISSING\n';
+    'DATABASE_URL=MISSING\n';
 export const README_PARAGRAPH = '`DATABASE_URL` starts as `MISSING`. While it is, `pnpm dev` offers to create the database first: it asks for a name,\n' +
     'starts Postgres from `docker-compose.yml` on port 5432 or the next free one (kept in `POSTGRES_PORT`), writes the URL\n' +
     'into `.env`, and migrates. `pnpm db:setup` does the same at any time. Without a terminal every answer comes from a\n' +
@@ -51,7 +51,7 @@ function rulesFor(root, api, templates) {
     const rules = [
         devRule('api-dev-check', at('package.json'), API_DEV_PREFIX),
         scriptRule('api-db-setup', at('package.json'), 'Remove the `db:setup` script', 'db:setup', (value) => value === SETUP_SCRIPT ? { status: 'pending' } : { status: 'modified', next: value }),
-        textRule('api-env-example', at('.env.example'), 'Put a sample database URL back in `.env.example`', EXAMPLE_BLOCK, `DATABASE_URL=${SAMPLE_URL}\nAUTH_DATABASE_URL=${SAMPLE_URL}\n`, '=MISSING'),
+        textRule('api-env-example', at('.env.example'), 'Put a sample database URL back in `.env.example`', EXAMPLE_BLOCK, `DATABASE_URL=${SAMPLE_URL}\n`, '=MISSING'),
         textRule('api-readme-setup', at('README.md'), 'Replace the README paragraph about `MISSING`', README_PARAGRAPH, README_REPLACEMENT, 'db:setup'),
         textRule('api-readme-row', at('README.md'), 'Remove `db:setup` from the README', README_ROW, '', '`pnpm db:setup`'),
     ];

package/dist/compose.js

@@ -182,7 +182,7 @@ async function assertCatalogCovers(target, catalog) {
         }
     }
 }
-export async function composeWorkspace({ templates, target, types, mobileScheme = 'app', mcp = false, }) {
+export async function composeWorkspace({ templates, target, types, mcp = false, }) {
     await mkdir(target, { recursive: true });
     await copyTemplate(join(templates, 'workspace'), target);
     const apps = [];
@@ -199,14 +199,6 @@ export async function composeWorkspace({ templates, target, types, mobileScheme
     else {
         await rm(join(target, 'packages'), { recursive: true, force: true });
     }
-    if (types.includes('api') && types.includes('mobile')) {
-        await rewriteText(join(target, 'apps', 'api', '.env.example'), (text) => {
-            if (!text.includes('# MOBILE_APP_SCHEME=app\n')) {
-                throw new Error('apps/api/.env.example no longer carries the commented MOBILE_APP_SCHEME line');
-            }
-            return text.replace('# MOBILE_APP_SCHEME=app\n', `MOBILE_APP_SCHEME=${mobileScheme}\n`);
-        });
-    }
     // One command for everything and one per app. Each app answers to `dev`, so the root never needs to know how.
     // The database and the ports are the exception: both may ask a question, which the interleaved output of a
     // parallel run would bury, so the root asks first and each app's own check then finds nothing to do.

package/dist/generate.js

@@ -24,7 +24,7 @@ async function nameMobileApp(app, name) {
         return setJsonc(result, ['expo', 'scheme'], schemeFor(name));
     });
 }
-const SECRET_LINE = /^BETTER_AUTH_SECRET=.*$/m;
+const SECRET_LINE = /^JWT_SECRET=.*$/m;
 // `.env` stays out of git, so the example is the committed truth and a fresh project gets a copy it can start with.
 // Only the secret differs: a sample value is public, so every generated API draws its own.
 async function writeLocalEnv(app, type) {
@@ -35,9 +35,9 @@ async function writeLocalEnv(app, type) {
     let env = await readFile(example, 'utf8');
     if (type === 'api') {
         if (!SECRET_LINE.test(env)) {
-            throw new Error(`${example} no longer carries a BETTER_AUTH_SECRET line`);
+            throw new Error(`${example} no longer carries a JWT_SECRET line`);
         }
-        env = env.replace(SECRET_LINE, `BETTER_AUTH_SECRET=${randomBytes(32).toString('base64url')}`);
+        env = env.replace(SECRET_LINE, `JWT_SECRET=${randomBytes(32).toString('base64url')}`);
     }
     await writeFile(join(app, '.env'), env);
 }
@@ -130,7 +130,6 @@ async function write({ templates, knowledge, target, answers, install, childOutp
             templates,
             target,
             types: answers.types,
-            mobileScheme: schemeFor(answers.name),
             mcp: answers.mcp,
         });
         await nameProject(target, answers.name);

package/dist/mcp.js

@@ -4,22 +4,29 @@ import { join } from 'node:path';
 import { setJsonc } from "./jsonc.js";
 // The api and web templates ship with MCP. A project that answered no receives them without it: these files are
 // deleted, these dependencies removed, and every marked line or block cut. Every other type has nothing to cut.
-const FILES = {
+// The API's MCP is its server and the OAuth authorization server that issues its tokens, with the table that
+// holds an authorization in a migration of its own, so a project without MCP never creates it.
+export const FILES = {
     api: [
         'src/infra/mcp',
+        'src/domain/oauth',
+        'src/infra/oauth',
+        'src/infra/di/oauth.di.ts',
+        'src/infra/http/fetch-bridge.ts',
         'src/infra/http/controllers/mcp.controller.ts',
+        'src/infra/http/controllers/oauth.controller.ts',
+        'src/infra/database/mikroorm/entities/authorization.schema.ts',
+        'src/infra/database/mikroorm/repositories/mikroorm-authorization.repository.ts',
+        'migrations/Migration20261002210631_create_authorization.ts',
+        'test/domain/oauth',
+        'test/infra/oauth',
         'test/infra/http/controllers/mcp.controller.spec.ts',
     ],
     web: ['src/features/oauth', 'src/routes/_authenticated/consent.tsx', 'test/features/oauth'],
 };
 const DEPENDENCIES = {
-    api: [
-        '@better-auth/cimd',
-        '@better-auth/mcp',
-        '@modelcontextprotocol/client',
-        '@modelcontextprotocol/server',
-    ],
-    web: ['@better-auth/oauth-provider'],
+    api: ['@modelcontextprotocol/client', '@modelcontextprotocol/server'],
+    web: [],
 };
 const BLOCK_START = /^\s*\/\/ prumo:mcp$/;
 const BLOCK_END = /^\s*\/\/ prumo:end-mcp$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",

package/templates/api/.env.example

@@ -4,12 +4,10 @@ LOG_LEVEL=info
 
 # MISSING until `pnpm db:setup` creates a database; `pnpm dev` offers to run it.
 DATABASE_URL=MISSING
-AUTH_DATABASE_URL=MISSING
 # Read by docker-compose.yml, not by the API: the port Postgres is published on.
 POSTGRES_PORT=5432
 
-BETTER_AUTH_SECRET=replace-this-with-at-least-32-characters
-BETTER_AUTH_URL=http://localhost:3000
+# Signs the access tokens. `prumo new` writes a random one into .env; never reuse it between environments.
+JWT_SECRET=replace-this-with-at-least-32-characters
+API_URL=http://localhost:3000
 WEB_ORIGIN=http://localhost:5173
-# Set only when a mobile app talks to this API; it enables Better Auth's Expo plugin.
-# MOBILE_APP_SCHEME=app

package/templates/api/README.md

@@ -11,7 +11,7 @@ pnpm install
 pnpm dev
 ```
 
-`.env` comes with the generated project, copied from `.env.example` with a random `BETTER_AUTH_SECRET`. It is not
+`.env` comes with the generated project, copied from `.env.example` with a random `JWT_SECRET`. It is not
 committed, so on a fresh clone run `cp .env.example .env` and replace the secret with 32 or more random characters.
 
 `DATABASE_URL` starts as `MISSING`. While it is, `pnpm dev` offers to create the database first: it asks for a name,
@@ -30,9 +30,8 @@ new port to `.env`, along with every URL that pointed at the old one. Without a
 Ctrl+C stops everything `pnpm dev` started, not only what the terminal signals: the script remembers the processes
 it spawned, stops them, and frees the port. Anything it did not start is named and left alone.
 
-`pnpm db:migrate` builds first, then runs Better Auth's migrations and then the application's. Before
-migrating, Better Auth logs `Database schema mismatch` because its tables do not exist yet; the migration
-still completes.
+Authentication is the API's own: `/api/auth/sign-up`, `sign-in`, `refresh`, `sign-out` and `session`. The web
+receives httpOnly cookies; a native client sends `X-Auth-Transport: bearer` and receives the tokens in the body.
 
 ## Everyday commands
 
@@ -42,7 +41,7 @@ still completes.
 | `pnpm lint` | Biome |
 | `pnpm typecheck` | `tsc --noEmit`, also run before every push |
 | `pnpm db:setup` | Creates a development database in Docker, writes its URL into `.env`, and migrates |
-| `pnpm db:migrate` | Builds, then runs Better Auth's migrations and the application's |
+| `pnpm db:migrate` | Runs the migrations |
 | `pnpm db:migration:create` | Generates a migration from the entity diff, to be read and edited before committing |
 
 ## Conventions

package/templates/api/docker-compose.yml

@@ -12,7 +12,6 @@ services:
       - '${POSTGRES_PORT:-5432}:5432'
     volumes:
       - postgres:/var/lib/postgresql
-      - ./docker/init:/docker-entrypoint-initdb.d:ro
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U app']
       interval: 5s

package/templates/api/migrations/Migration20261002210629_create_user_profile_session.ts

@@ -0,0 +1,31 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20261002210629_create_user_profile_session extends Migration {
+
+  override name = 'Migration20261002210629_create_user_profile_session';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "user" ("id" uuid not null default uuidv7(), "email" text not null, "password_hash" text not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`alter table "user" add constraint "user_email_unique" unique ("email");`);
+
+    this.addSql(`create table "session" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "token_hash" text not null, "client_id" text null, "resource" text null, "previous_token_hash" text null, "rotated_at" timestamptz null, "expires_at" timestamptz not null, "revoked_at" timestamptz null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create index "session_user_id_index" on "session" ("user_id");`);
+
+    this.addSql(`create table "profile" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "display_name" text not null, "locale" text not null default 'en', "timezone" text not null default 'UTC', "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`alter table "profile" add constraint "profile_user_id_unique" unique ("user_id");`);
+
+    this.addSql(`alter table "session" add constraint "session_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete cascade;`);
+
+    this.addSql(`alter table "profile" add constraint "profile_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete restrict;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "session" drop constraint "session_user_id_foreign";`);
+    this.addSql(`alter table "profile" drop constraint "profile_user_id_foreign";`);
+
+    this.addSql(`drop table if exists "user" cascade;`);
+    this.addSql(`drop table if exists "session" cascade;`);
+    this.addSql(`drop table if exists "profile" cascade;`);
+  }
+
+}

package/templates/api/migrations/Migration20261002210631_create_authorization.ts

@@ -0,0 +1,18 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20261002210631_create_authorization extends Migration {
+
+  override name = 'Migration20261002210631_create_authorization';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "authorization" ("id" uuid not null default uuidv7(), "client_id" text not null, "client_name" text not null, "redirect_uri" text not null, "code_challenge" text not null, "client_state" text null, "resource" text not null, "status" text not null, "user_id" uuid null, "code_hash" text null, "session_id" uuid null, "expires_at" timestamptz not null, "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`create index "authorization_user_id_index" on "authorization" ("user_id");`);
+
+    this.addSql(`alter table "authorization" add constraint "authorization_user_id_foreign" foreign key ("user_id") references "user" ("id") on delete cascade;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "authorization" cascade;`);
+  }
+
+}

package/templates/api/package.json

@@ -13,26 +13,24 @@
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
     "db:setup": "node scripts/database.mjs",
-    "db:migrate": "pnpm build && auth migrate --config dist/infra/auth/auth.cli.js --yes && mikro-orm migration:up",
+    "db:migrate": "mikro-orm migration:up",
     "db:migration:create": "mikro-orm migration:create",
     "prepare": "node .githooks/install.mjs"
   },
   "dependencies": {
-    "@better-auth/cimd": "1.7.7",
-    "@better-auth/core": "1.7.7",
-    "@better-auth/expo": "1.7.7",
-    "@better-auth/mcp": "1.7.7",
+    "@fastify/cookie": "11.1.2",
     "@fastify/cors": "11.3.0",
+    "@fastify/rate-limit": "11.2.0",
     "@fastify/swagger": "9.9.0",
     "@fastify/swagger-ui": "6.1.1",
     "@mikro-orm/core": "7.2.0",
     "@mikro-orm/migrations": "7.2.0",
     "@mikro-orm/postgresql": "7.2.0",
     "@modelcontextprotocol/server": "2.2.0",
-    "better-auth": "1.7.7",
+    "@node-rs/argon2": "2.2.1",
     "fastify": "5.12.5",
     "fastify-type-provider-zod": "7.0.0",
-    "pg": "8.23.0",
+    "jose": "6.2.12",
     "reflect-metadata": "0.2.2",
     "tsyringe": "4.10.0",
     "zod": "4.6.4"
@@ -48,7 +46,7 @@
     "@types/node": "24.13.4",
     "@types/pg": "8.23.1",
     "@vitest/coverage-v8": "4.1.11",
-    "auth": "1.7.7",
+    "pg": "8.23.0",
     "pino-pretty": "13.1.3",
     "typescript": "6.0.3",
     "unplugin-swc": "1.6.0",

package/templates/api/scripts/database.mjs

@@ -6,7 +6,7 @@
 // The server is always the one in docker-compose.yml, published on 5432 or, when that port is taken, the next free
 // one, kept in POSTGRES_PORT. It needs no dependency, so it runs before `pnpm install` has installed anything.
 import { spawnSync } from 'node:child_process'
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { connect } from 'node:net'
 import { basename, dirname, join, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
@@ -259,17 +259,9 @@ async function main() {
     say(`Created database ${name}.`)
   }
 
-  // The image runs docker/init only for the database it creates on first start; every other one needs them too.
-  const init = join(api, 'docker', 'init')
-  for (const file of readdirSync(init)
-    .filter((entry) => entry.endsWith('.sql'))
-    .sort()) {
-    sql(name, readFileSync(join(init, file), 'utf8'))
-  }
-
   const url = `postgresql://${USER}:${PASSWORD}@localhost:${port}/${name}`
-  writeEnv({ DATABASE_URL: url, AUTH_DATABASE_URL: url })
-  say('Wrote DATABASE_URL and AUTH_DATABASE_URL to .env.')
+  writeEnv({ DATABASE_URL: url })
+  say('Wrote DATABASE_URL to .env.')
 
   let migrated = false
 

package/templates/api/scripts/ports.mjs

@@ -25,7 +25,7 @@ const APPS = {
 // A port that moves takes these with it: the key to write, in which app, from which app's port.
 const FOLLOWERS = {
   api: [
-    { app: 'api', key: 'BETTER_AUTH_URL' },
+    { app: 'api', key: 'API_URL' },
     { app: 'web', key: 'VITE_API_URL' },
     { app: 'mobile', key: 'EXPO_PUBLIC_API_URL' },
   ],

package/templates/api/src/domain/auth/dto/refresh.dto.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+// The web sends its refresh token as a cookie and no body, which Fastify hands over as null; a native client
+// sends it here.
+export const refreshSchema = z
+  .strictObject({ refreshToken: z.string().min(1).optional() })
+  .nullish()
+
+export type RefreshDto = z.infer<typeof refreshSchema>

package/templates/api/src/domain/auth/dto/session-response.dto.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+export const sessionResponseSchema = z.object({
+  user: z.object({ id: z.uuid(), email: z.string() }),
+})
+
+export type SessionResponseDto = z.infer<typeof sessionResponseSchema>

package/templates/api/src/domain/auth/dto/sign-in.dto.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const signInSchema = z.strictObject({
+  email: z.email().max(254),
+  password: z.string().min(1).max(128),
+})
+
+export type SignInDto = z.infer<typeof signInSchema>

package/templates/api/src/domain/auth/dto/sign-up.dto.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+export const signUpSchema = z.strictObject({
+  name: z.string().trim().min(1).max(80),
+  email: z.email().max(254),
+  password: z.string().min(8).max(128),
+})
+
+export type SignUpDto = z.infer<typeof signUpSchema>

package/templates/api/src/domain/auth/dto/tokens-response.dto.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+// What a native client receives instead of cookies. `expiresIn` is in seconds, as OAuth writes it.
+export const tokensResponseSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresIn: z.number().int(),
+})
+
+export type TokensResponseDto = z.infer<typeof tokensResponseSchema>

package/templates/api/src/domain/auth/entities/session.entity.ts

@@ -0,0 +1,76 @@
+// A refresh token is long-lived, so it rotates on every use and is kept only as a hash.
+export const SESSION_LIFETIME_MS = 30 * 24 * 60 * 60 * 1000
+
+// Two tabs refreshing at once both present the same token. The second, arriving within this window, is told to
+// retry instead of being treated as a stolen token.
+export const ROTATION_GRACE_MS = 10 * 1000
+
+export type RefreshOutcome = 'valid' | 'superseded' | 'reused' | 'expired'
+
+// A session the user started in this application has neither. One an OAuth client obtained names the client and
+// the resource its access tokens are for.
+export type Grant = { clientId: string; resource: string }
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export class Session {
+  id: string
+  userId: string
+  tokenHash: string
+  clientId: string | null = null
+  resource: string | null = null
+  previousTokenHash: string | null = null
+  rotatedAt: Date | null = null
+  expiresAt: Date
+  revokedAt: Date | null = null
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(userId: string, tokenHash: string, now: Date, grant?: Grant) {
+    this.userId = userId
+    this.tokenHash = tokenHash
+    this.clientId = grant?.clientId ?? null
+    this.resource = grant?.resource ?? null
+    this.expiresAt = new Date(now.getTime() + SESSION_LIFETIME_MS)
+  }
+
+  // The refresh token names its session, so a token from any earlier rotation is recognised as reuse.
+  static parseRefreshToken(token: string): { sessionId: string; secret: string } | null {
+    const dot = token.indexOf('.')
+    const sessionId = token.slice(0, dot)
+    const secret = token.slice(dot + 1)
+
+    return dot === -1 || !UUID.test(sessionId) || secret === '' ? null : { sessionId, secret }
+  }
+
+  refreshToken(secret: string): string {
+    return `${this.id}.${secret}`
+  }
+
+  // A token that is neither the current one nor the one just replaced was replaced long ago: someone kept a copy.
+  check(tokenHash: string, now: Date): RefreshOutcome {
+    if (this.revokedAt !== null || this.expiresAt <= now) {
+      return 'expired'
+    }
+
+    if (tokenHash === this.tokenHash) {
+      return 'valid'
+    }
+
+    const justRotated =
+      this.rotatedAt !== null && now.getTime() - this.rotatedAt.getTime() < ROTATION_GRACE_MS
+
+    return tokenHash === this.previousTokenHash && justRotated ? 'superseded' : 'reused'
+  }
+
+  rotate(tokenHash: string, now: Date): void {
+    this.previousTokenHash = this.tokenHash
+    this.tokenHash = tokenHash
+    this.rotatedAt = now
+    this.expiresAt = new Date(now.getTime() + SESSION_LIFETIME_MS)
+  }
+
+  revoke(now: Date): void {
+    this.revokedAt ??= now
+  }
+}

package/templates/api/src/domain/auth/entities/user.entity.ts

@@ -0,0 +1,17 @@
+export class User {
+  id: string
+  email: string
+  passwordHash: string
+  createdAt: Date
+  updatedAt: Date
+
+  constructor(email: string, passwordHash: string) {
+    this.email = User.normalizeEmail(email)
+    this.passwordHash = passwordHash
+  }
+
+  // One address, one account: `Ana@Example.com ` and `ana@example.com` are the same person.
+  static normalizeEmail(email: string): string {
+    return email.trim().toLowerCase()
+  }
+}

package/templates/api/src/domain/auth/errors/email-taken.error.ts

@@ -0,0 +1,9 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class EmailTakenError extends DomainError {
+  readonly kind = 'conflict'
+
+  constructor() {
+    super('An account with this email already exists')
+  }
+}

package/templates/api/src/domain/auth/errors/invalid-credentials.error.ts

@@ -0,0 +1,10 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// One message for an unknown email and a wrong password, so the answer does not say which accounts exist.
+export class InvalidCredentialsError extends DomainError {
+  readonly kind = 'unauthorized'
+
+  constructor() {
+    super('Invalid email or password')
+  }
+}

package/templates/api/src/domain/auth/errors/invalid-session.error.ts

@@ -0,0 +1,9 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+export class InvalidSessionError extends DomainError {
+  readonly kind = 'unauthorized'
+
+  constructor(message = 'Session expired or revoked') {
+    super(message)
+  }
+}

package/templates/api/src/domain/auth/errors/superseded-token.error.ts

@@ -0,0 +1,11 @@
+import { DomainError } from '@/domain/shared/errors/domain-error'
+
+// Another request rotated this token a moment ago. The client already holds the new one, so it retries instead of
+// signing out.
+export class SupersededTokenError extends DomainError {
+  readonly kind = 'conflict'
+
+  constructor() {
+    super('Refresh token was just rotated; retry with the current one')
+  }
+}

package/templates/api/src/domain/auth/ports/access-tokens.port.ts

@@ -0,0 +1,15 @@
+export type AccessClaims = { userId: string; sessionId: string; clientId?: string }
+
+export type IssuedToken = { token: string; expiresAt: Date }
+
+// Short-lived and checked by signature alone: nothing is looked up to accept one, so nothing can revoke one.
+export const ACCESS_TOKEN_LIFETIME_MS = 15 * 60 * 1000
+
+// Without an audience a token is for this API's own routes; with one, for that resource alone. Neither is accepted
+// where the other is expected.
+export interface AccessTokens {
+  issue(claims: AccessClaims, expiresAt: Date, audience?: string): Promise<IssuedToken>
+  verify(token: string, audience?: string): Promise<AccessClaims | null>
+}
+
+export const ACCESS_TOKENS = Symbol('AccessTokens')

package/templates/api/src/domain/auth/ports/opaque-tokens.port.ts

@@ -0,0 +1,7 @@
+// Random values that are handed out once and stored only as a digest.
+export interface OpaqueTokens {
+  create(): string
+  digest(token: string): string
+}
+
+export const OPAQUE_TOKENS = Symbol('OpaqueTokens')

package/templates/api/src/domain/auth/ports/password-hasher.port.ts

@@ -0,0 +1,8 @@
+export interface PasswordHasher {
+  hash(password: string): Promise<string>
+  // Without a hash it still spends the time of a real check and answers false, so an unknown email and a wrong
+  // password take as long as each other.
+  verify(hash: string | undefined, password: string): Promise<boolean>
+}
+
+export const PASSWORD_HASHER = Symbol('PasswordHasher')

package/templates/api/src/domain/auth/repositories/session.repository.ts

@@ -0,0 +1,10 @@
+import type { Session } from '@/domain/auth/entities/session.entity'
+
+export interface SessionRepository {
+  findById(id: string): Promise<Session | null>
+  // Reads the row and holds it until the surrounding transaction ends, so two rotations cannot interleave.
+  lockById(id: string): Promise<Session | null>
+  save(session: Session): Promise<void>
+}
+
+export const SESSION_REPOSITORY = Symbol('SessionRepository')