sentri 4.1.1 → 5.0.0

package/README.md

@@ -1,16 +1,35 @@
 # sentri
 
-Auth and authorization library for Express. Supports two modes:
+[![npm version](https://img.shields.io/npm/v/sentri.svg)](https://www.npmjs.com/package/sentri) [![license](https://img.shields.io/npm/l/sentri.svg)](LICENSE) [![build](https://img.shields.io/github/actions/workflow/status/rizzzdev/sentri/build.yml?branch=main)](https://github.com/rizzzdev/sentri/actions)
+
+Auth and authorization library for Node.js — Express, Fastify, Hono, Elysia, and Koa. 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.
 
+## Subpath exports
+
+| Import           | Description                                                |
+| ---------------- | ---------------------------------------------------------- |
+| `sentri`         | Full package re-export (backward compat)                   |
+| `sentri/core`    | Framework-agnostic types, `SentriError`, `SentriLogger`    |
+| `sentri/express` | Express adapter — `createAuthExpress`, middleware, router  |
+| `sentri/fastify` | Fastify adapter — `createAuthFastify`, preHandlers, plugin |
+| `sentri/hono`    | Hono adapter — `createAuthHono`, middleware, router        |
+| `sentri/elysia`  | Elysia adapter — `createAuthElysia`, middleware, router    |
+| `sentri/koa`     | Koa adapter — `createAuthKoa`, middleware, router          |
+
 ---
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+  - [Express](#express-server-mode-recommended)
+  - [Fastify](#fastify-server-mode)
+  - [Hono](#hono-server-mode)
+  - [Elysia](#elysia-server-mode)
+  - [Client mode](#client-mode-1)
 - [Server Mode](#server-mode)
 - [Client Mode](#client-mode)
 - [SSO Flow](#sso-flow)
@@ -32,9 +51,15 @@ Auth and authorization library for Express. Supports two modes:
 npm install sentri
 ```
 
-`kysely` and `pg` are bundled with sentri — no separate installation needed for PostgreSQL.
+`kysely` is bundled with sentri — no separate installation needed for Kysely. However, you must install the driver for your database of choice.
 
-For other databases, install the driver:
+For PostgreSQL:
+
+```bash
+npm install pg
+```
+
+For other databases:
 
 ```bash
 # MySQL
@@ -44,21 +69,43 @@ npm install mysql2
 npm install better-sqlite3
 ```
 
-**Peer dependency:** `express >= 4.0.0`
+**Peer dependencies** (install only what you use):
+
+```bash
+# Express
+npm install express
+
+# Fastify
+npm install fastify @fastify/cookie
+
+# Hono
+npm install hono
+
+# Elysia
+npm install elysia
+```
 
 ---
 
 ## Quick Start
 
-### Server Mode — PostgreSQL (recommended)
+### Express (server mode, recommended)
 
 ```typescript
-import express from 'express';
-import { createAuthServer } from 'sentri';
+import express from "express";
+import { createAuthExpress } from "sentri/express";
 
-const auth = createAuthServer({
-  validRoles: ['user', 'admin'] as const,
-  db: { connectionString: process.env.DATABASE_URL! },
+import { PostgresDialect } from "kysely";
+import pg from "pg";
+
+const { Pool } = pg;
+
+const auth = createAuthExpress({
+  mode: "server",
+  validRoles: ["user", "admin"] as const,
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL! }),
+  }),
 });
 
 const app = express();
@@ -66,35 +113,190 @@ app.use(express.json());
 app.use(auth.idempotencyMiddleware());
 
 await auth.migrate();
-app.use('/auth', auth.router());
+app.use("/auth", auth.router());
 
-app.get('/me', auth.protect(), (req, res) => res.json(req.user));
+app.get("/me", auth.protect(), (req, res) => res.json(req.user));
 app.use(auth.errorHandler());
 app.listen(3000);
 ```
 
 `createAuthServer()` generates an RSA-2048 key pair at startup and enables `GET /keys` automatically.
 
+For detailed Express docs see [src/adapters/express/README.md](src/adapters/express/README.md).
+
+### Fastify (server mode)
+
+```typescript
+import Fastify from "fastify";
+import cookie from "@fastify/cookie";
+import { createAuthFastify } from "sentri/fastify";
+
+import { PostgresDialect } from "kysely";
+import pg from "pg";
+
+const { Pool } = pg;
+
+const auth = createAuthFastify({
+  mode: "server",
+  validRoles: ["user", "admin"] as const,
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL! }),
+  }),
+});
+
+await auth.migrate();
+
+const app = Fastify();
+await app.register(cookie);
+await app.register(auth.plugin(), { prefix: "/auth" });
+app.setErrorHandler(auth.errorHandler());
+
+app.get("/me", { preHandler: auth.protect() }, async (request, reply) => {
+  reply.send(request.user);
+});
+
+await app.listen({ port: 3000 });
+```
+
+For detailed Fastify docs see [src/adapters/fastify/README.md](src/adapters/fastify/README.md).
+
+### Hono (server mode)
+
+```typescript
+import { Hono } from "hono";
+import { createAuthHono } from "sentri/hono";
+import type { SentriHonoEnv } from "sentri/hono";
+
+import { PostgresDialect } from "kysely";
+import pg from "pg";
+
+const { Pool } = pg;
+
+const auth = createAuthHono({
+  mode: "server",
+  validRoles: ["user", "admin"] as const,
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL! }),
+  }),
+});
+
+await auth.migrate();
+
+const app = new Hono<SentriHonoEnv>();
+
+app.route("/auth", auth.router());
+
+app.get("/me", auth.protect(), (c) => c.json(c.get("user")));
+
+app.onError(auth.errorHandler());
+
+export default app;
+```
+
+`createAuthHono` generates an RSA-2048 key pair at startup and enables `GET /keys` automatically. Works with Node.js, Cloudflare Workers, Bun, and Deno — use **client mode** for edge runtimes that cannot reach a PostgreSQL database.
+
+For detailed Hono docs see [src/adapters/hono/README.md](src/adapters/hono/README.md).
+
+### Elysia (server mode)
+
+```typescript
+import { Elysia } from "elysia";
+import { createAuthElysia } from "sentri/elysia";
+
+import { PostgresDialect } from "kysely";
+import pg from "pg";
+
+const { Pool } = pg;
+
+const auth = createAuthElysia({
+  mode: "server",
+  validRoles: ["user", "admin"] as const,
+  dialect: new PostgresDialect({
+    pool: new Pool({ connectionString: process.env.DATABASE_URL! }),
+  }),
+});
+
+await auth.migrate();
+
+const app = new Elysia()
+  .onError(auth.errorHandler())
+  .group("/auth", (app) => app.use(auth.router()))
+  .use(auth.protect())
+  .get("/me", ({ user }) => user);
+
+app.listen(3000);
+```
+
+For detailed Elysia docs see [src/adapters/elysia/README.md](src/adapters/elysia/README.md).
+
+### Koa (server mode)
+
+```typescript
+import Koa from "koa";
+import Router from "@koa/router";
+import bodyParser from "koa-bodyparser";
+import { createAuthKoa } from "sentri/koa";
+
+const auth = createAuthKoa({
+  mode: "server",
+  validRoles: ["user", "admin"] as const,
+  db: { connectionString: process.env.DATABASE_URL! },
+});
+
+await auth.migrate();
+
+const app = new Koa();
+app.use(bodyParser());
+app.use(auth.errorHandler());
+
+const rootRouter = new Router();
+rootRouter.use("/auth", auth.router().routes(), auth.router().allowedMethods());
+
+rootRouter.get("/me", auth.protect(), (ctx) => {
+  ctx.body = ctx.state.user;
+});
+
+app.use(rootRouter.routes());
+app.use(rootRouter.allowedMethods());
+
+app.listen(3000);
+```
+
+For detailed Koa docs see [src/adapters/koa/README.md](src/adapters/koa/README.md).
+
+### Client mode (any framework, any server)
+
+```typescript
+import { createAuthExpress } from "sentri/express";
+
+const auth = createAuthExpress({
+  mode: "client",
+  keyUri: "https://auth.myapp.com/auth/keys",
+});
+```
+
 ### Server Mode — Custom Dialect
 
 ```typescript
