sentri 1.1.1 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # 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 + 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.
 
 ---
 
@@ -10,6 +10,13 @@ Auth and authorization library for Express + PostgreSQL. Provides JWT-based auth
 - [Quick Start](#quick-start)
 - [CLI](#cli)
 - [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)
@@ -17,6 +24,7 @@ Auth and authorization library for Express + PostgreSQL. Provides JWT-based auth
 - [Programmatic API](#programmatic-api)
 - [Types](#types)
 - [Error Handling](#error-handling)
+- [Migration Guide](#migration-guide)
 
 ---
 
@@ -55,15 +63,26 @@ prisma/
   schema.prisma          ← Prisma models (Prisma only, created or appended)
 ```
 
-### 2. Mount the router
+### 2. Mount the router and error handler
 
 ```typescript
 import express from 'express';
 import { auth } from './lib/sentri/auth.js';
+import { createIdempotencyMiddleware } from 'sentri';
 
 const app = express();
 app.use(express.json());
+
+// Optional: make POST/PUT/PATCH operations idempotent
+app.use(createIdempotencyMiddleware());
+
 app.use('/auth', auth.router());
+
+// ... your routes ...
+
+// Must be last — catches SentriError from sentri and your own subclasses
+app.use(auth.errorHandler());
+app.listen(3000);
 ```
 
 Done. All endpoints are available at `/auth/*`.
@@ -104,23 +123,43 @@ export const auth = createAuth({
   adapter: myAdapter,                     // required — see Adapter Interface
 
   // optional
-  accessExpiresIn: '15m',   // default: '15m'
+  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)
 
-  // Restrict POST /register to callers that supply X-Api-Key header.
-  // When set, only requests with this exact key can create new accounts.
+  // API key for POST /register — see apiKey section
   apiKey: process.env.REGISTER_API_KEY,  // optional
 
-  cookie: {                 // optional — enables httpOnly cookie for refresh token
+  // 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: '/'
+    // 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) => { ... },
@@ -132,53 +171,234 @@ export const auth = createAuth({
 });
 ```
 
-`accessExpiresIn` and `refreshExpiresIn` accept duration strings (`'15m'`, `'1h'`, `'7d'`, `'30d'`) or seconds as a number.
+`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' },
+  // ...
+});
+```
+
+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.
 
-When `cookie` is configured, the refresh token is stored in an httpOnly cookie automatically. No `cookie-parser` middleware is needed.
+### 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];
+```
+
+### Reading the token server-side
+
+```typescript
+import { getCurrentAccessToken } from 'sentri';
+
+app.get('/debug', (req, res) => {
+  // Checks Authorization header first, then access_token cookie
+  const token = getCurrentAccessToken(req, config);
+  res.json({ hasToken: !!token });
+});
+
+// Or via the auth client (pre-bound to config):
+const token = auth.getCurrentAccessToken(req);
+```
 
 ---
 
-## apiKey — Restricting Registration
+## 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.
+
+```
+Logout  → session deleted from DB
+Request with old access token → accepted until exp (≤ 5m)
+Request with old refresh token → rejected immediately (session gone)
+```
 
-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`.
+---
+
+## Automatic Token Refresh
+
+When `protect()` encounters an expired access token, it performs one silent refresh before returning an error:
 
-Set `apiKey` in your config to lock the endpoint:
+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.
+
+---
+
+## Request Idempotency
+
+`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.
+
+```typescript
+import { createIdempotencyMiddleware } 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
+
+| 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 |
+
+The idempotency key is also attached as `req.requestId` and echoed in the `X-Request-Id` response header for all requests that include it.
+
+```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
+});
+```
+
+**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.
 
 ```typescript
 export const auth = createAuth({
   // ...
-  apiKey: process.env.REGISTER_API_KEY!,
+  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);
+    },
+  },
 });
 ```
 
-Requests to `POST /register` must then include the header:
+### `AuthHooks` interface
+
+| 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` |
 
+> `POST /logout` (single session) does not fire `onLogout` — there is no authenticated user at that point. Use `onLogout` for "logout from all devices" events.
+
+---
+
+## Immediate Token Revocation (`isTokenRevoked`)
+
+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`:
+
+```typescript
+export const auth = createAuth({
+  // ...
+  isTokenRevoked: async (sessionId) =>
+    await redis.sismember('revoked_sessions', sessionId),
+});
 ```
-X-Api-Key: <value of REGISTER_API_KEY>
+
+After logout, add the `sessionId` to the revocation set:
+
+```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
 ```
 
-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.).
+`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.
 
 ---
 
-## Session-Bound Access Tokens
+## apiKey — Restricting Registration
 
-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.
+By default `POST /register` is open to the public. Set `apiKey` in your config to lock the endpoint:
 
-**What this means in practice:**
+```typescript
+export const auth = createAuth({
+  // ...
+  apiKey: process.env.REGISTER_API_KEY!,
+});
+```
 
-- `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.
+Requests to `POST /register` must then include the header:
 
 ```
-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
+X-Api-Key: <value of REGISTER_API_KEY>
 ```
 
-> **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.
+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.
 
 ---
 
@@ -186,10 +406,8 @@ Request → protect() verifies JWT → session not found → ✗ 401 UNAUTHORIZE
 
 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.
 
-Each key is optional — only override what you need. Any key you omit falls back to the built-in behaviour.
-
 ```typescript
-import { createAuth, AuthError } from 'sentri';
+import { createAuth, SentriError } from 'sentri';
 import type { AuthResult } from 'sentri';
 
 export const auth = createAuth({
@@ -202,7 +420,7 @@ export const auth = createAuth({
     login: async (input): Promise<AuthResult> => {
       const otpVerified = await redis.get(`otp:${input.identifier}`);
       if (!otpVerified) {
-        return { success: false, error: new AuthError('INVALID_CREDENTIALS', 'OTP required') };
+        return { success: false, error: new SentriError('INVALID_CREDENTIALS', 'OTP required') };
       }
       return defaultLogin(input);
     },
@@ -215,15 +433,6 @@ export const auth = createAuth({
       }
       return result;
     },
-
-    // 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;
-    },
   },
 });
 ```
@@ -232,15 +441,13 @@ export const auth = createAuth({
 
 | Key | Signature | Must return |
 |---|---|---|
-| `register` | `(input: SignupInput) => Promise<SignupResult>` | `SignupResult` |
+| `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
@@ -268,27 +475,6 @@ const adapter: AuthAdapter = {
 
 `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:
-
-```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);
-```
-
-`createAdapter` throws `AuthError` with code `CONFIGURATION_ERROR` at runtime if called without a `db` argument.
-
 ---
 
 ## Pre-built Router
@@ -296,20 +482,13 @@ export const adapter = createAdapter(db);
 `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
-}
+{ error: boolean, statusCode: number, message: string, data: T | null }
 ```
 
 ### 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[] }
@@ -317,84 +496,56 @@ Returns: { user: { id, identifier, roles } }
 Status:  201
 ```
 
-`password` must be 8–72 characters. `roles` must be a subset of `validRoles`.
-
----
-
 #### `POST /login`
 
-Authenticate a user and start a session.
-
 ```
 Body:    { identifier, password }
 Returns: { accessToken, user: { id, identifier, roles } }
+Cookies: access_token=<jwt>   (when config.accessCookie is set)
+         refresh_token=<jwt>  (httpOnly)
 Status:  200
 ```
 
-The refresh token is stored in an httpOnly cookie. The access token is returned in the response body.
-
----
-
 #### `POST /refresh`
 
-Exchange the refresh token cookie for a new access token. Implements session rotation — the old session is deleted and a new one is created.
-
 ```
-Cookie:  refresh_token=<token>   (set automatically by /login)
+Cookie:  refresh_token=<token>
 Returns: { accessToken }
+Cookies: access_token=<new-jwt>   (when config.accessCookie is set)
+         refresh_token=<new-jwt>  (rotated)
 Status:  200
 ```
 
-The new refresh token is written back to the cookie. No body required.
-
----
-
 #### `POST /logout`
 
-Invalidate the current session.
-
 ```
 Cookie:  refresh_token=<token>
+Clears:  access_token, refresh_token cookies
 Returns: null
 Status:  200
 ```
 
-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.
-
----
-
 #### `POST /logout-all`
 
-Invalidate all sessions for the authenticated user (logout from every device).
-
 ```
-Headers: Authorization: Bearer <accessToken>
+Headers: Authorization: Bearer <accessToken>  (or access_token cookie)
+Clears:  access_token, refresh_token cookies
 Returns: null
 Status:  200
 ```
 
-All access tokens across all devices are immediately rejected by `protect()` after this call.
-
----
-
 #### `GET /me`
 
-Return the currently authenticated user.
-
 ```
-Headers: Authorization: Bearer <accessToken>
+Headers: Authorization: Bearer <accessToken>  (or access_token cookie)
 Returns: { id, identifier, roles }
 Status:  200
 ```
 
----
-
 #### `POST /users/:userId/roles`
 
-Add roles to another user. Restricted to users with the `admin` role. Merges the given roles with the user's existing roles — no duplicates.
-
 ```
-Headers: Authorization: Bearer <accessToken>   (must have admin role)
+Headers: Authorization: Bearer <accessToken>  (must have admin role)
 Body:    { roles: string[] }
 Returns: { user: { id, identifier, roles } }
 Status:  200
@@ -406,7 +557,12 @@ Status:  200
 
 ### `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 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.
 
 ```typescript
 router.get('/dashboard', auth.protect(), (request, response) => {
@@ -415,23 +571,18 @@ router.get('/dashboard', auth.protect(), (request, response) => {
 ```
 
 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)
+- No token is present in header or cookie
+- The token signature is invalid
+- The token is expired **and** the refresh also fails
 
 ---
 
 ### `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.
+Enforces role-based access. Must be used **after** `auth.protect()`.
 
 ```typescript
-router.delete(
-  '/posts/:id',
-  auth.protect(),
-  auth.authorize('admin'),
-  handler,
-);
+router.delete('/posts/:id', auth.protect(), auth.authorize('admin'), handler);
 ```
 
 ---
@@ -441,23 +592,19 @@ router.delete(
 Resource-level permission check. Must be used **after** `auth.protect()`. Return `true` to allow, `false` to deny.
 
 ```typescript
-// Simple ownership check
-router.put(
-  '/users/:id',
-  auth.protect(),
-  auth.permit((request) => request.user!.id === request.params['id']),
+// Ownership check
+router.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 + custom check
+router.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.post.findById(req.params['id']);
+      return post?.authorId === req.user!.id;
     },
   }),
   handler,
@@ -466,23 +613,57 @@ router.delete(
 
 ---
 
+### `createIdempotencyMiddleware(options?)`
+
+Makes mutating operations idempotent via `X-Idempotency-Key` header. See [Request Idempotency](#request-idempotency).
+
+---
+
 ## Programmatic API
 
-Token and password utilities are available on the auth client for use outside the built-in router.
+### Token utilities
 
 ```typescript
-// Token utilities
 const accessToken = auth.signAccessToken({ id, identifier, roles });
-const user = auth.verifyAccessToken(accessToken);         // throws AuthError if invalid
-const { sessionId } = auth.verifyRefreshToken(token);    // throws AuthError if invalid
+const user = auth.verifyAccessToken(accessToken);         // throws SentriError if invalid
+const { sessionId } = auth.verifyRefreshToken(token);    // throws SentriError if invalid
 const refreshToken = auth.signRefreshToken(sessionId);
+```
 
-// Password utilities
+### Password utilities
+
+```typescript
 const hash = await auth.hashPassword('secret123');
 const valid = await auth.verifyPassword('secret123', hash);
 ```
 
-`verifyAccessToken` and `verifyRefreshToken` throw `AuthError` with code `TOKEN_EXPIRED` or `TOKEN_INVALID` — wrap them in a try/catch or use the router which handles this automatically.
+### 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'
+}
+```
 
 ---
 
@@ -493,32 +674,42 @@ import type {
   AuthConfig,
   AuthClient,
   AuthAdapter,
+  AuthHooks,
   AuthUser,
   AuthResult,
-  SignupResult,
+  RegisterResult,
   AssignRolesResult,
   RefreshResult,
   ApiResponse,
-  SignupInput,
+  RegisterInput,
   LoginInput,
   RouterHandlers,
   UserRecord,
   SessionRecord,
   CreateUserData,
   CookieConfig,
+  AccessCookieConfig,
+  IdempotencyOptions,
   PermitCheck,
   PermitOptions,
-  AuthErrorCode,
+  SentriErrorCode,
 } from 'sentri';
 
-import { AuthError, createAuth } from 'sentri';
+import {
+  SentriError,
+  AUTH_ERROR_STATUS,
+  createAuth,
+  register,
+  createIdempotencyMiddleware,
+  getCurrentAccessToken,
+} from 'sentri';
 ```
 
 ---
 
 ## Error Handling
 
-All errors thrown by the library are instances of `AuthError` with a machine-readable `code`:
+All errors thrown by the library are instances of `SentriError` with a machine-readable `code` and an HTTP `statusCode`:
 
 | Code | HTTP | Meaning |
 |---|---|---|
@@ -527,58 +718,75 @@ All errors thrown by the library are instances of `AuthError` with a machine-rea
 | `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 |
+| `UNAUTHORIZED` | 401 | No valid access 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 |
 
-The built-in router converts all `AuthError` instances to the standard envelope automatically. For custom routes:
+### `auth.errorHandler()`
+
+Mount **after all your routes**:
 
 ```typescript
-import { AuthError } from 'sentri';
-
-const AUTH_ERROR_STATUS: Record<string, number> = {
-  UNAUTHORIZED: 401,
-  TOKEN_EXPIRED: 401,
-  TOKEN_INVALID: 401,
-  INVALID_CREDENTIALS: 401,
-  FORBIDDEN: 403,
-  USER_NOT_FOUND: 404,
-  USER_ALREADY_EXISTS: 409,
-  INVALID_ROLE: 400,
-  VALIDATION_ERROR: 400,
-  CONFIGURATION_ERROR: 500,
-};
+app.use('/auth', auth.router());
+app.use('/api', apiRouter);
+app.use(auth.errorHandler());
+```
+
+### Extending `SentriError`
 
-app.use((error, _request, response, next) => {
-  if (error instanceof AuthError) {
-    const statusCode = AUTH_ERROR_STATUS[error.code] ?? 500;
-    return response.status(statusCode).json({
-      error: true,
-      statusCode,
-      code: error.code,
-      message: error.message,
-      data: null,
-    });
+```typescript
+import { SentriError } from 'sentri';
+
+export class NotFoundError extends SentriError {
+  constructor(resource: string) {
+    super('NOT_FOUND', `${resource} not found`, 404);
   }
-  next(error);
+}
+
+app.get('/items/:id', auth.protect(), async (req, res) => {
+  const item = await db.items.findById(req.params['id']);
+  if (!item) throw new NotFoundError('Item');
+  res.json(item);
 });
 ```
 
 ---
 
-## Migration from 1.0.x
+## Migration Guide
 
-### Breaking changes
+### Breaking changes in 2.0.0
+
+| 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. |
+
+### New in 2.0.0
+
+- **`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.
+
+### Breaking changes in 1.1.0
 
 | 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 |
 
-### New features
+### Breaking changes in 1.2.0
 
-- **Session-bound tokens** — access tokens are immediately invalidated after logout without waiting for expiry.
-- **`apiKey` config** — lock `POST /register` to trusted callers via `X-Api-Key` header.
+| 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 }` |