sentri 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,9 @@
 # sentri
 
-Auth and authorization library for Express + PostgreSQL. Provides stateless JWT authentication, automatic token refresh, cookie-based token storage, request idempotency, role-based access control, fine-grained permission checks, and a pre-built Express router — all behind a single typed client.
+Auth and authorization library for Express. Supports two modes:
+
+- **Server mode** — runs as a standalone auth server with its own database schema (Kysely), issues JWTs, and exposes auth endpoints including a public key endpoint for SSO.
+- **Client mode** — used by other apps to validate tokens issued by the auth server, without a database.
 
 ---
 
@@ -8,22 +11,15 @@ Auth and authorization library for Express + PostgreSQL. Provides stateless JWT
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [CLI](#cli)
+- [Server Mode](#server-mode)
+- [Client Mode](#client-mode)
+- [SSO Flow](#sso-flow)
 - [Configuration](#configuration)
-- [Token Storage](#token-storage)
-- [Stateless Access Tokens](#stateless-access-tokens)
-- [Automatic Token Refresh](#automatic-token-refresh)
-- [Request Idempotency](#request-idempotency)
-- [Lifecycle Hooks](#lifecycle-hooks)
-- [Immediate Token Revocation](#immediate-token-revocation-istokenrevoked)
-- [apiKey — Restricting Registration](#apikey--restricting-registration)
-- [Custom Route Handlers](#custom-route-handlers)
-- [Adapter Interface](#adapter-interface)
-- [Pre-built Router](#pre-built-router)
+- [Endpoints](#endpoints)
 - [Middleware](#middleware)
-- [Programmatic API](#programmatic-api)
-- [Types](#types)
+- [Token Utilities](#token-utilities)
 - [Error Handling](#error-handling)
+- [Request Idempotency](#request-idempotency)
 - [Migration Guide](#migration-guide)
 
 ---
@@ -34,522 +30,267 @@ Auth and authorization library for Express + PostgreSQL. Provides stateless JWT
 npm install sentri
 ```
 
-**Peer dependency:** `express >= 4.0.0`
-
----
-
-## Quick Start
+`kysely` and `pg` are bundled with sentri — no separate installation needed for PostgreSQL.
 
-### 1. Generate templates
+For other databases, install the driver:
 
 ```bash
-# Prisma
-npx sentri generate prisma
+# MySQL
+npm install mysql2
 
-# Drizzle
-npx sentri generate drizzle
+# SQLite
+npm install better-sqlite3
 ```
 
-This creates:
+**Peer dependency:** `express >= 4.0.0`
 
-```
-src/lib/
-  index.ts               ← barrel export
-  sentri/
-    adapter.ts           ← AuthAdapter implementation
-    auth.ts              ← configured auth client
-    schema.ts            ← table definitions (Drizzle only)
-prisma/
-  schema.prisma          ← Prisma models (Prisma only, created or appended)
-```
+---
+
+## Quick Start
 
-### 2. Mount the router and error handler
+### Server Mode — PostgreSQL (recommended)
 
 ```typescript
 import express from 'express';
-import { auth } from './lib/sentri/auth.js';
-import { createIdempotencyMiddleware } from 'sentri';
+import { createAuthServer } from 'sentri';
+
+const auth = createAuthServer({
+  validRoles: ['user', 'admin'] as const,
+  db: { connectionString: process.env.DATABASE_URL! },
+});
 
 const app = express();
 app.use(express.json());
+app.use(auth.idempotencyMiddleware());
 
-// Optional: make POST/PUT/PATCH operations idempotent
-app.use(createIdempotencyMiddleware());
-
+await auth.migrate();
 app.use('/auth', auth.router());
 
-// ... your routes ...
-
-// Must be last — catches SentriError from sentri and your own subclasses
+app.get('/me', auth.protect(), (req, res) => res.json(req.user));
 app.use(auth.errorHandler());
 app.listen(3000);
 ```
 
-Done. All endpoints are available at `/auth/*`.
-
----
-
-## CLI
-
-### `sentri generate <prisma|drizzle>`
-
-Generates adapter, auth config, and schema templates in one command.
-
-```bash
-npx sentri generate prisma
-npx sentri generate drizzle
-```
+`createAuthServer()` generates an RSA-2048 key pair at startup and enables `GET /keys` automatically.
 
-**What gets created:**
-
-| File | Behavior |
-|---|---|
-| `src/lib/sentri/adapter.ts` | Created fresh (error if exists) |
-| `src/lib/sentri/auth.ts` | Created fresh (error if exists) |
-| `src/lib/sentri/schema.ts` | Drizzle only — created fresh or tables appended |
-| `prisma/schema.prisma` | Prisma only — created fresh or models appended |
-| `src/lib/index.ts` | Created fresh, skipped if already exists |
-
----
-
-## Configuration
+### Server Mode — Custom Dialect
 
 ```typescript
+import express from 'express';
 import { createAuth } from 'sentri';
-
-export const auth = createAuth({
-  secret: process.env.JWT_SECRET!,        // required — keep in env, min 32 chars
-  validRoles: ['user', 'admin'] as const, // required — use `as const` for type safety
-  adapter: myAdapter,                     // required — see Adapter Interface
-
-  // optional
-  accessExpiresIn: '5m',    // default: '15m' — short is safe: auto-refresh handles it
-  refreshExpiresIn: '7d',   // default: '7d'
-  algorithm: 'HS256',       // default: 'HS256' — also 'HS384' | 'HS512'
-  saltRounds: 12,           // default: 12 (bcrypt rounds, min 10)
-
-  // API key for POST /register — see apiKey section
-  apiKey: process.env.REGISTER_API_KEY,  // optional
-
-  // Access token cookie — non-httpOnly so browser JS can read it.
-  // When set, protect() reads from this cookie when no Authorization header is present.
-  accessCookie: {
-    secure: process.env.NODE_ENV === 'production',
-    // name: 'access_token',  // default: 'access_token'
-    // sameSite: 'strict',    // default: 'strict'
-    // path: '/',             // default: '/'
-  },
-
-  // Refresh token cookie — httpOnly (not readable by JS).
-  cookie: {
-    secure: process.env.NODE_ENV === 'production',
-    // name: 'refresh_token', // default: 'refresh_token'
-    // httpOnly: true,        // default: true
-    // sameSite: 'strict',    // default: 'strict'
-    // path: '/',             // default: '/'
-  },
-
-  // Lifecycle hooks — fire-and-forget, rejections are swallowed.
-  // hooks: {
-  //   onLogin: async (user) => auditLog.record('login', user.id),
-  //   onFailedLogin: (identifier) => rateLimiter.hit(`login:${identifier}`),
-  //   onLogout: async (userId) => cache.invalidate(userId),
-  // },
-
-  // Optional immediate revocation — called on every protect() invocation.
-  // isTokenRevoked: async (sessionId) =>
-  //   await redis.sismember('revoked_sessions', sessionId),
-
-  // router: {             // optional — replace built-in service logic per route
-  //   login: async (input) => { ... },
-  //   register: async (input) => { ... },
-  //   refresh: async (refreshToken) => { ... },
-  //   logout: async (refreshToken) => { ... },
-  //   logoutAll: async (userId) => { ... },
-  //   assignRoles: async (userId, roles) => { ... },
-  // },
-});
-```
-
-`accessExpiresIn` and `refreshExpiresIn` accept duration strings (`'5m'`, `'1h'`, `'7d'`, `'30d'`) or seconds as a number.
-
----
-
-## Token Storage
-
-sentri uses a two-cookie strategy for SPAs:
-
-| Cookie | `httpOnly` | Readable by JS | Purpose |
-|---|---|---|---|
-| `access_token` | **false** | ✅ Yes | Carries the JWT for authenticated requests |
-| `refresh_token` | **true** | ❌ No | Used to silently rotate the access token |
-
-### Setting up cookie storage
-
-Enable both cookies in your config:
-
-```typescript
-export const auth = createAuth({
-  accessExpiresIn: '5m',
-  accessCookie: { secure: process.env.NODE_ENV === 'production' },
-  cookie:        { secure: process.env.NODE_ENV === 'production' },
-  // ...
+import { PostgresDialect } from 'kysely';  // kysely is bundled, no install needed
+import { Pool } from 'pg';                 // pg is bundled, no install needed
+
+const auth = createAuth({
+  mode: 'server',
+  dialect: new PostgresDialect({ pool: new Pool({ connectionString: process.env.DATABASE_URL }) }),
+  secret: process.env.JWT_PRIVATE_KEY!,   // RSA private key PEM (RS256) or plain string (HS256)
+  algorithm: 'RS256',
+  validRoles: ['user', 'admin'] as const,
 });
-```
 
-After `/login`, the router sets both cookies automatically. `protect()` reads the access token from the cookie when no `Authorization: Bearer` header is present, so your SPA needs zero manual header management.
-
-### Reading the access token in the browser
-
-```javascript
-// Read from document.cookie
-const token = document.cookie
-  .split('; ')
-  .find(c => c.startsWith('access_token='))
-  ?.split('=')[1];
+const app = express();
+app.use(express.json());
+await auth.migrate();
+app.use('/auth', auth.router());
+app.use(auth.errorHandler());
+app.listen(3000);
 ```
 
-### Reading the token server-side
+### Client Mode (Other Apps)
 
 ```typescript
-import { getCurrentAccessToken } from 'sentri';
+import express from 'express';
+import { createAuth } from 'sentri';
 
-app.get('/debug', (req, res) => {
-  // Checks Authorization header first, then access_token cookie
-  const token = getCurrentAccessToken(req, config);
-  res.json({ hasToken: !!token });
+const auth = createAuth({
+  mode: 'client',
+  keyUri: 'https://auth.myapp.com/auth/keys',
 });
 
-// Or via the auth client (pre-bound to config):
-const token = auth.getCurrentAccessToken(req);
-```
-
----
-
-## Stateless Access Tokens
-
-Access tokens are validated **stateless** — by JWT signature and `exp` claim only. No database lookup occurs on every protected request, which keeps `protect()` fast regardless of load.
-
-```
-Request → protect() verifies JWT signature + expiry → ✓ allowed
-(no DB round-trip per request)
-```
-
-**Trade-off:** After logout, an access token remains technically valid until it expires (`accessExpiresIn`). Keep this window short (`'5m'`) to limit exposure. Refresh tokens are still session-bound, so a revoked refresh token cannot obtain new access tokens.
+const app = express();
+app.get('/products', auth.protect(), auth.authorize('admin'), handler);
+app.get('/orders', auth.protect(), auth.permit(req => req.user!.id === req.params.userId), handler);
 
-```
-Logout  → session deleted from DB
-Request with old access token → accepted until exp (≤ 5m)
-Request with old refresh token → rejected immediately (session gone)
+app.use(auth.errorHandler());
 ```
 
 ---
 
-## Automatic Token Refresh
-
-When `protect()` encounters an expired access token, it performs one silent refresh before returning an error:
-
-1. Reads the refresh token from the httpOnly cookie.
-2. Rotates the session (deletes old, creates new).
-3. Issues new access + refresh tokens.
-4. Updates both cookies on the response.
-5. Writes the new access token to the `X-New-Access-Token` response header.
-6. Calls `next()` — the handler runs normally without any knowledge of the refresh.
-
-If the refresh also fails (session expired or revoked), the middleware calls `next(SentriError)` with `UNAUTHORIZED` and the user must log in again.
-
-```
-Request with expired access token
-  → protect() tries refresh cookie
-  → refresh succeeds → new tokens set → request continues transparently
-  → refresh fails   → 401 UNAUTHORIZED — user must login
-```
-
-**Client-side:** Check the `X-New-Access-Token` header on every response to detect a silent refresh and update any in-memory token copy:
-
-```javascript
-const newToken = response.headers.get('X-New-Access-Token');
-if (newToken) currentAccessToken = newToken;
-```
-
-When `accessCookie` is configured the cookie is updated automatically, so in-memory management is optional.
-
----
+## Server Mode
 
-## Request Idempotency
+Server mode manages users, sessions, and tokens entirely within Sentri. The user provides a database dialect; Sentri handles the schema.
 
-`createIdempotencyMiddleware()` makes `POST`, `PUT`, and `PATCH` operations idempotent. When a client sends the same `X-Idempotency-Key` header twice, the second request receives the cached response without re-executing the handler.
+### `createAuthServer(options)` — PostgreSQL shortcut
 
 ```typescript
-import { createIdempotencyMiddleware } from 'sentri';
+import { createAuthServer } from 'sentri';
 
-// Apply globally (before routes)
-app.use(createIdempotencyMiddleware());
-
-// Or scoped with custom options
-apiRouter.use(createIdempotencyMiddleware({
-  ttl: 60_000,             // cache TTL in ms — default: 300_000 (5 min)
-  header: 'X-Request-Id', // key header name — default: 'X-Idempotency-Key'
-  methods: ['POST'],       // methods to watch — default: ['POST','PUT','PATCH']
-}));
-```
-
-### How it works
+const auth = createAuthServer({
+  validRoles: ['user', 'admin'] as const,
 
-| Request | Key present | Cache hit | Behaviour |
-|---|---|---|---|
-| POST | No | — | Passes through unchanged |
-| POST | Yes | No | Handler runs; response is cached (2xx only) |
-| POST | Yes | Yes | Cached response returned immediately; `X-Idempotent-Replayed: true` header added |
+  // Connection string
+  db: { connectionString: process.env.DATABASE_URL!, max: 10 },
 
-The idempotency key is also attached as `req.requestId` and echoed in the `X-Request-Id` response header for all requests that include it.
+  // — or individual params —
+  // db: { host: 'localhost', port: 5432, database: 'mydb', user: 'app', password: 'secret' },
 
-```typescript
-app.post('/orders', createIdempotencyMiddleware(), async (req, res) => {
-  console.log(req.requestId); // the X-Idempotency-Key value
-  const order = await db.orders.create(req.body);
-  res.status(201).json({ error: false, data: order });
-  // On retry with same key → instant 201 from cache, no DB write
+  // Optional
+  accessExpiresIn: '15m',
+  refreshExpiresIn: '7d',
+  saltRounds: 12,
+  apiKey: process.env.REGISTER_API_KEY,
+  redisUrl: process.env.REDIS_URL,  // enables Redis-backed idempotency cache
 });
 ```
 
-**Note:** The cache is in-memory and per-process. For multi-process deployments (clusters, containers) use a shared cache layer such as Redis.
-
----
-
-## Lifecycle Hooks
-
-`hooks` lets you fire side effects at key points in the authentication flow. Every hook is optional and runs fire-and-forget — a rejected hook Promise is silently swallowed so a broken hook can never abort or delay a login request.
+### `createAuth(config)` — Full config
 
 ```typescript
-export const auth = createAuth({
-  // ...
-  hooks: {
-    /** Called after every successful login. */
-    onLogin: async (user) => {
-      await auditLog.record('login', { userId: user.id, identifier: user.identifier });
-    },
-
-    /** Called after every failed login attempt. */
-    onFailedLogin: (identifier, error) => {
-      rateLimiter.hit(`login:${identifier}`);
-      logger.warn('Login failed', { identifier, code: error.code });
-    },
-
-    /** Called after logout (single session) and logout-all. */
-    onLogout: async (userId) => {
-      await cache.invalidate(userId);
-    },
+createAuth({
+  mode: 'server',
+  dialect,                            // required — Kysely Dialect
+  secret: process.env.JWT_SECRET!,   // required — RSA private key PEM (RS256) or string (HS256)
+  validRoles: ['user', 'admin'] as const,  // required
+
+  algorithm: 'RS256',        // default: 'HS256' | also: 'HS384','HS512','RS384','RS512'
+  accessExpiresIn: '15m',    // default: '15m'
+  refreshExpiresIn: '7d',    // default: '7d'
+  saltRounds: 12,            // default: 12 (bcrypt rounds, 10–31)
+  apiKey: process.env.REGISTER_API_KEY,   // restricts POST /register
+  redisUrl: process.env.REDIS_URL,        // Redis URL for idempotency cache
+  cookie: { secure: true },              // httpOnly refresh token cookie
+  accessCookie: { secure: true },        // non-httpOnly access token cookie (SPA)
+  hooks: { onLogin, onFailedLogin, onLogout },
+  isTokenRevoked: async (sessionId) => await redis.sismember('revoked', sessionId),
+  router: {                              // override built-in service functions
+    login, register, refresh, logout, logoutAll, assignRoles,
+    changeIdentifier, changePassword,
   },
 });
 ```
 
-### `AuthHooks` interface
+### Database Migration
 
-| Hook | When | Receives |
-|---|---|---|
-| `onLogin` | After successful login | `AuthUser` |
-| `onFailedLogin` | After failed login (wrong password or unknown identifier) | `identifier: string`, `error: SentriError` |
-| `onLogout` | After `POST /logout-all` | `userId: string` |
+```typescript
+// Call once at startup — uses IF NOT EXISTS, safe to repeat
+await auth.migrate();
+```
 
-> `POST /logout` (single session) does not fire `onLogout` — there is no authenticated user at that point. Use `onLogout` for "logout from all devices" events.
+Creates two tables:
+- `sentri_users` — id, identifier, password_hash, roles (JSON), created_at
+- `sentri_sessions` — id, user_id, expires_at, created_at
 
 ---
 
-## Immediate Token Revocation (`isTokenRevoked`)
+## Client Mode
 
-By default, sentri uses stateless access tokens — no DB lookup per request. If you need to revoke a token immediately (e.g. after a security incident), supply `isTokenRevoked`:
+Client mode has no database. It fetches the auth server's public key and validates JWTs stateless.
 
 ```typescript
-export const auth = createAuth({
-  // ...
-  isTokenRevoked: async (sessionId) =>
-    await redis.sismember('revoked_sessions', sessionId),
+createAuth({
+  mode: 'client',
+  keyUri: 'https://auth.myapp.com/auth/keys',  // required
+  validRoles: ['admin', 'user'],               // optional — TypeScript type safety only
 });
 ```
 
-After logout, add the `sessionId` to the revocation set:
+Available methods: `protect()`, `authorize()`, `permit()`, `errorHandler()`.
 
-```typescript
-// When handling a security incident — add to revoked set with a TTL
-// equal to the access token lifetime so memory stays bounded.
-await redis.sadd('revoked_sessions', sessionId);
-await redis.expire('revoked_sessions', 300); // 5 min — matches accessExpiresIn
-```
-
-`isTokenRevoked` is called on **every** `protect()` invocation. Keep it fast (a single Redis `SISMEMBER`) or the latency benefit of stateless JWTs is lost. If a short revocation window equal to `accessExpiresIn` is acceptable, omit this hook entirely.
+The public key is fetched once and cached for 1 hour. Token validation is fully stateless.
 
 ---
 
-## apiKey — Restricting Registration
+## SSO Flow
 
-By default `POST /register` is open to the public. Set `apiKey` in your config to lock the endpoint:
+```
+[User]  →  POST /auth/login          (Sentri Auth Server)
+       ←   { accessToken, user }
 
-```typescript
-export const auth = createAuth({
-  // ...
-  apiKey: process.env.REGISTER_API_KEY!,
-});
+[User]  →  GET /products             (App A — client mode)
+           Authorization: Bearer <accessToken>
+       ←   App A fetches public key from GET /auth/keys, verifies JWT
+       ←   200 OK
 ```
 
-Requests to `POST /register` must then include the header:
+For SSO, use `algorithm: 'RS256'` on the server (or `createAuthServer()` which defaults to RS256). This automatically adds `GET /keys` to the auth router, which returns the public key in JWKS format (RFC 7517).
 
 ```
-X-Api-Key: <value of REGISTER_API_KEY>
+GET /auth/keys → { keys: [{ kty, use, kid, n, e, ... }] }
 ```
 
-Requests without the header, or with the wrong value, receive HTTP 401 `UNAUTHORIZED`. Keep the API key in an environment variable and share it only with trusted services.
+Client apps point `keyUri` at this endpoint and receive the public key automatically.
 
 ---
 
-## Custom Route Handlers
-
-The `router` field in config lets you replace the built-in service logic for individual routes while the router still handles request parsing, input validation, and response formatting.
-
-```typescript
-import { createAuth, SentriError } from 'sentri';
-import type { AuthResult } from 'sentri';
-
-export const auth = createAuth({
-  secret: process.env.JWT_SECRET!,
-  validRoles: ['user', 'admin'] as const,
-  adapter: myAdapter,
-
-  router: {
-    // Add an OTP check before issuing tokens
-    login: async (input): Promise<AuthResult> => {
-      const otpVerified = await redis.get(`otp:${input.identifier}`);
-      if (!otpVerified) {
-        return { success: false, error: new SentriError('INVALID_CREDENTIALS', 'OTP required') };
-      }
-      return defaultLogin(input);
-    },
-
-    // Send a welcome email after registration
-    register: async (input) => {
-      const result = await defaultRegister(input);
-      if (result.success) {
-        await emailService.sendWelcome(input.identifier);
-      }
-      return result;
-    },
-  },
-});
-```
+## Configuration
 
-### Available handler signatures
+### `algorithm`
 
-| Key | Signature | Must return |
+| Value | Type | Use case |
 |---|---|---|
-| `register` | `(input: RegisterInput) => Promise<RegisterResult>` | `RegisterResult` |
-| `login` | `(input: LoginInput) => Promise<AuthResult>` | `AuthResult` |
-| `refresh` | `(refreshToken: string) => Promise<RefreshResult>` | `RefreshResult` |
-| `logout` | `(refreshToken: string \| undefined) => Promise<void>` | `void` |
-| `logoutAll` | `(userId: string) => Promise<void>` | `void` |
-| `assignRoles` | `(userId: string, roles: string[]) => Promise<AssignRolesResult>` | `AssignRolesResult` |
+| `'HS256'` | Symmetric (default) | Single app, shared secret |
+| `'RS256'` | Asymmetric | SSO — enables `GET /keys` |
 
----
-
-## Adapter Interface
+When using RS256, `secret` must be a valid RSA private key in PEM format. `createAuthServer()` generates the key pair automatically.
 
-The adapter connects sentri to your database. Implement `AuthAdapter` for any ORM or data layer.
+### Cookie Strategy (SPA)
 
 ```typescript
-import type { AuthAdapter } from 'sentri';
-
-const adapter: AuthAdapter = {
-  user: {
-    findByIdentifier(identifier: string): Promise<UserRecord | null>,
-    findById(id: string): Promise<UserRecord | null>,
-    create(data: CreateUserData): Promise<{ id: string }>,
-    updateRoles(userId: string, roles: string[]): Promise<void>,
-  },
-  session: {
-    create(data: { userId: string; expiresAt: Date }): Promise<{ id: string }>,
-    findById(sessionId: string): Promise<(SessionRecord & { user: UserRecord }) | null>,
-    delete(sessionId: string): Promise<void>,
-    deleteAllForUser(userId: string): Promise<void>,
-  },
-};
+createAuth({
+  mode: 'server',
+  cookie: { secure: true },        // httpOnly refresh token
+  accessCookie: { secure: true },  // non-httpOnly access token (readable by JS)
+});
 ```
 
-`identifier` is a single string — the adapter decides what it maps to (email column, username column, phone, or a combined lookup). sentri never assumes the column name.
+After login, both cookies are set automatically. `protect()` reads the access token from the cookie when no `Authorization` header is present.
 
 ---
 
-## Pre-built Router
-
-`auth.router()` returns an Express Router with all standard endpoints. Every response uses this envelope:
-
-```typescript
-{ error: boolean, statusCode: number, message: string, data: T | null }
-```
-
-### Endpoints
+## Endpoints
 
-#### `POST /register`
+`auth.router()` mounts these endpoints:
 
-```
-Headers: X-Api-Key: <key>   (required when config.apiKey is set)
-Body:    { identifier, password, roles?: string[] }
-Returns: { user: { id, identifier, roles } }
-Status:  201
-```
-
-#### `POST /login`
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `POST` | `/register` | — | Create a user (requires `X-Api-Key` when `apiKey` is set) |
+| `POST` | `/login` | — | Authenticate, receive tokens |
+| `POST` | `/refresh` | — | Rotate refresh token |
+| `POST` | `/logout` | — | Invalidate current session |
+| `POST` | `/logout-all` | ✓ | Invalidate all sessions |
+| `GET` | `/me` | ✓ | Return authenticated user |
+| `PATCH` | `/me/identifier` | ✓ self | Change identifier (username/email) |
+| `PATCH` | `/me/password` | ✓ self | Change password — revokes all sessions |
+| `POST` | `/users/:userId/roles` | ✓ admin | Assign roles to user |
+| `GET` | `/keys` | — | Public key in JWKS format (RS256 only) |
 
-```
-Body:    { identifier, password }
-Returns: { accessToken, user: { id, identifier, roles } }
-Cookies: access_token=<jwt>   (when config.accessCookie is set)
-         refresh_token=<jwt>  (httpOnly)
-Status:  200
+All responses use the envelope:
+```json
+{ "error": false, "statusCode": 200, "message": "...", "data": { ... } }
 ```
 
-#### `POST /refresh`
+### Change Identifier
 
 ```
-Cookie:  refresh_token=<token>
-Returns: { accessToken }
-Cookies: access_token=<new-jwt>   (when config.accessCookie is set)
-         refresh_token=<new-jwt>  (rotated)
-Status:  200
-```
-
-#### `POST /logout`
+PATCH /me/identifier
+Authorization: Bearer <token>
+Content-Type: application/json
 
-```
-Cookie:  refresh_token=<token>
-Clears:  access_token, refresh_token cookies
-Returns: null
-Status:  200
+{ "identifier": "new@example.com" }
 ```
 
-#### `POST /logout-all`
+### Change Password
 
 ```
-Headers: Authorization: Bearer <accessToken>  (or access_token cookie)
-Clears:  access_token, refresh_token cookies
-Returns: null
-Status:  200
-```
+PATCH /me/password
+Authorization: Bearer <token>
+Content-Type: application/json
 
-#### `GET /me`
-
-```
-Headers: Authorization: Bearer <accessToken>  (or access_token cookie)
-Returns: { id, identifier, roles }
-Status:  200
+{ "currentPassword": "old-pass", "newPassword": "new-pass" }
 ```
 
-#### `POST /users/:userId/roles`
-
-```
-Headers: Authorization: Bearer <accessToken>  (must have admin role)
-Body:    { roles: string[] }
-Returns: { user: { id, identifier, roles } }
-Status:  200
-```
+Changing the password revokes all existing sessions. The user must log in again after this call.
 
 ---
 
@@ -557,53 +298,39 @@ Status:  200
 
 ### `auth.protect()`
 
-Verifies the access token and injects `request.user`. Token is read from:
-
-1. `Authorization: Bearer <token>` header
-2. `access_token` cookie (when `config.accessCookie` is set)
-
-When the token has expired, a silent refresh is attempted automatically. On success the request proceeds normally; on failure HTTP 401 is returned.
+Verifies the JWT and sets `req.user`. In server mode, also performs silent token refresh when the access token expires.
 
 ```typescript
-router.get('/dashboard', auth.protect(), (request, response) => {
-  response.json(request.user); // { id, identifier, roles }
-});
+app.get('/dashboard', auth.protect(), (req, res) => res.json(req.user));
 ```
 
-Returns HTTP 401 if:
-- No token is present in header or cookie
-- The token signature is invalid
-- The token is expired **and** the refresh also fails
-
----
+Token is read from `Authorization: Bearer <token>` header or `access_token` cookie.
 
 ### `auth.authorize(...roles)`
 
-Enforces role-based access. Must be used **after** `auth.protect()`.
+Role-based access — must follow `protect()`.
 
 ```typescript
-router.delete('/posts/:id', auth.protect(), auth.authorize('admin'), handler);
+app.delete('/posts/:id', auth.protect(), auth.authorize('admin'), handler);
 ```
 
----
-
 ### `auth.permit(check | options)`
 
-Resource-level permission check. Must be used **after** `auth.protect()`. Return `true` to allow, `false` to deny.
+Resource-level permission — must follow `protect()`.
 
 ```typescript
 // Ownership check
-router.put('/users/:id', auth.protect(),
-  auth.permit((req) => req.user!.id === req.params['id']),
+app.put('/users/:id', auth.protect(),
+  auth.permit((req) => req.user!.id === req.params.id),
   handler,
 );
 
-// Role bypass + custom check
-router.delete('/posts/:id', auth.protect(),
+// Role bypass + ownership check
+app.delete('/posts/:id', auth.protect(),
   auth.permit({
     roles: ['admin'],
     check: async (req) => {
-      const post = await db.post.findById(req.params['id']);
+      const post = await db.posts.findById(req.params.id);
       return post?.authorId === req.user!.id;
     },
   }),
@@ -613,140 +340,66 @@ router.delete('/posts/:id', auth.protect(),
 
 ---
 
-### `createIdempotencyMiddleware(options?)`
+## Token Utilities
 
-Makes mutating operations idempotent via `X-Idempotency-Key` header. See [Request Idempotency](#request-idempotency).
-
----
-
-## Programmatic API
-
-### Token utilities
+Available on `ServerAuthClient` only:
 
 ```typescript
-const accessToken = auth.signAccessToken({ id, identifier, roles });
-const user = auth.verifyAccessToken(accessToken);         // throws SentriError if invalid
-const { sessionId } = auth.verifyRefreshToken(token);    // throws SentriError if invalid
+const auth = createAuth({ mode: 'server', ... });
+
+// Sign
+const accessToken  = auth.signAccessToken({ id, identifier, roles });
 const refreshToken = auth.signRefreshToken(sessionId);
-```
 
-### Password utilities
+// Verify
+const user          = auth.verifyAccessToken(accessToken);
+const { sessionId } = auth.verifyRefreshToken(refreshToken);
 
-```typescript
-const hash = await auth.hashPassword('secret123');
+// Password
+const hash  = await auth.hashPassword('secret123');
 const valid = await auth.verifyPassword('secret123', hash);
-```
-
-### Token extraction
-
-```typescript
-// Read the raw access token from Authorization header or access_token cookie
-const token = auth.getCurrentAccessToken(request);
-
-// Or import and use directly with a config object
-import { getCurrentAccessToken } from 'sentri';
-const token = getCurrentAccessToken(request, config);
-```
 
-### Standalone `register`
-
-```typescript
-import { register } from 'sentri';
-
-const result = await register(
-  { identifier: 'alice@example.com', password: 'hunter2', roles: ['user'] },
-  config,
-);
-
-if (result.success) {
-  console.log(result.user.id);
-} else {
-  console.error(result.error.code); // 'USER_ALREADY_EXISTS' | 'INVALID_ROLE'
-}
+// Extract raw token from request
+const token = auth.getCurrentAccessToken(req);
 ```
 
 ---
 
-## Types
+## Error Handling
 
 ```typescript
-import type {
-  AuthConfig,
-  AuthClient,
-  AuthAdapter,
-  AuthHooks,
-  AuthUser,
-  AuthResult,
-  RegisterResult,
-  AssignRolesResult,
-  RefreshResult,
-  ApiResponse,
-  RegisterInput,
-  LoginInput,
-  RouterHandlers,
-  UserRecord,
-  SessionRecord,
-  CreateUserData,
-  CookieConfig,
-  AccessCookieConfig,
-  IdempotencyOptions,
-  PermitCheck,
-  PermitOptions,
-  SentriErrorCode,
-} from 'sentri';
-
-import {
-  SentriError,
-  AUTH_ERROR_STATUS,
-  createAuth,
-  register,
-  createIdempotencyMiddleware,
-  getCurrentAccessToken,
-} from 'sentri';
+app.use('/auth', auth.router());
+app.use('/api', apiRouter);
+app.use(auth.errorHandler());  // must be last
 ```
 
----
-
-## Error Handling
-
-All errors thrown by the library are instances of `SentriError` with a machine-readable `code` and an HTTP `statusCode`:
-
 | Code | HTTP | Meaning |
 |---|---|---|
 | `INVALID_CREDENTIALS` | 401 | Wrong identifier or password |
-| `USER_ALREADY_EXISTS` | 409 | Registration with duplicate identifier |
-| `USER_NOT_FOUND` | 404 | Operation on a non-existent user |
-| `TOKEN_EXPIRED` | 401 | JWT `exp` claim is in the past |
-| `TOKEN_INVALID` | 401 | JWT signature invalid or malformed |
-| `UNAUTHORIZED` | 401 | No valid access token, or session not found |
+| `USER_ALREADY_EXISTS` | 409 | Duplicate identifier at registration |
+| `USER_NOT_FOUND` | 404 | User does not exist |
+| `TOKEN_EXPIRED` | 401 | JWT `exp` is in the past |
+| `TOKEN_INVALID` | 401 | Bad signature or malformed JWT |
+| `UNAUTHORIZED` | 401 | No valid token or session not found |
 | `FORBIDDEN` | 403 | Authenticated but missing required role |
-| `INVALID_ROLE` | 400 | Role name not in `validRoles` |
-| `VALIDATION_ERROR` | 400 | Missing or invalid input field |
-| `CONFIGURATION_ERROR` | 500 | Invalid `createAuth` configuration |
-
-### `auth.errorHandler()`
-
-Mount **after all your routes**:
-
-```typescript
-app.use('/auth', auth.router());
-app.use('/api', apiRouter);
-app.use(auth.errorHandler());
-```
+| `INVALID_ROLE` | 400 | Role not in `validRoles` |
+| `VALIDATION_ERROR` | 400 | Missing or invalid input |
+| `CONFIGURATION_ERROR` | 500 | Invalid `createAuth` config |
 
 ### Extending `SentriError`
 
 ```typescript
 import { SentriError } from 'sentri';
 
-export class NotFoundError extends SentriError {
+class NotFoundError extends SentriError {
   constructor(resource: string) {
     super('NOT_FOUND', `${resource} not found`, 404);
   }
 }
 
+// Caught automatically by auth.errorHandler()
 app.get('/items/:id', auth.protect(), async (req, res) => {
-  const item = await db.items.findById(req.params['id']);
+  const item = await db.items.findById(req.params.id);
   if (!item) throw new NotFoundError('Item');
   res.json(item);
 });
@@ -754,39 +407,62 @@ app.get('/items/:id', auth.protect(), async (req, res) => {
 
 ---
 
-## Migration Guide
+## Request Idempotency
 
-### Breaking changes in 2.0.0
+Repeat requests with the same `X-Idempotency-Key` header receive the cached response immediately (2xx only). Useful for POST/PUT/PATCH endpoints where clients may retry on network failure.
 
-| What changed | Action required |
-|---|---|
-| `protect()` no longer performs a DB session check per request | Access tokens are now stateless. Logout does **not** immediately invalidate a live access token — it expires after `accessExpiresIn`. Keep this value short (`'5m'`). |
-| `protect()` reads token from `access_token` cookie when `accessCookie` is configured | No action required if you use the `Authorization` header. Add `accessCookie` to config to enable cookie-based token delivery. |
-| `protect()` silently refreshes expired tokens | Clients should read the `X-New-Access-Token` response header to detect and store the new token. |
+### Via `createAuthServer()` (recommended)
 
-### New in 2.0.0
+```typescript
+const auth = createAuthServer({
+  validRoles: ['user', 'admin'] as const,
+  db: { connectionString: process.env.DATABASE_URL! },
+  redisUrl: process.env.REDIS_URL,  // omit for in-memory cache
+});
 
-- **`accessCookie`** — store the access token in a non-httpOnly cookie for SPA use.
-- **`auth.getCurrentAccessToken(req)`** / **`getCurrentAccessToken(req, config)`** — extract the token from header or cookie.
-- **`createIdempotencyMiddleware()`** — idempotent mutations via `X-Idempotency-Key`.
-- **`hooks`** (`onLogin`, `onFailedLogin`, `onLogout`) — fire-and-forget lifecycle callbacks for audit logs, rate limiting, cache invalidation.
-- **`isTokenRevoked`** — optional callback for Redis-backed immediate token revocation without giving up stateless JWTs.
-- **Minified bundle** — library is built with tsup, reducing load time and install footprint.
-- **Memoised config resolution** — `resolveConfig` is cached per config object; HMAC secret derivation is cached per secret string.
+// Mount before your routes
+app.use(auth.idempotencyMiddleware());
 
-### Breaking changes in 1.1.0
+// Override TTL or methods
+app.use(auth.idempotencyMiddleware({ ttl: 60_000 }));
+```
 
-| What changed | Action required |
-|---|---|
-| `POST /signup` renamed to `POST /register` | Update all client-side calls |
-| `RouterHandlers.signup` renamed to `RouterHandlers.register` | Update config if you used a custom signup handler |
+When `redisUrl` is set in server config, the middleware automatically uses Redis — no extra config needed.
+
+### Standalone (without createAuthServer)
+
+```typescript
+import { createIdempotencyMiddleware } from 'sentri';
+
+// In-memory (single process)
+app.use(createIdempotencyMiddleware({ ttl: 300_000 }));
+
+// Redis (multi-process)
+app.use(createIdempotencyMiddleware({ redisUrl: 'redis://localhost:6379' }));
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `ttl` | `300_000` | Cache TTL in milliseconds |
+| `header` | `'X-Idempotency-Key'` | Header name to read the key from |
+| `methods` | `['POST','PUT','PATCH']` | HTTP methods to apply idempotency to |
+| `maxSize` | `10_000` | Max in-memory entries (ignored when `redisUrl` is set) |
+| `redisUrl` | — | Redis connection URL for multi-process cache |
+
+---
+
+## Migration Guide
 
-### Breaking changes in 1.2.0
+### 3.0.0 Breaking Changes
 
 | What changed | Action required |
 |---|---|
-| `AuthError` renamed to `SentriError` | Replace all `import { AuthError }` with `import { SentriError }` |
-| `AuthErrorCode` renamed to `SentriErrorCode` | Replace all `AuthErrorCode` type references |
-| `SignupResult` renamed to `RegisterResult` | Replace type references |
-| `SignupInput` renamed to `RegisterInput` | Replace type references |
-| `signup` service renamed to `register` | Replace `import { signup }` with `import { register }` |
+| `createAuth` now requires `mode: 'server'` or `mode: 'client'` | Add `mode: 'server'` to existing configs |
+| `adapter` field removed — Sentri owns the schema | Remove adapter, add `dialect` (Kysely Dialect) |
+| `algorithm` now supports `'RS256' \| 'RS384' \| 'RS512'` | Optional — HS256 still default |
+| `AuthError` renamed to `SentriError` | Update imports: `import { SentriError } from 'sentri'` |
+| `AUTH_ERROR_STATUS` renamed to `SENTRI_ERROR_STATUS` | Update references |
+| `npx sentri generate` removed | Run `await auth.migrate()` at startup instead |
+| Templates directory removed | No longer needed |