-import express from 'express';
-import { createAuth } from 'sentri';
-import { PostgresDialect } from 'kysely';  // kysely is bundled, no install needed
-import { Pool } from 'pg';                 // pg is bundled, no install needed
+import express from "express";
+import { createAuth } from "sentri";
+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,
+  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,
 });
 
 const app = express();
 app.use(express.json());
 await auth.migrate();
-app.use('/auth', auth.router());
+app.use("/auth", auth.router());
 app.use(auth.errorHandler());
 app.listen(3000);
 ```
@@ -102,17 +304,22 @@ app.listen(3000);
 ### Client Mode (Other Apps)
 
 ```typescript
-import express from 'express';
-import { createAuth } from 'sentri';
+import express from "express";
+import { createAuth } from "sentri";
 
 const auth = createAuth({
-  mode: 'client',
-  keyUri: 'https://auth.myapp.com/auth/keys',
+  mode: "client",
+  keyUri: "https://auth.myapp.com/auth/keys",
 });
 
 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.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());
 ```
@@ -126,10 +333,10 @@ Server mode manages users, sessions, and tokens entirely within Sentri. The user
 ### `createAuthServer(options)` — PostgreSQL shortcut
 
 ```typescript
-import { createAuthServer } from 'sentri';
+import { createAuthServer } from "sentri/express";
 
 const auth = createAuthServer({
-  validRoles: ['user', 'admin'] as const,
+  validRoles: ["user", "admin"] as const,
 
   // Connection string
   db: { connectionString: process.env.DATABASE_URL!, max: 10 },
@@ -138,37 +345,48 @@ const auth = createAuthServer({
   // db: { host: 'localhost', port: 5432, database: 'mydb', user: 'app', password: 'secret' },
 
   // Optional
-  accessExpiresIn: '15m',
-  refreshExpiresIn: '7d',
+  accessExpiresIn: "15m",
+  refreshExpiresIn: "7d",
   saltRounds: 12,
   apiKey: process.env.REGISTER_API_KEY,
-  redisUrl: process.env.REDIS_URL,  // enables Redis-backed idempotency cache
+  redisUrl: process.env.REDIS_URL, // enables Redis-backed idempotency cache
 });
 ```
 
 ### `createAuth(config)` — Full config
 
 ```typescript
+import { createAuth } from "sentri/express";
+
 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)
+  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,
-    bulkCreateIdentifiers, bulkUpdateIdentifiers, bulkDeleteIdentifiers,
-    changePrimaryIdentifier, changePassword,
+  isTokenRevoked: async (sessionId) =>
+    await redis.sismember("revoked", sessionId),
+  router: {
+    // override built-in service functions
+    login,
+    register,
+    refresh,
+    logout,
+    logoutAll,
+    assignRoles,
+    bulkCreateIdentifiers,
+    bulkUpdateIdentifiers,
+    bulkDeleteIdentifiers,
+    changePassword,
   },
 });
 ```
@@ -181,9 +399,10 @@ await auth.migrate();
 ```
 
 Creates three tables:
