sentri 1.1.2 → 2.1.0

package/README.md

@@ -1,6 +1,9 @@
 # sentri
 
-Auth and authorization library for Express + PostgreSQL. Provides JWT-based authentication with session-bound access tokens, refresh token rotation, 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,16 +11,16 @@ Auth and authorization library for Express + PostgreSQL. Provides JWT-based auth
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [CLI](#cli)
+- [Server Mode](#server-mode)
+- [Client Mode](#client-mode)
+- [SSO Flow](#sso-flow)
 - [Configuration](#configuration)
-- [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)
-- [Migration from 1.0.x](#migration-from-10x)
+- [Request Idempotency](#request-idempotency)
+- [Migration Guide](#migration-guide)
 
 ---
 
@@ -27,444 +30,308 @@ Auth and authorization library for Express + PostgreSQL. Provides JWT-based auth
 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 { 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', auth.router());
+app.use(auth.idempotencyMiddleware());
 
-// ... your routes ...
+await auth.migrate();
+app.use('/auth', auth.router());
 
-// 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
-```
-
-**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 |
-
----
+`createAuthServer()` generates an RSA-2048 key pair at startup and enables `GET /keys` automatically.
 
-## 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: '15m',   // default: '15m'
-  refreshExpiresIn: '7d',   // default: '7d'
-  algorithm: 'HS256',       // default: 'HS256' — also 'HS384' | 'HS512'
-  saltRounds: 12,           // default: 12 (bcrypt rounds, min 10)
-
-  // Restrict POST /register to callers that supply X-Api-Key header.
-  // When set, only requests with this exact key can create new accounts.
-  apiKey: process.env.REGISTER_API_KEY,  // optional
-
-  cookie: {                 // optional — enables httpOnly cookie for refresh token
-    secure: process.env.NODE_ENV === 'production',
-    // name: 'refresh_token',  // default: 'refresh_token'
-    // httpOnly: true,          // default: true
-    // sameSite: 'strict',      // default: 'strict'
-    // path: '/',               // default: '/'
-  },
-
-  // 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 (`'15m'`, `'1h'`, `'7d'`, `'30d'`) or seconds as a number.
-
-When `cookie` is configured, the refresh token is stored in an httpOnly cookie automatically. No `cookie-parser` middleware is needed.
-
----
-
-## apiKey — Restricting Registration
-
-By default `POST /register` is open to the public. This can be a security risk when your application allows role selection at registration time — any caller could register themselves as `admin`.
-
-Set `apiKey` in your config to lock the endpoint:
-
-```typescript
-export const auth = createAuth({
-  // ...
-  apiKey: process.env.REGISTER_API_KEY!,
+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,
 });
-```
-
-Requests to `POST /register` must then include the header:
 
+const app = express();
+app.use(express.json());
+await auth.migrate();
+app.use('/auth', auth.router());
+app.use(auth.errorHandler());
+app.listen(3000);
 ```
-X-Api-Key: <value of REGISTER_API_KEY>
-```
-
-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 (your back-office panel, CI scripts, etc.).
-
----
 
-## Session-Bound Access Tokens
+### Client Mode (Other Apps)
 
-Since version 1.1.0, access tokens embed the `sessionId` of the session that was created at login. The `protect()` middleware validates this session against the database on every request.
+```typescript
+import express from 'express';
+import { createAuth } from 'sentri';
 
-**What this means in practice:**
+const auth = createAuth({
+  mode: 'client',
+  keyUri: 'https://auth.myapp.com/auth/keys',
+});
 
-- `POST /logout` deletes the session. Any access token issued during that login is immediately rejected — even if it has not expired yet.
-- `POST /logout-all` deletes **all** sessions for the user. Every access token across all devices is immediately rejected.
-- Tokens issued before 1.1.0 (without the `sessionId` claim) are still accepted but bypass session validation — plan a rolling upgrade if you need strict enforcement for existing 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);
 
+app.use(auth.errorHandler());
 ```
-Login  →  session created  →  access token embeds sessionId
-Request → protect() verifies JWT → checks session exists → ✓ allowed
-Logout  → session deleted
-Request → protect() verifies JWT → session not found → ✗ 401 UNAUTHORIZED
-```
-
-> **Trade-off:** `protect()` now performs one additional database read per request. For most applications this is negligible. If you need to avoid any per-request DB access, keep `accessExpiresIn` short (e.g. `'5m'`) and rely on token expiry instead — but note that tokens will remain valid for up to `accessExpiresIn` after logout.
 
 ---
 
-## Custom Route Handlers
+## Server Mode
 
-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.
+Server mode manages users, sessions, and tokens entirely within Sentri. The user provides a database dialect; Sentri handles the schema.
 
-Each key is optional — only override what you need. Any key you omit falls back to the built-in behaviour.
+### `createAuthServer(options)` — PostgreSQL shortcut
 
 ```typescript
-import { createAuth, SentriError } from 'sentri';
-import type { AuthResult } from 'sentri';
+import { createAuthServer } from 'sentri';
 
-export const auth = createAuth({
-  secret: process.env.JWT_SECRET!,
+const auth = createAuthServer({
   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;
-    },
+  // Connection string
+  db: { connectionString: process.env.DATABASE_URL!, max: 10 },
 
-    // Audit-log every token rotation
-    refresh: async (refreshToken) => {
-      const result = await defaultRefresh(refreshToken);
-      if (result.success) {
-        await auditLog.record('token_rotated', result.user.id);
-      }
-      return result;
-    },
-  },
+  // — or individual params —
+  // db: { host: 'localhost', port: 5432, database: 'mydb', user: 'app', password: 'secret' },
+
+  // Optional
+  accessExpiresIn: '15m',
+  refreshExpiresIn: '7d',
+  saltRounds: 12,
+  apiKey: process.env.REGISTER_API_KEY,
+  redisUrl: process.env.REDIS_URL,  // enables Redis-backed idempotency cache
 });
 ```
 
-### Available handler signatures
-
-| Key | Signature | Must return |
-|---|---|---|
-| `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` |
-
-The router always validates the request body and URL parameters before calling any handler. Your function receives the already-validated, trimmed input.
-
----
-
-## Adapter Interface
-
-The adapter connects sentri to your database. Implement `AuthAdapter` for any ORM or data layer.
+### `createAuth(config)` — Full config
 
 ```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>,
+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,
   },
-  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>,
-  },
-};
+});
 ```
 
-`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.
-
-### Using the generated adapter
-
-The generated `adapter.ts` exports `createAdapter(db)` so you can pass your existing database instance:
+### Database Migration
 
 ```typescript
-// Prisma
-import { PrismaClient } from '@prisma/client';
-import { createAdapter } from './adapter.js';
-
-const prisma = new PrismaClient();
-export const adapter = createAdapter(prisma);
-
-// Drizzle
-import { db } from '../db.js';
-import { createAdapter } from './adapter.js';
-
-export const adapter = createAdapter(db);
+// Call once at startup — uses IF NOT EXISTS, safe to repeat
+await auth.migrate();
 ```
 
-`createAdapter` throws `SentriError` with code `CONFIGURATION_ERROR` at runtime if called without a `db` argument.
+Creates two tables:
+- `sentri_users` — id, identifier, password_hash, roles (JSON), created_at
+- `sentri_sessions` — id, user_id, expires_at, created_at
 
 ---
 
-## Pre-built Router
+## Client Mode
 
-`auth.router()` returns an Express Router with all standard endpoints. Every response uses this envelope:
+Client mode has no database. It fetches the auth server's public key and validates JWTs stateless.
 
 ```typescript
-{
-  error: boolean,
-  statusCode: number,
-  message: string,
-  data: T | null
-}
+createAuth({
+  mode: 'client',
+  keyUri: 'https://auth.myapp.com/auth/keys',  // required
+  validRoles: ['admin', 'user'],               // optional — TypeScript type safety only
+});
 ```
 
-### Endpoints
-
-#### `POST /register`
-
-Register a new user. Does **not** issue tokens — call `/login` after registration.
-
-```
-Headers: X-Api-Key: <key>   (required when config.apiKey is set)
-Body:    { identifier, password, roles?: string[] }
-Returns: { user: { id, identifier, roles } }
-Status:  201
-```
+Available methods: `protect()`, `authorize()`, `permit()`, `errorHandler()`.
 
-`password` must be 8–72 characters. `roles` must be a subset of `validRoles`.
+The public key is fetched once and cached for 1 hour. Token validation is fully stateless.
 
 ---
 
-#### `POST /login`
+## SSO Flow
 
-Authenticate a user and start a session.
-
-```
-Body:    { identifier, password }
-Returns: { accessToken, user: { id, identifier, roles } }
-Status:  200
 ```
+[User]  →  POST /auth/login          (Sentri Auth Server)
+       ←   { accessToken, user }
 
-The refresh token is stored in an httpOnly cookie. The access token is returned in the response body.
-
----
-
-#### `POST /refresh`
+[User]  →  GET /products             (App A — client mode)
+           Authorization: Bearer <accessToken>
+       ←   App A fetches public key from GET /auth/keys, verifies JWT
+       ←   200 OK
+```
 
-Exchange the refresh token cookie for a new access token. Implements session rotation — the old session is deleted and a new one is created.
+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).
 
 ```
-Cookie:  refresh_token=<token>   (set automatically by /login)
-Returns: { accessToken }
-Status:  200
+GET /auth/keys → { keys: [{ kty, use, kid, n, e, ... }] }
 ```
 
-The new refresh token is written back to the cookie. No body required.
+Client apps point `keyUri` at this endpoint and receive the public key automatically.
 
 ---
 
-#### `POST /logout`
-
-Invalidate the current session.
-
-```
-Cookie:  refresh_token=<token>
-Returns: null
-Status:  200
-```
+## Configuration
 
-After logout, any access token bound to this session is immediately rejected by `protect()`. Safe to call even if the cookie is missing or the token is already expired.
+### `algorithm`
 
----
+| Value | Type | Use case |
+|---|---|---|
+| `'HS256'` | Symmetric (default) | Single app, shared secret |
+| `'RS256'` | Asymmetric | SSO — enables `GET /keys` |
 
-#### `POST /logout-all`
+When using RS256, `secret` must be a valid RSA private key in PEM format. `createAuthServer()` generates the key pair automatically.
 
-Invalidate all sessions for the authenticated user (logout from every device).
+### Cookie Strategy (SPA)
 
-```
-Headers: Authorization: Bearer <accessToken>
-Returns: null
-Status:  200
+```typescript
+createAuth({
+  mode: 'server',
+  cookie: { secure: true },        // httpOnly refresh token
+  accessCookie: { secure: true },  // non-httpOnly access token (readable by JS)
+});
 ```
 
-All access tokens across all devices are immediately rejected by `protect()` after this call.
+After login, both cookies are set automatically. `protect()` reads the access token from the cookie when no `Authorization` header is present.
 
 ---
 
-#### `GET /me`
+## Endpoints
 
-Return the currently authenticated user.
+`auth.router()` mounts these endpoints:
 
-```
-Headers: Authorization: Bearer <accessToken>
-Returns: { id, identifier, roles }
-Status:  200
+| 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) |
+
+All responses use the envelope:
+```json
+{ "error": false, "statusCode": 200, "message": "...", "data": { ... } }
 ```
 
----
+### Change Identifier
 
-#### `POST /users/:userId/roles`
+```
+PATCH /me/identifier
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "identifier": "new@example.com" }
+```
 
-Add roles to another user. Restricted to users with the `admin` role. Merges the given roles with the user's existing roles — no duplicates.
+### Change Password
 
 ```
-Headers: Authorization: Bearer <accessToken>   (must have admin role)
-Body:    { roles: string[] }
-Returns: { user: { id, identifier, roles } }
-Status:  200
+PATCH /me/password
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "currentPassword": "old-pass", "newPassword": "new-pass" }
 ```
 
+Changing the password revokes all existing sessions. The user must log in again after this call.
+
 ---
 
 ## Middleware
 
 ### `auth.protect()`
 
-Verifies the `Authorization: Bearer <token>` header, confirms the session is still active in the database, and injects `request.user` into the request.
+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:
-- The `Authorization` header is missing or malformed
-- The token signature is invalid or the token is expired
-- The session embedded in the token has been revoked (logout)
-
----
+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()`. Passes if the user has at least one of the specified roles.
+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
-// Simple ownership check
-router.put(
-  '/users/:id',
-  auth.protect(),
-  auth.permit((request) => request.user!.id === request.params['id']),
+// Ownership check
+app.put('/users/:id', auth.protect(),
+  auth.permit((req) => req.user!.id === req.params.id),
   handler,
 );
 
-// Admins bypass the check; others must own the resource
-router.delete(
-  '/posts/:id',
-  auth.protect(),
+// Role bypass + ownership check
+app.delete('/posts/:id', auth.protect(),
   auth.permit({
     roles: ['admin'],
-    check: async (request) => {
-      const post = await db.post.findUnique({ where: { id: request.params['id'] } });
-      return post?.authorId === request.user!.id;
+    check: async (req) => {
+      const post = await db.posts.findById(req.params.id);
+      return post?.authorId === req.user!.id;
     },
   }),
   handler,
@@ -473,176 +340,129 @@ router.delete(
 
 ---
 
-## Programmatic API
+## Token Utilities
 
-Token and password utilities are available on the auth client for use outside the built-in router.
+Available on `ServerAuthClient` only:
 
 ```typescript
-// Token utilities
-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 refreshToken = auth.signRefreshToken(sessionId);
+const auth = createAuth({ mode: 'server', ... });
 
-// Password utilities
-const hash = await auth.hashPassword('secret123');
-const valid = await auth.verifyPassword('secret123', hash);
-```
-
-`verifyAccessToken` and `verifyRefreshToken` throw `SentriError` with code `TOKEN_EXPIRED` or `TOKEN_INVALID` — wrap them in a try/catch or use the router which handles this automatically.
-
-### `register` — standalone service function
-
-The `register` function is also exported directly so you can call it outside the built-in router (e.g. in tests, scripts, or admin tools):
+// Sign
+const accessToken  = auth.signAccessToken({ id, identifier, roles });
+const refreshToken = auth.signRefreshToken(sessionId);
 
-```typescript
-import { register } from 'sentri';
+// Verify
+const user          = auth.verifyAccessToken(accessToken);
+const { sessionId } = auth.verifyRefreshToken(refreshToken);
 
-const result = await register(
-  { identifier: 'alice@example.com', password: 'hunter2', roles: ['user'] },
-  config,
-);
+// Password
+const hash  = await auth.hashPassword('secret123');
+const valid = await auth.verifyPassword('secret123', hash);
 
-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,
-  AuthUser,
-  AuthResult,
-  RegisterResult,
-  AssignRolesResult,
-  RefreshResult,
-  ApiResponse,
-  RegisterInput,
-  LoginInput,
-  RouterHandlers,
-  UserRecord,
-  SessionRecord,
-  CreateUserData,
-  CookieConfig,
-  PermitCheck,
-  PermitOptions,
-  SentriErrorCode,
-} from 'sentri';
-
-import { SentriError, AUTH_ERROR_STATUS, createAuth, register } 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, revoked session, or invalid API key |
+| `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 `auth.errorHandler()` **after all your routes** to automatically format every `SentriError` (and any subclass) into the standard envelope:
-
-```typescript
-app.use('/auth', auth.router());
-app.use('/api', apiRouter);
-
-// Must be last
-app.use(auth.errorHandler());
-```
-
-Optional logger for unexpected errors:
-
-```typescript
-app.use(auth.errorHandler({
-  onUnhandled: (err) => logger.error('Unexpected error', { err }),
-}));
-```
+| `INVALID_ROLE` | 400 | Role not in `validRoles` |
+| `VALIDATION_ERROR` | 400 | Missing or invalid input |
+| `CONFIGURATION_ERROR` | 500 | Invalid `createAuth` config |
 
 ### Extending `SentriError`
 
-Define application-specific errors by extending `SentriError`. They are caught automatically by `auth.errorHandler()` via `instanceof`:
-
 ```typescript
 import { SentriError } from 'sentri';
 
-export class NotFoundError extends SentriError {
+class NotFoundError extends SentriError {
   constructor(resource: string) {
     super('NOT_FOUND', `${resource} not found`, 404);
   }
 }
 
-export class PaymentError extends SentriError {
-  constructor(message: string) {
-    super('PAYMENT_FAILED', message, 402);
-  }
-}
-
-// Throw anywhere in your routes — auth.errorHandler() catches them all
+// 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);
 });
 ```
 
-Response shape for any `SentriError` (built-in or custom):
+---
 
-```json
-{
-  "error": true,
-  "statusCode": 404,
-  "code": "NOT_FOUND",
-  "message": "Item not found",
-  "data": null
-}
+## Request Idempotency
+
+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.
+
+### Via `createAuthServer()` (recommended)
+
+```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
+});
+
+// Mount before your routes
+app.use(auth.idempotencyMiddleware());
+
+// Override TTL or methods
+app.use(auth.idempotencyMiddleware({ ttl: 60_000 }));
 ```
 
----
+When `redisUrl` is set in server config, the middleware automatically uses Redis — no extra config needed.
 
-## Migration from 1.0.x
+### Standalone (without createAuthServer)
 
-### Breaking changes in 1.1.0
+```typescript
+import { createIdempotencyMiddleware } from 'sentri';
 
-| 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 |
-| `protect()` now performs one DB read per request | Ensure your adapter's `session.findById` is indexed on session ID |
+// 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 }` |
-
-### New features in 1.2.0
-
-- **`auth.errorHandler()`** — built-in Express error handler mounted like `auth.router()`.
-- **`SentriError.statusCode`** — each error carries its own HTTP status; no need for a manual status map.
-- **Extensible errors** — subclass `SentriError` with a custom `code` and `statusCode`; `auth.errorHandler()` catches all subclasses automatically.
-- **`register` exported** — the registration service function is now a named export for use outside the built-in router.
+| `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 |