+
 - `sentri_users` — id, password_hash, roles (JSON), created_at
 - `sentri_sessions` — id, user_id, expires_at, created_at
-- `sentri_identifiers` — id, user_id, type, value (globally unique), is_primary, created_at
+- `sentri_identifiers` — id, user_id, type, value (globally unique), created_at
 
 ---
 
@@ -193,9 +412,9 @@ Client mode has no database. It fetches the auth server's public key and validat
 
 ```typescript
 createAuth({
-  mode: 'client',
-  keyUri: 'https://auth.myapp.com/auth/keys',  // required
-  validRoles: ['admin', 'user'],               // optional — TypeScript type safety only
+  mode: "client",
+  keyUri: "https://auth.myapp.com/auth/keys", // required
+  validRoles: ["admin", "user"], // optional — TypeScript type safety only
 });
 ```
 
@@ -231,11 +450,11 @@ Client apps point `keyUri` at this endpoint and receive the public key automatic
 
 Each user can have multiple identifiers — email, username, phone number, or any custom type. All identifier values are **globally unique** regardless of type.
 
-One identifier per user is marked as **primary** and its value is embedded in the JWT payload. Regardless of which identifier a user logs in with, the JWT always contains the primary identifier.
+Login accepts any identifier value — Sentri searches all types automatically. No concept of "primary" exists; the JWT payload only contains `{ id, roles, sessionId }`.
 
 ### Registration
 
-Provide at least one identifier. The first entry becomes the primary.
+Provide at least one identifier.
 
 ```
 POST /register
@@ -252,6 +471,7 @@ Content-Type: application/json
 ```
 
 **Response:**
+
 ```json
 {
   "error": false,
@@ -260,12 +480,10 @@ Content-Type: application/json
   "data": {
     "user": {
       "id": "uuid",
-      "identifier": "rizz@example.com",
-      "identifierType": "email",
       "roles": ["user"],
       "identifiers": [
-        { "id": "uuid-1", "type": "email",    "value": "rizz@example.com", "isPrimary": true },
-        { "id": "uuid-2", "type": "username", "value": "rizz",             "isPrimary": false }
+        { "id": "uuid-1", "type": "email", "value": "rizz@example.com" },
+        { "id": "uuid-2", "type": "username", "value": "rizz" }
       ]
     }
   }
@@ -323,18 +541,6 @@ Content-Type: application/json
 
 At least one identifier must remain after deletion.
 
-### Change Primary Identifier
-
-```
-PATCH /me/identifiers/primary
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{ "id": "uuid-2" }
-```
-
-The new primary value will be embedded in the JWT on the next login or token refresh.
-
 ### Programmatic API
 
 ```typescript
@@ -357,9 +563,6 @@ await auth.bulkUpdateIdentifiers(userId, [{ id: 'uuid-2', type: 'username', valu
 
 // Delete identifiers
 await auth.bulkDeleteIdentifiers(userId, ['uuid-2']);
-
-// Change primary
-await auth.changePrimaryIdentifier(userId, 'uuid-3');
 ```
 
 ---
@@ -368,10 +571,10 @@ await auth.changePrimaryIdentifier(userId, 'uuid-3');
 
 ### `algorithm`
 
-| Value | Type | Use case |
-|---|---|---|
+| Value     | Type                | Use case                  |
+| --------- | ------------------- | ------------------------- |
 | `'HS256'` | Symmetric (default) | Single app, shared secret |
-| `'RS256'` | Asymmetric | SSO — enables `GET /keys` |
+| `'RS256'` | Asymmetric          | SSO — enables `GET /keys` |
 
 When using RS256, `secret` must be a valid RSA private key in PEM format. `createAuthServer()` generates the key pair automatically.
 
@@ -379,9 +582,9 @@ When using RS256, `secret` must be a valid RSA private key in PEM format. `creat
 
 ```typescript
 createAuth({
-  mode: 'server',
-  cookie: { secure: true },        // httpOnly refresh token
-  accessCookie: { secure: true },  // non-httpOnly access token (readable by JS)
+  mode: "server",
+  cookie: { secure: true }, // httpOnly refresh token
+  accessCookie: { secure: true }, // non-httpOnly access token (readable by JS)
 });
 ```
 
@@ -393,23 +596,23 @@ After login, both cookies are set automatically. `protect()` reads the access to
 
 `auth.router()` mounts these endpoints:
 
-| 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 with all identifiers |
-| `POST` | `/me/identifiers` | ✓ self | Add identifiers in bulk |
-| `PUT` | `/me/identifiers` | ✓ self | Update identifiers in bulk |
-| `DELETE` | `/me/identifiers` | ✓ self | Delete identifiers in bulk |
-| `PATCH` | `/me/identifiers/primary` | ✓ self | Change primary identifier |
-| `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) |
+| 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 with all identifiers            |
+| `POST`   | `/me/identifiers`      | ✓ self  | Add identifiers in bulk                                   |
+| `PUT`    | `/me/identifiers`      | ✓ self  | Update identifiers in bulk                                |
+| `DELETE` | `/me/identifiers`      | ✓ self  | Delete identifiers in bulk                                |
+| `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": { ... } }
 ```
@@ -432,45 +635,64 @@ Changing the password revokes all existing sessions. The user must log in again
 
 ### `auth.protect()`
 
-Verifies the JWT and sets `req.user`. In server mode, also performs silent token refresh when the access token expires.
+Verifies the JWT and sets the user on the request context. In server mode, also performs silent token refresh when the access token expires.
+
+Token is read from `Authorization: Bearer <token>` header or `access_token` cookie.
 
 ```typescript
-app.get('/dashboard', auth.protect(), (req, res) => res.json(req.user));
-// req.user: { id, identifier, identifierType, roles, identifiers? }
-```
+// Express
+app.get("/dashboard", auth.protect(), (req, res) => res.json(req.user));
+// req.user: { id, roles }
+
+// Fastify
+app.get(
+  "/dashboard",
+  { preHandler: auth.protect() },
+  async (request) => request.user,
+);
 
-Token is read from `Authorization: Bearer <token>` header or `access_token` cookie.
+// Hono
+app.get("/dashboard", auth.protect(), (c) => c.json(c.get("user")));
+```
 
 ### `auth.authorize(...roles)`
 
 Role-based access — must follow `protect()`.
 
 ```typescript
-app.delete('/posts/:id', auth.protect(), auth.authorize('admin'), handler);
+// Express / Fastify preHandler / Hono — same API
+app.delete("/posts/:id", auth.protect(), auth.authorize("admin"), handler);
 ```
 
 ### `auth.permit(check | options)`
 
-Resource-level permission — must follow `protect()`.
+Resource-level permission — must follow `protect()`. The check function receives the request context object of each framework.
 
 ```typescript
-// Ownership check
-app.put('/users/:id', auth.protect(),
+// Express
+app.put(
+  "/users/:id",
+  auth.protect(),
   auth.permit((req) => req.user!.id === req.params.id),
   handler,
 );
 
-// Role bypass + ownership check
-app.delete('/posts/:id', auth.protect(),
-  auth.permit({
-    roles: ['admin'],
-    check: async (req) => {
-      const post = await db.posts.findById(req.params.id);
-      return post?.authorId === req.user!.id;
-    },
-  }),
+// Hono
+app.put(
+  "/users/:id",
+  auth.protect(),
+  auth.permit((c) => c.get("user")!.id === c.req.param("id")),
   handler,
 );
+
+// Role bypass + ownership check
+auth.permit({
+  roles: ["admin"],
+  check: async (req) => {
+    const post = await db.posts.findById(req.params.id);
+    return post?.authorId === req.user!.id;
+  },
+});
 ```
 
 ---
@@ -483,7 +705,7 @@ Available on `ServerAuthClient` only:
 const auth = createAuth({ mode: 'server', ... });
 
 // Sign
-const accessToken  = auth.signAccessToken({ id, identifier, identifierType, roles });
+const accessToken  = auth.signAccessToken({ id, roles });
 const refreshToken = auth.signRefreshToken(sessionId);
 
 // Verify
@@ -503,41 +725,49 @@ const token = auth.getCurrentAccessToken(req);
 ## Error Handling
 
 ```typescript
-app.use('/auth', auth.router());
-app.use('/api', apiRouter);
-app.use(auth.errorHandler());  // must be last
-```
-
-| Code | HTTP | Meaning |
-|---|---|---|
-| `INVALID_CREDENTIALS` | 401 | Wrong identifier or password |
-| `USER_NOT_FOUND` | 404 | User does not exist |
-| `USER_ALREADY_EXISTS` | 409 | Duplicate identifier at registration |
-| `IDENTIFIER_NOT_FOUND` | 404 | Referenced identifier ID does not exist or belongs to another user |
-| `IDENTIFIER_ALREADY_EXISTS` | 409 | Identifier value already taken by another user |
-| `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 not in `validRoles` |
-| `VALIDATION_ERROR` | 400 | Missing or invalid input |
-| `CONFIGURATION_ERROR` | 500 | Invalid `createAuth` config |
+// Express — must be last
+app.use("/auth", auth.router());
+app.use("/api", apiRouter);
+app.use(auth.errorHandler());
+
+// Fastify
+app.setErrorHandler(auth.errorHandler());
+
+// Hono — mount via onError
+app.route("/auth", auth.router());
+app.onError(auth.errorHandler());
+```
+
+| Code                        | HTTP | Meaning                                                            |
+| --------------------------- | ---- | ------------------------------------------------------------------ |
+| `INVALID_CREDENTIALS`       | 401  | Wrong identifier or password                                       |
+| `USER_NOT_FOUND`            | 404  | User does not exist                                                |
+| `USER_ALREADY_EXISTS`       | 409  | Duplicate identifier at registration                               |
+| `IDENTIFIER_NOT_FOUND`      | 404  | Referenced identifier ID does not exist or belongs to another user |
+| `IDENTIFIER_ALREADY_EXISTS` | 409  | Identifier value already taken by another user                     |
+| `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 not in `validRoles`                                           |
+| `VALIDATION_ERROR`          | 400  | Missing or invalid input                                           |
+| `CONFIGURATION_ERROR`       | 500  | Invalid `createAuth` config                                        |
 
 ### Extending `SentriError`
 
 ```typescript
-import { SentriError } from 'sentri';
+import { SentriError } from "sentri";
 
 class NotFoundError extends SentriError {
   constructor(resource: string) {
-    super('NOT_FOUND', `${resource} not found`, 404);
+    super("NOT_FOUND", `${resource} not found`, 404);
   }
 }
 
 // Caught automatically by auth.errorHandler()
-app.get('/items/:id', auth.protect(), async (req, res) => {
+app.get("/items/:id", auth.protect(), async (req, res) => {
   const item = await db.items.findById(req.params.id);
-  if (!item) throw new NotFoundError('Item');
+  if (!item) throw new NotFoundError("Item");
   res.json(item);
 });
 ```
@@ -552,9 +782,9 @@ Repeat requests with the same `X-Idempotency-Key` header receive the cached resp
 
 ```typescript
 const auth = createAuthServer({
-  validRoles: ['user', 'admin'] as const,
+  validRoles: ["user", "admin"] as const,
   db: { connectionString: process.env.DATABASE_URL! },
-  redisUrl: process.env.REDIS_URL,  // omit for in-memory cache
+  redisUrl: process.env.REDIS_URL, // omit for in-memory cache
 });
 
 // Mount before your routes
@@ -569,24 +799,24 @@ When `redisUrl` is set in server config, the middleware automatically uses Redis
 ### Standalone (without createAuthServer)
 
 ```typescript
-import { createIdempotencyMiddleware } from 'sentri';
+import { createIdempotencyMiddleware } from "sentri";
 
 // In-memory (single process)
 app.use(createIdempotencyMiddleware({ ttl: 300_000 }));
 
 // Redis (multi-process)
-app.use(createIdempotencyMiddleware({ redisUrl: 'redis://localhost:6379' }));
+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 |
+| 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           |
 
 ---
 
@@ -599,22 +829,24 @@ Sentri produces structured JSON log entries for every auth event. Logging is **o
 Pass any object that implements `{ info, warn, error }` via the `logger` field in your config.
 
 **pino** (recommended for production):
+
 ```typescript
-import pino from 'pino';
+import pino from "pino";
 
 const auth = createAuth({
-  mode: 'server',
+  mode: "server",
   // ...other config
   logger: pino(),
 });
 ```
 
 **winston**:
+
 ```typescript
-import winston from 'winston';
+import winston from "winston";
 
 const auth = createAuth({
-  mode: 'server',
+  mode: "server",
   // ...other config
   logger: winston.createLogger({
     transports: [new winston.transports.Console()],
@@ -623,19 +855,21 @@ const auth = createAuth({
 ```
 
 **console** (zero setup, good for development):
+
 ```typescript
 const auth = createAuth({
-  mode: 'server',
+  mode: "server",
   // ...other config
   logger: console,
 });
 ```
 
 Works identically in **client mode**:
+
 ```typescript
 const auth = createAuth({
-  mode: 'client',
-  keyUri: 'https://auth.myapp.com/auth/keys',
+  mode: "client",
+  keyUri: "https://auth.myapp.com/auth/keys",
   logger: pino(),
 });
 ```
@@ -648,7 +882,7 @@ By default every log entry contains `"service": "sentri"`. Override it with `log
 const auth = createAuth({
   // ...
   logger: pino(),
-  loggerService: 'auth-service',
+  loggerService: "auth-service",
 });
 ```
 
@@ -657,17 +891,18 @@ const auth = createAuth({
 If you mount a request-ID middleware **before** Sentri, the `requestId` is automatically included in every log entry for that request:
 
 ```typescript
-import { randomUUID } from 'crypto';
+import { randomUUID } from "crypto";
 
 app.use((req, _res, next) => {
   req.requestId = randomUUID();
   next();
 });
 
-app.use('/auth', auth.router());
+app.use("/auth", auth.router());
 ```
 
 Sample pino output:
+
 ```json
 {"level":30,"time":1719484800000,"service":"sentri","event":"auth.login.success","userId":"usr_abc","duration_ms":42,"requestId":"d4e5f6"}
 {"level":40,"time":1719484801000,"service":"sentri","event":"auth.authorize.denied","userId":"usr_abc","userRoles":["user"],"requiredRoles":["admin"],"requestId":"d4e5f7"}
@@ -675,47 +910,52 @@ Sample pino output:
 
 ### Log events
 
-| Event | Level | Emitted by | Key fields |
-|-------|-------|------------|-----------|
-| `auth.protect.success` | info | `protect()` | `userId`, `mode` |
-| `auth.protect.failure` | warn | `protect()` | `errorCode`, `mode` |
-| `auth.protect.token_revoked` | warn | `protect()` | `userId`, `mode` |
-| `auth.protect.auto_refresh` | info | `protect()` | `userId`, `mode` |
-| `auth.authorize.passed` | info | `authorize()` | `userId`, `userRoles`, `requiredRoles` |
-| `auth.authorize.denied` | warn | `authorize()` | `userId`, `userRoles`, `requiredRoles` |
-| `auth.authorize.unauthenticated` | warn | `authorize()` | `requiredRoles` |
-| `auth.permit.passed` | info | `permit()` | `userId` |
-| `auth.permit.denied` | warn | `permit()` | `userId` |
-| `auth.permit.role_bypass` | info | `permit()` | `userId`, `bypassedByRole` |
-| `auth.permit.unauthenticated` | warn | `permit()` | — |
-| `auth.register.success` | info | router | `userId`, `duration_ms` |
-| `auth.register.failure` | warn | router | `errorCode`, `duration_ms` |
-| `auth.login.success` | info | router | `userId`, `duration_ms` |
-| `auth.login.failure` | warn | router | `errorCode`, `duration_ms` |
-| `auth.refresh.success` | info | router | `userId`, `duration_ms` |
-| `auth.refresh.failure` | warn | router | `errorCode`, `duration_ms` |
-| `auth.logout` | info | router | `duration_ms` |
-| `auth.logout_all` | info | router | `userId`, `duration_ms` |
-| `auth.password.changed` | info | router | `userId`, `duration_ms` |
-| `auth.password.change_failure` | warn | router | `userId`, `errorCode`, `duration_ms` |
-| `auth.roles.assigned` | info | router | `targetUserId`, `roles`, `duration_ms` |
-| `auth.roles.assign_failure` | warn | router | `targetUserId`, `errorCode`, `duration_ms` |
-| `auth.identifiers.created` | info | router | `userId`, `count`, `duration_ms` |
-| `auth.identifiers.updated` | info | router | `userId`, `count`, `duration_ms` |
-| `auth.identifiers.deleted` | info | router | `userId`, `duration_ms` |
-| `auth.identifiers.primary_changed` | info | router | `userId`, `duration_ms` |
+| Event                            | Level | Emitted by    | Key fields                                 |
+| -------------------------------- | ----- | ------------- | ------------------------------------------ |
+| `auth.protect.success`           | info  | `protect()`   | `userId`, `mode`                           |
+| `auth.protect.failure`           | warn  | `protect()`   | `errorCode`, `mode`                        |
+| `auth.protect.token_revoked`     | warn  | `protect()`   | `userId`, `mode`                           |
+| `auth.protect.auto_refresh`      | info  | `protect()`   | `userId`, `mode`                           |
+| `auth.authorize.passed`          | info  | `authorize()` | `userId`, `userRoles`, `requiredRoles`     |
+| `auth.authorize.denied`          | warn  | `authorize()` | `userId`, `userRoles`, `requiredRoles`     |
+| `auth.authorize.unauthenticated` | warn  | `authorize()` | `requiredRoles`                            |
+| `auth.permit.passed`             | info  | `permit()`    | `userId`                                   |
+| `auth.permit.denied`             | warn  | `permit()`    | `userId`                                   |
+| `auth.permit.role_bypass`        | info  | `permit()`    | `userId`, `bypassedByRole`                 |
+| `auth.permit.unauthenticated`    | warn  | `permit()`    | —                                          |
+| `auth.register.success`          | info  | router        | `userId`, `duration_ms`                    |
+| `auth.register.failure`          | warn  | router        | `errorCode`, `duration_ms`                 |
+| `auth.login.success`             | info  | router        | `userId`, `duration_ms`                    |
+| `auth.login.failure`             | warn  | router        | `errorCode`, `duration_ms`                 |
+| `auth.refresh.success`           | info  | router        | `userId`, `duration_ms`                    |
+| `auth.refresh.failure`           | warn  | router        | `errorCode`, `duration_ms`                 |
+| `auth.logout`                    | info  | router        | `duration_ms`                              |
+| `auth.logout_all`                | info  | router        | `userId`, `duration_ms`                    |
+| `auth.password.changed`          | info  | router        | `userId`, `duration_ms`                    |
+| `auth.password.change_failure`   | warn  | router        | `userId`, `errorCode`, `duration_ms`       |
+| `auth.roles.assigned`            | info  | router        | `targetUserId`, `roles`, `duration_ms`     |
+| `auth.roles.assign_failure`      | warn  | router        | `targetUserId`, `errorCode`, `duration_ms` |
+| `auth.identifiers.created`       | info  | router        | `userId`, `count`, `duration_ms`           |
+| `auth.identifiers.updated`       | info  | router        | `userId`, `count`, `duration_ms`           |
+| `auth.identifiers.deleted`       | info  | router        | `userId`, `duration_ms`                    |
 
 All entries include `service` (configurable via `loggerService`) and `requestId` when available.
 
 ### `SentriLogger` interface
 
 ```typescript
-import type { SentriLogger } from 'sentri';
+import type { SentriLogger } from "sentri";
 
 const myLogger: SentriLogger = {
-  info(data: Record<string, unknown>) { /* ... */ },
-  warn(data: Record<string, unknown>) { /* ... */ },
-  error(data: Record<string, unknown>) { /* ... */ },
+  info(data: Record<string, unknown>) {
+    /* ... */
+  },
+  warn(data: Record<string, unknown>) {
+    /* ... */
+  },
+  error(data: Record<string, unknown>) {
+    /* ... */
+  },
 };
 ```
 
@@ -723,26 +963,37 @@ const myLogger: SentriLogger = {
 
 ## Migration Guide
 
+### 5.0.0 Breaking Changes
+
+| What changed                                                   | Action required                                                        |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `is_primary` column removed from `sentri_identifiers`          | Drop and recreate tables — run `auth.migrate()` after                  |
+| `AuthUser` no longer has `identifier` / `identifierType`       | Update any code reading `req.user` — shape is now `{ id, roles }`      |
+| JWT payload no longer includes `identifier` / `identifierType` | Any code decoding the token directly must drop these fields            |
+| `PATCH /me/identifiers/primary` endpoint removed               | No replacement — the concept of primary is gone                        |
+| `changePrimaryIdentifier()` removed from `ServerAuthClient`    | Delete call sites                                                      |
+| `ChangePrimaryResult` type removed                             | Delete references from type imports                                    |
+| `bulkDeleteIdentifiers` guard changed                          | Old: "cannot delete primary". New: "must keep at least one identifier" |
+
 ### 4.0.0 Breaking Changes
 
-| What changed | Action required |
-|---|---|
-| `sentri_users` no longer has an `identifier` column | Drop and recreate tables — identities now live in `sentri_identifiers` |
-| New `sentri_identifiers` table | Created automatically by `auth.migrate()` |
-| `RegisterInput.identifier` → `RegisterInput.identifiers` (array) | Update register calls to pass `identifiers: [{ type, value }]` |
-| `AuthUser` now includes `identifierType` | Update any code reading `req.user` to expect this new field |
-| `PATCH /me/identifier` removed | Use `PUT /me/identifiers` for updates, `PATCH /me/identifiers/primary` for primary change |
-| `changeIdentifier()` removed from `ServerAuthClient` | Use `bulkUpdateIdentifiers()` or `changePrimaryIdentifier()` |
-| New error codes: `IDENTIFIER_NOT_FOUND`, `IDENTIFIER_ALREADY_EXISTS` | Handle these in your error handlers as needed |
+| What changed                                                         | Action required                                                        |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `sentri_users` no longer has an `identifier` column                  | Drop and recreate tables — identities now live in `sentri_identifiers` |
+| New `sentri_identifiers` table                                       | Created automatically by `auth.migrate()`                              |
+| `RegisterInput.identifier` → `RegisterInput.identifiers` (array)     | Update register calls to pass `identifiers: [{ type, value }]`         |
+| `PATCH /me/identifier` removed                                       | Use `PUT /me/identifiers` for updates                                  |
+| `changeIdentifier()` removed from `ServerAuthClient`                 | Use `bulkUpdateIdentifiers()`                                          |
+| New error codes: `IDENTIFIER_NOT_FOUND`, `IDENTIFIER_ALREADY_EXISTS` | Handle these in your error handlers as needed                          |
 
 ### 3.0.0 Breaking Changes
 
-| What changed | Action required |
-|---|---|
-| `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 |
+| What changed                                                   | Action required                                        |
+| -------------------------------------------------------------- | ------------------------------------------------------ |
+| `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                                       |