sentri 1.0.4 → 1.0.5

package/README.md

@@ -1,1044 +1,448 @@
 # sentri
 
-Library autentikasi dan otorisasi personal untuk Express + PostgreSQL. ORM-agnostic — kamu implementasi adapter database sendiri sesuai ORM yang dipakai.
-
-## Fitur
-
-- **Flexible identifier** — email, username, nomor HP, atau string unik apapun
-- **Access token + refresh token** dari satu secret; dirotasi otomatis setiap refresh
-- **Session-based revocation** — logout instan tanpa token blacklist
-- **Multi-role** dengan type safety compile-time via TypeScript generics
-- **Tiga lapis middleware**: `protect` (autentikasi) → `authorize` (role) → `permit` (kepemilikan resource)
-- **Built-in router** — 6 endpoint auth siap pakai tanpa boilerplate
-- **Cookie mode** — refresh token otomatis disimpan di httpOnly cookie, tanpa `cookie-parser`
-- **ORM-agnostic** — satu interface, bisa diimplementasi dengan Prisma, Drizzle, raw SQL, apapun
+Auth and authorization library for Express + PostgreSQL. Provides JWT-based authentication with refresh token rotation, role-based access control, fine-grained permission checks, and a pre-built Express router — all behind a single typed client.
 
 ---
 
-## Daftar Isi
-
-1. [Instalasi](#instalasi)
-2. [Cara Kerja](#cara-kerja)
-3. [Setup Lengkap dari Nol](#setup-lengkap-dari-nol)
-4. [Contoh HTTP Request & Response](#contoh-http-request--response)
-5. [Middleware](#middleware)
-6. [Custom Routes](#custom-routes)
-7. [Cookie Mode](#cookie-mode)
-8. [Identifier Fleksibel](#identifier-fleksibel)
-9. [Konfigurasi](#konfigurasi)
-10. [AuthAdapter Interface](#authadapter-interface)
-11. [Error Handling](#error-handling)
-12. [Type Exports](#type-exports)
-13. [Keamanan](#keamanan)
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI](#cli)
+- [Configuration](#configuration)
+- [Adapter Interface](#adapter-interface)
+- [Pre-built Router](#pre-built-router)
+- [Middleware](#middleware)
+- [Programmatic API](#programmatic-api)
+- [Types](#types)
+- [Error Handling](#error-handling)
 
 ---
 
-## Instalasi
+## Installation
 
 ```bash
-npm install sentri express
-npm install -D @types/express typescript
+npm install sentri
 ```
 
+**Peer dependency:** `express >= 4.0.0`
+
 ---
 
-## Cara Kerja
+## Quick Start
 
-Sebelum mulai, penting memahami dua konsep utama:
+### 1. Generate templates
 
-### Dua token, satu secret
+```bash
+# Prisma
+npx sentri generate prisma
 
+# Drizzle
+npx sentri generate drizzle
 ```
-secret  ──→  secret:access   → sign access token  (pendek, 15 menit)
-        └──→  secret:refresh  → sign refresh token (panjang, 7 hari)
-```
-
-Kamu hanya perlu simpan satu `secret`. Library otomatis membuat dua derived key terpisah.
 
-### Access token vs Refresh token
+This creates:
 
-| | Access Token | Refresh Token |
-|---|---|---|
-| **Isi JWT** | `{ id, identifier, roles }` | `{ sessionId }` |
-| **Default expire** | 15 menit | 7 hari |
-| **Dipakai untuk** | Akses endpoint protected | Minta access token baru |
-| **Disimpan di** | Memory / header | Storage yang lebih aman |
+```
+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)
+```
 
-### Session-based revocation
+### 2. Mount the router
 
-Refresh token tidak menyimpan data user — hanya `sessionId`. Saat dipakai, library cek session tersebut masih ada di DB. Jika sudah dihapus (logout), token otomatis tidak berlaku tanpa perlu blacklist.
+```typescript
+import express from 'express';
+import { auth } from './lib/sentri/auth.js';
 
-```
-Login  →  buat session di DB  →  refresh token berisi sessionId
-Logout →  hapus session di DB →  refresh token langsung tidak berlaku
+const app = express();
+app.use(express.json());
+app.use('/auth', auth.router());
 ```
 
+Done. All endpoints are available at `/auth/*`.
+
 ---
 
-## Setup Lengkap dari Nol
+## CLI
 
-### Langkah 1: Struktur project
+### `sentri generate <prisma|drizzle>`
 
-```
-src/
-├── index.ts          ← Express app utama
-├── lib/
-│   ├── auth.ts       ← createAuth() dipanggil di sini
-│   ├── adapter.ts    ← implementasi AuthAdapter
-│   └── prisma.ts     ← inisialisasi PrismaClient
-└── routes/
-    └── user.ts       ← contoh protected routes
-```
-
-### Langkah 2: Siapkan environment
+Generates adapter, auth config, and schema templates in one command.
 
 ```bash
-# .env
-DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
-JWT_SECRET="ganti-dengan-string-acak-minimal-32-karakter-ini"
-PORT=3000
+npx sentri generate prisma
+npx sentri generate drizzle
 ```
 
-> **Penting:** `JWT_SECRET` harus minimal 32 karakter. `createAuth()` akan throw `CONFIGURATION_ERROR` jika kurang dari itu.
-
-### Langkah 3: Siapkan tabel database
+**What gets created:**
 
-Library membutuhkan empat tabel: **User**, **Role**, **UserRole**, dan **Session**.
-
-**Contoh Prisma schema** (`prisma/schema.prisma`):
+| 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 |
 
-```prisma
-generator client {
-  provider = "prisma-client-js"
-}
+---
 
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
+## Configuration
 
-model User {
-  id           String     @id @default(cuid())
-  email        String     @unique
-  passwordHash String
-  createdAt    DateTime   @default(now())
-  updatedAt    DateTime   @updatedAt
-  userRoles    UserRole[]
-  sessions     Session[]
-}
-
-model Role {
-  id        String     @id @default(cuid())
-  name      String     @unique
-  userRoles UserRole[]
-}
+```typescript
+import { createAuth } from 'sentri';
 
-model UserRole {
-  userId String
-  roleId String
-  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
-  role   Role   @relation(fields: [roleId], references: [id], onDelete: Cascade)
+export const auth = createAuth({
+  secret: process.env.JWT_SECRET!,        // required — keep in env
+  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)
+
+  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: '/'
+  },
+});
+```
 
-  @@id([userId, roleId])
-}
+`accessExpiresIn` and `refreshExpiresIn` accept duration strings (`'15m'`, `'1h'`, `'7d'`, `'30d'`) or seconds as a number.
 
-model Session {
-  id        String   @id @default(cuid())
-  userId    String
-  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
-  expiresAt DateTime
-  createdAt DateTime @default(now())
-}
-```
+When `cookie` is configured, the refresh token is stored in an httpOnly cookie automatically. No `cookie-parser` middleware is needed.
 
-```bash
-npx prisma db push   # atau prisma migrate dev
-npx prisma generate
-```
+---
 
-### Langkah 4: Buat adapter
+## Adapter Interface
 
-Adapter adalah jembatan antara library dan database kamu. Library mendefinisikan interface-nya, kamu mengisi implementasinya.
+The adapter connects sentri to your database. Implement `AuthAdapter` for any ORM or data layer.
 
 ```typescript
-// src/lib/adapter.ts
 import type { AuthAdapter } from 'sentri';
-import { prisma } from './prisma.js';
-
-// Helper: ubah format row DB ke format yang diharapkan library
-function toUserRecord(raw: {
-  id: string;
-  email: string;
-  passwordHash: string;
-  userRoles: { role: { name: string } }[];
-}) {
-  return {
-    id: raw.id,
-    identifier: raw.email,     // kolom "email" di DB → "identifier" di library
-    passwordHash: raw.passwordHash,
-    roles: raw.userRoles.map((ur) => ur.role.name),
-  };
-}
 
-export const adapter: AuthAdapter = {
+const adapter: AuthAdapter = {
   user: {
-    // Dipanggil saat login — cari user berdasarkan identifier
-    async findByIdentifier(identifier) {
-      const raw = await prisma.user.findUnique({
-        where: { email: identifier },
-        include: { userRoles: { include: { role: true } } },
-      });
-      return raw ? toUserRecord(raw) : null;
-    },
-
-    // Dipanggil saat validasi token
-    async findById(id) {
-      const raw = await prisma.user.findUnique({
-        where: { id },
-        include: { userRoles: { include: { role: true } } },
-      });
-      return raw ? toUserRecord(raw) : null;
-    },
-
-    // Dipanggil saat signup
-    async create({ identifier, passwordHash, roles }) {
-      const user = await prisma.user.create({ data: { email: identifier, passwordHash } });
-
-      if (roles.length > 0) {
-        // Upsert role agar tidak perlu seed manual
-        const roleRecords = await Promise.all(
-          roles.map((name) =>
-            prisma.role.upsert({ where: { name }, create: { name }, update: {} }),
-          ),
-        );
-        await prisma.userRole.createMany({
-          data: roleRecords.map((r) => ({ userId: user.id, roleId: r.id })),
-        });
-      }
-
-      return { id: user.id };
-    },
+    findByIdentifier(identifier: string): Promise<UserRecord | null>,
+    findById(id: string): Promise<UserRecord | null>,
+    create(data: CreateUserData): Promise<{ id: string }>,
+    updateRoles(userId: string, roles: string[]): Promise<void>,
   },
-
   session: {
-    // Dipanggil setelah login/signup berhasil
-    async create({ userId, expiresAt }) {
-      const session = await prisma.session.create({ data: { userId, expiresAt } });
-      return { id: session.id };
-    },
-
-    // Dipanggil saat refresh token — ambil session + data user
-    async findById(sessionId) {
-      const raw = await prisma.session.findUnique({
-        where: { id: sessionId },
-        include: { user: { include: { userRoles: { include: { role: true } } } } },
-      });
-      if (!raw) return null;
-      return {
-        id: raw.id,
-        userId: raw.userId,
-        expiresAt: raw.expiresAt,
-        createdAt: raw.createdAt,
-        user: toUserRecord(raw.user),
-      };
-    },
-
-    // Dipanggil saat logout atau rotasi token
-    async delete(sessionId) {
-      await prisma.session.delete({ where: { id: sessionId } });
-    },
-
-    // Dipanggil saat logout-all
-    async deleteAllForUser(userId) {
-      await prisma.session.deleteMany({ where: { userId } });
-    },
+    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>,
   },
 };
 ```
 
-### Langkah 5: Buat auth client
+`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.
 
-```typescript
-// src/lib/auth.ts
-import { createAuth } from 'sentri';
-import { adapter } from './adapter.js';
-
-// Definisikan role yang ada di aplikasimu
-export type AppRole = 'user' | 'admin' | 'moderator';
-
-export const auth = createAuth<AppRole>({
-  secret: process.env.JWT_SECRET!,
-  validRoles: ['user', 'admin', 'moderator'],
-  adapter,
-  // Semua di bawah ini opsional, nilai berikut adalah default:
-  // accessExpiresIn:  '15m',
-  // refreshExpiresIn: '7d',
-  // saltRounds:       12,
-  // algorithm:        'HS256',
-});
-```
+### Using the generated adapter
 
-Setelah ini, TypeScript tahu persis role apa yang valid. `auth.authorize('superuser')` adalah **compile error**.
-
-### Langkah 6: Pasang di Express
+The generated `adapter.ts` exports `createAdapter(db)` so you can pass your existing database instance:
 
 ```typescript
-// src/index.ts
-import 'dotenv/config';
-import express from 'express';
-import { AuthError } from 'sentri';
-import { auth } from './lib/auth.js';
-import { userRouter } from './routes/user.js';
-import { prisma } from './lib/prisma.js';
+// Prisma
+import { PrismaClient } from '@prisma/client';
+import { createAdapter } from './adapter.js';
 
-const app = express();
+const prisma = new PrismaClient();
+export const adapter = createAdapter(prisma);
 
-// express.json() WAJIB dipasang sebelum auth.router()
-app.use(express.json());
-
-// 6 endpoint auth langsung jadi — tidak perlu tulis manual
-app.use('/auth', auth.router());
-
-// Route lain milikmu
-app.use('/user', userRouter);
+// Drizzle
+import { db } from '../db.js';
+import { createAdapter } from './adapter.js';
 
-// Error handler global — tangkap AuthError dari semua middleware
-app.use((
-  err: unknown,
-  _req: express.Request,
-  res: express.Response,
-  _next: express.NextFunction,
-) => {
-  if (err instanceof AuthError) {
-    const status =
-      err.code === 'UNAUTHORIZED' ? 401 :
-      err.code === 'FORBIDDEN'    ? 403 : 400;
-    res.status(status).json({ code: err.code, message: err.message });
-    return;
-  }
-  console.error(err);
-  res.status(500).json({ message: 'Internal server error' });
-});
-
-const port = Number(process.env.PORT ?? 3000);
-app.listen(port, () => console.log(`Server running on http://localhost:${port}`));
-
-process.on('SIGINT', async () => {
-  await prisma.$disconnect();
-  process.exit(0);
-});
+export const adapter = createAdapter(db);
 ```
 
-### Langkah 7: Buat protected routes
-
-```typescript
-// src/routes/user.ts
-import { Router } from 'express';
-import { auth } from '../lib/auth.js';
-
-export const userRouter = Router();
-
-// Hanya user yang sudah login
-userRouter.get('/me', auth.protect(), (req, res) => {
-  res.json(req.user); // { id, identifier, roles }
-});
-
-// Hanya admin
-userRouter.get('/admin-only',
-  auth.protect(),
-  auth.authorize('admin'),
-  (req, res) => res.json({ message: 'selamat datang admin' }),
-);
-
-// Admin atau moderator
-userRouter.get('/dashboard',
-  auth.protect(),
-  auth.authorize('admin', 'moderator'),
-  (req, res) => res.json({ message: 'selamat datang di dashboard' }),
-);
-
-// User hanya bisa edit profilnya sendiri; admin bisa edit siapapun
-userRouter.put('/:userId',
-  auth.protect(),
-  auth.permit({
-    roles: ['admin'],
-    check: (req) => req.user!.id === req.params['userId'],
-  }),
-  (req, res) => res.json({ message: `profil ${req.params['userId']} diperbarui` }),
-);
-```
+`createAdapter` throws an `AdapterConfigError` at runtime if called without a `db` argument.
 
 ---
 
-## Contoh HTTP Request & Response
+## Pre-built Router
 
-Gunakan `curl`, Postman, atau HTTP client lain. Semua request body harus JSON.
-
-### Signup
-
-```bash
-curl -X POST http://localhost:3000/auth/signup \
-  -H "Content-Type: application/json" \
-  -d '{ "identifier": "alice@example.com", "password": "password123", "roles": ["user"] }'
-```
+`auth.router()` returns an Express Router with all standard endpoints. Every response uses this envelope:
 
-```json
-// 201 Created
+```typescript
 {
-  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "user": {
-    "id": "clx1234abcd",
-    "identifier": "alice@example.com",
-    "roles": ["user"]
-  }
+  error: boolean,
+  statusCode: number,
+  message: string,
+  data: T | null
 }
 ```
 
-```json
-// 409 Conflict — identifier sudah terdaftar
-{ "code": "USER_ALREADY_EXISTS", "message": "User already exists" }
-```
+### Endpoints
 
-```json
-// 400 Bad Request — role tidak ada di validRoles
-{ "code": "INVALID_ROLE", "message": "Invalid roles: superuser" }
-```
+#### `POST /signup`
 
-### Login
+Register a new user. Does **not** issue tokens — call `/login` after signup.
 
-```bash
-curl -X POST http://localhost:3000/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{ "identifier": "alice@example.com", "password": "password123" }'
 ```
-
-```json
-// 200 OK
-{
-  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "user": {
-    "id": "clx1234abcd",
-    "identifier": "alice@example.com",
-    "roles": ["user"]
-  }
-}
+Body:    { identifier, password, roles?: string[] }
+Returns: { user: { id, identifier, roles } }
+Status:  201
 ```
 
-```json
-// 401 Unauthorized — identifier atau password salah
-{ "code": "INVALID_CREDENTIALS", "message": "Invalid credentials" }
-```
+`password` must be 8–72 characters. `roles` must be a subset of `validRoles`.
 
-### Akses endpoint protected
+---
 
-Kirim `accessToken` di header `Authorization`:
+#### `POST /login`
 
-```bash
-curl http://localhost:3000/user/me \
-  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-```
+Authenticate a user and start a session.
 
-```json
-// 200 OK
-{ "id": "clx1234abcd", "identifier": "alice@example.com", "roles": ["user"] }
 ```
-
-```json
-// 401 Unauthorized — token tidak ada atau tidak valid
-{ "code": "UNAUTHORIZED", "message": "Missing or malformed Authorization header" }
+Body:    { identifier, password }
+Returns: { accessToken, user: { id, identifier, roles } }
+Status:  200
 ```
 
-```json
-// 401 Unauthorized — token sudah expire
-{ "code": "TOKEN_EXPIRED", "message": "Token has expired" }
-```
+The refresh token is stored in an httpOnly cookie. The access token is returned in the response body.
 
-```json
-// 403 Forbidden — tidak punya role yang dibutuhkan
-{ "code": "FORBIDDEN", "message": "Requires one of roles: admin" }
-```
+---
 
-### Refresh token
+#### `POST /refresh`
 
-Access token expire setelah 15 menit. Gunakan refresh token untuk minta yang baru **tanpa login ulang**. Setelah refresh, refresh token lama **tidak berlaku lagi** (rotasi).
+Exchange the refresh token cookie for a new access token. Implements session rotation — the old session is deleted and a new one is created.
 
-```bash
-curl -X POST http://localhost:3000/auth/refresh \
-  -H "Content-Type: application/json" \
-  -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'
 ```
-
-```json
-// 200 OK — simpan kedua token baru, buang yang lama
-{
-  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-}
+Cookie:  refresh_token=<token>   (set automatically by /login)
+Returns: { accessToken }
+Status:  200
 ```
 
-```json
-// 401 Unauthorized — refresh token sudah dipakai / session di-logout
-{ "code": "UNAUTHORIZED", "message": "Session not found or revoked" }
-```
+The new refresh token is written back to the cookie. No body required.
 
-### Logout
+---
 
-Hapus session saat ini. Refresh token yang terkait langsung tidak berlaku.
+#### `POST /logout`
 
-```bash
-curl -X POST http://localhost:3000/auth/logout \
-  -H "Content-Type: application/json" \
-  -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'
-```
+Invalidate the current session.
 
-```json
-// 200 OK
-{ "message": "logged out" }
+```
+Cookie:  refresh_token=<token>
+Returns: null
+Status:  200
 ```
 
-### Logout semua device
+Safe to call even if the cookie is missing or the token is already expired.
 
-Perlu access token yang valid. Menghapus semua session user — efektif logout dari semua device sekaligus.
+---
 
-```bash
-curl -X POST http://localhost:3000/auth/logout-all \
-  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-```
+#### `POST /logout-all`
+
+Invalidate all sessions for the authenticated user (logout from every device).
 
-```json
-// 200 OK
-{ "message": "all sessions revoked" }
+```
+Headers: Authorization: Bearer <accessToken>
+Returns: null
+Status:  200
 ```
 
-### Cek user saat ini
+---
 
-Mengembalikan data user yang sedang login berdasarkan access token. Endpoint ini membutuhkan access token yang valid.
+#### `GET /me`
 
-```bash
-curl http://localhost:3000/auth/me \
-  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-```
+Return the currently authenticated user.
 
-```json
-// 200 OK
-{
-  "id": "clx1234abcd",
-  "identifier": "alice@example.com",
-  "roles": ["user"]
-}
 ```
-
-```json
-// 401 Unauthorized — token tidak ada atau tidak valid
-{ "code": "UNAUTHORIZED", "message": "Missing or malformed Authorization header" }
+Headers: Authorization: Bearer <accessToken>
+Returns: { id, identifier, roles }
+Status:  200
 ```
 
 ---
 
-## Middleware
+#### `POST /users/:userId/roles`
 
-Library menyediakan tiga middleware yang bisa dikombinasikan:
+Add roles to another user. Restricted to users with the `admin` role. Merges the given roles with the user's existing roles — no duplicates.
 
 ```
-protect()    → autentikasi: siapa yang request?
-authorize()  → otorisasi role: role apa yang boleh?
-permit()     → otorisasi resource: boleh akses data ini?
+Headers: Authorization: Bearer <accessToken>   (must have admin role)
+Body:    { roles: string[] }
+Returns: { user: { id, identifier, roles } }
+Status:  200
 ```
 
-Ketiganya bekerja seperti rantai. `authorize` dan `permit` selalu dipasang **setelah** `protect`.
+---
+
+## Middleware
 
 ### `auth.protect()`
 
-Verifikasi access token dari header `Authorization: Bearer <token>`. Jika valid, `req.user` tersedia di handler berikutnya.
+Verifies the `Authorization: Bearer <token>` header and injects `req.user` into the request.
 
 ```typescript
-router.get('/profile', auth.protect(), (req, res) => {
-  // req.user dijamin ada dan bertipe AuthUser<AppRole>
-  res.json({
-    id: req.user!.id,
-    identifier: req.user!.identifier,
-    roles: req.user!.roles,
-  });
+router.get('/dashboard', auth.protect(), (req, res) => {
+  res.json(req.user); // { id, identifier, roles }
 });
 ```
 
+---
+
 ### `auth.authorize(...roles)`
 
-Cek apakah user punya minimal satu dari role yang disebutkan.
+Enforces role-based access. Must be used **after** `auth.protect()`. Passes if the user has at least one of the specified roles.
 
 ```typescript
-// Satu role
-router.post('/posts', auth.protect(), auth.authorize('admin'), createPost);
-
-// Beberapa role — user cukup punya salah satu
-router.put('/posts/:id', auth.protect(), auth.authorize('admin', 'moderator'), updatePost);
+router.delete(
+  '/posts/:id',
+  auth.protect(),
+  auth.authorize('admin'),
+  handler,
+);
 ```
 
-### `auth.permit(check | options)`
+---
 
-Cek kepemilikan resource atau kondisi apapun yang butuh data dari request. Cocok untuk aturan seperti "hanya pemilik yang bisa edit".
+### `auth.permit(check | options)`
 
-**Bentuk 1 — fungsi check saja:**
+Resource-level permission check. Must be used **after** `auth.protect()`. Return `true` to allow, `false` to deny.
 
 ```typescript
-// User hanya bisa akses data miliknya sendiri
-router.get('/orders/:orderId',
+// Simple ownership check
+router.put(
+  '/users/:id',
   auth.protect(),
-  auth.permit(async (req) => {
-    const order = await db.order.findUnique({ where: { id: req.params['orderId'] } });
-    return order?.userId === req.user!.id;
-  }),
-  getOrderHandler,
+  auth.permit((request) => request.user!.id === request.params['id']),
+  handler,
 );
-```
-
-**Bentuk 2 — dengan role bypass:**
 
-```typescript
-// Admin bisa akses semua; user biasa hanya miliknya
-router.delete('/orders/:orderId',
+// Admins bypass the check; others must own the resource
+router.delete(
+  '/posts/:id',
   auth.protect(),
   auth.permit({
-    roles: ['admin'],                     // admin selalu lolos, skip check
-    check: async (req) => {
-      const order = await db.order.findUnique({ where: { id: req.params['orderId'] } });
-      return order?.userId === req.user!.id;
-    },
-  }),
-  deleteOrderHandler,
-);
-```
-
-**Contoh kombinasi lengkap:**
-
-```typescript
-// Hanya user dengan role 'editor' atau 'admin' yang bisa akses,
-// dan hanya jika artikel milik mereka (kecuali admin)
-router.put('/articles/:id',
-  auth.protect(),                          // 1. harus login
-  auth.authorize('editor', 'admin'),       // 2. harus punya role
-  auth.permit({                            // 3. admin bebas, editor harus pemilik
     roles: ['admin'],
-    check: async (req) => {
-      const article = await db.article.findUnique({ where: { id: req.params['id'] } });
-      return article?.authorId === req.user!.id;
+    check: async (request) => {
+      const post = await db.post.findUnique({ where: { id: request.params['id'] } });
+      return post?.authorId === request.user!.id;
     },
   }),
-  updateArticleHandler,
+  handler,
 );
 ```
 
 ---
 
-## Custom Routes
+## Programmatic API
 
-Jika `auth.router()` tidak sesuai kebutuhan, kamu bisa tulis route sendiri menggunakan method `auth.signup()`, `auth.login()`, dll secara langsung.
+All methods are available on the auth client for use outside the built-in router.
 
 ```typescript
-import { Router } from 'express';
-import { auth } from '../lib/auth.js';
-
-const router = Router();
-
-// Contoh: signup dengan response yang dikustomisasi
-router.post('/register', async (req, res, next) => {
-  try {
-    const result = await auth.signup({
-      identifier: req.body.email,
-      password: req.body.password,
-      roles: ['user'], // selalu assign role 'user' saat register
-    });
-
-    if (!result.success) {
-      // Kamu bebas tentukan status code dan format response
-      const status = result.error.code === 'USER_ALREADY_EXISTS' ? 409 : 400;
-      return res.status(status).json({ error: result.error.code });
-    }
-
-    // Contoh: kirim token lewat cookie, bukan body
-    res.cookie('refreshToken', result.refreshToken, {
-      httpOnly: true,
-      secure: process.env.NODE_ENV === 'production',
-      maxAge: 7 * 24 * 60 * 60 * 1000, // 7 hari
-    });
-
-    res.status(201).json({
-      accessToken: result.accessToken,
-      user: result.user,
-    });
-  } catch (err) {
-    next(err);
-  }
-});
+// Auth
+const result = await auth.signup({ identifier: 'user@example.com', password: 'secret123' });
+const result = await auth.login({ identifier: 'user@example.com', password: 'secret123' });
+const result = await auth.refresh(refreshToken);
+await auth.logout(refreshToken);
+await auth.logoutAll(userId);
 
-// Contoh: refresh token dari cookie (bukan body)
-router.post('/token', async (req, res, next) => {
-  try {
-    const refreshToken = req.cookies['refreshToken'] as string | undefined;
-    if (!refreshToken) return res.status(401).json({ error: 'UNAUTHORIZED' });
+// Roles
+const result = await auth.assignRoles(userId, ['admin']);
+// Merges with existing roles — result.user.roles has the full updated list
 
-    const result = await auth.refresh(refreshToken);
-    if (!result.success) return res.status(401).json({ error: result.error.code });
+// 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
 
-    res.cookie('refreshToken', result.refreshToken, { httpOnly: true, secure: true });
-    res.json({ accessToken: result.accessToken });
-  } catch (err) {
-    next(err);
-  }
-});
+// Password utilities
+const hash = await auth.hashPassword('secret123');
+const valid = await auth.verifyPassword('secret123', hash);
 ```
 
----
-
-## Cookie Mode
-
-Secara default, built-in router mengembalikan refresh token di response body. Jika kamu ingin menyimpannya di **httpOnly cookie** (lebih aman karena tidak bisa diakses JavaScript), cukup tambah field `cookie` di config:
+All auth methods return a discriminated union — check `result.success` before accessing data:
 
 ```typescript
-// src/lib/auth.ts
-export const auth = createAuth<AppRole>({
-  secret: process.env.JWT_SECRET!,
-  validRoles: ['user', 'admin', 'moderator'],
-  adapter,
-  cookie: {
-    secure: process.env.NODE_ENV === 'production', // true di production (HTTPS only)
-  },
-});
-```
-
-Tidak ada `cookie-parser` yang diperlukan — library membaca header `Cookie` secara langsung.
-
-### Perubahan behavior di cookie mode
-
-| Endpoint | Default (body) | Cookie mode |
-|---|---|---|
-| `POST /signup` | Response berisi `refreshToken` | Cookie `refresh_token` di-set, `refreshToken` tidak ada di response |
-| `POST /login` | Response berisi `refreshToken` | Cookie `refresh_token` di-set, `refreshToken` tidak ada di response |
-| `POST /refresh` | Body harus berisi `refreshToken` | Cookie dibaca otomatis, cookie baru di-set |
-| `POST /logout` | Body harus berisi `refreshToken` | Cookie dibaca otomatis, cookie dihapus |
-| `POST /logout-all` | Cookie dihapus (jika ada) | Cookie dihapus |
-| `GET /me` | Tidak terpengaruh cookie mode | Tidak terpengaruh cookie mode |
-
-### Contoh curl dengan cookie
+const result = await auth.login({ identifier, password });
 
-Browser mengelola cookie otomatis. Untuk testing manual dengan curl, gunakan flag `-c` (simpan cookie) dan `-b` (kirim cookie):
-
-```bash
-# Login — cookie otomatis disimpan ke file cookies.txt
-curl -c cookies.txt -X POST http://localhost:3000/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{ "identifier": "alice@example.com", "password": "password123" }'
-```
-
-```json
-// Response — tidak ada refreshToken di body
-{
-  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "user": { "id": "clx1234abcd", "identifier": "alice@example.com", "roles": ["user"] }
+if (!result.success) {
+  console.error(result.error.code);   // 'INVALID_CREDENTIALS'
+  console.error(result.error.message);
+  return;
 }
-```
-
-```bash
-# Refresh — cookie dikirim otomatis dari file cookies.txt
-curl -c cookies.txt -b cookies.txt -X POST http://localhost:3000/auth/refresh
-```
 
-```json
-// Response — access token baru, cookie baru di-set
-{ "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
+const { accessToken, refreshToken, user } = result;
 ```
 
-```bash
-# Logout — cookie dikirim dan dihapus dari server
-curl -c cookies.txt -b cookies.txt -X POST http://localhost:3000/auth/logout
-```
-
-### Opsi cookie lengkap
-
-```typescript
-cookie: {
-  name?: string;                          // nama cookie, default 'refresh_token'
-  httpOnly?: boolean;                     // default true — tidak bisa diakses JavaScript
-  secure?: boolean;                       // default false — set true di production (HTTPS)
-  sameSite?: 'strict' | 'lax' | 'none';  // default 'strict'
-  path?: string;                          // default '/'
-}
-```
-
-> **SameSite recommendation:**
-> - `'strict'` — paling aman, cocok untuk web app yang tidak butuh cross-site auth
-> - `'lax'` — cocok jika frontend dan backend berbeda subdomain
-> - `'none'` — butuh `secure: true`, cocok untuk third-party integrations (SaaS widget, iframe)
-
 ---
 
-## Identifier Fleksibel
-
-Field `identifier` bisa berisi apapun — library tidak peduli formatnya. Adapter yang menentukan apa yang dimaksud "identifier" di database kamu.
-
-### Login dengan email
+## Types
 
 ```typescript
-// adapter.ts
-async findByIdentifier(identifier) {
-  return prisma.user.findUnique({ where: { email: identifier }, ... });
-}
-```
-
-```bash
-curl -X POST /auth/login -d '{ "identifier": "alice@example.com", "password": "..." }'
-```
-
-### Login dengan username
-
-```typescript
-// adapter.ts
-async findByIdentifier(identifier) {
-  return prisma.user.findUnique({ where: { username: identifier }, ... });
-}
-```
-
-```bash
-curl -X POST /auth/login -d '{ "identifier": "alice123", "password": "..." }'
-```
-
-### Login dengan email ATAU username (multi-kolom)
-
-```typescript
-// adapter.ts
-async findByIdentifier(identifier) {
-  // Prisma: cari di kolom email atau username
-  const raw = await prisma.user.findFirst({
-    where: {
-      OR: [{ email: identifier }, { username: identifier }],
-    },
-    include: { userRoles: { include: { role: true } } },
-  });
-  return raw ? toUserRecord(raw) : null;
-}
-```
-
-```bash
-# Bisa pakai email
-curl -X POST /auth/login -d '{ "identifier": "alice@example.com", "password": "..." }'
-
-# Atau username — endpoint sama
-curl -X POST /auth/login -d '{ "identifier": "alice123", "password": "..." }'
-```
-
-### Login dengan nomor HP
-
-```typescript
-async findByIdentifier(identifier) {
-  return prisma.user.findUnique({ where: { phone: identifier }, ... });
-}
-```
-
----
-
-## Konfigurasi
-
-```typescript
-createAuth({
-  // WAJIB
-  secret: string,         // JWT signing secret, min 32 karakter, simpan di env
-  validRoles: TRole[],    // daftar role yang sah di aplikasimu, gunakan as const
-  adapter: AuthAdapter,   // implementasi database
-
-  // OPSIONAL
-  accessExpiresIn?: '15m',    // masa berlaku access token, default '15m'
-  refreshExpiresIn?: '7d',    // masa berlaku refresh token, default '7d'
-  saltRounds?: 12,            // bcrypt cost factor, default 12, min 10 maks 31
-  algorithm?: 'HS256',        // algoritma JWT, default 'HS256'
-
-  // COOKIE MODE (opsional) — simpan refresh token di httpOnly cookie
-  cookie?: {
-    name?: string,                          // nama cookie, default 'refresh_token'
-    httpOnly?: boolean,                     // default true
-    secure?: boolean,                       // default false, set true di production
-    sameSite?: 'strict' | 'lax' | 'none',  // default 'strict'
-    path?: string,                          // default '/'
-  }
-})
-```
-
-**Format `expiresIn`:**
-
-| Format | Arti |
-|---|---|
-| `'30s'` | 30 detik |
-| `'15m'` | 15 menit |
-| `'2h'` | 2 jam |
-| `'7d'` | 7 hari |
-| `'2w'` | 2 minggu |
-| `3600` | 3600 detik (angka = detik) |
-
-Validasi konfigurasi dijalankan saat `createAuth()` dipanggil — kesalahan terdeteksi langsung saat server start, bukan saat request pertama datang.
-
----
-
-## AuthAdapter Interface
-
-Ini adalah kontrak yang harus kamu implementasi. Berisi 7 method:
-
-```typescript
-interface AuthAdapter {
-  user: {
-    findByIdentifier(identifier: string): Promise<UserRecord | null>;
-    findById(id: string): Promise<UserRecord | null>;
-    create(data: CreateUserData): Promise<{ id: string }>;
-  };
-  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>;
-  };
-}
-```
-
-**Type yang terlibat:**
-
-```typescript
-// Yang dikembalikan oleh adapter ke library
-interface UserRecord {
-  id: string;
-  identifier: string;   // email / username / phone — apapun yang kamu pakai
-  passwordHash: string;
-  roles: string[];
-}
-
-interface SessionRecord {
-  id: string;
-  userId: string;
-  expiresAt: Date;
-  createdAt: Date;
-}
+import type {
+  AuthConfig,
+  AuthClient,
+  AuthAdapter,
+  AuthUser,
+  AuthResult,
+  SignupResult,
+  AssignRolesResult,
+  RefreshResult,
+  ApiResponse,
+  SignupInput,
+  LoginInput,
+  UserRecord,
+  SessionRecord,
+  CreateUserData,
+  CookieConfig,
+  PermitCheck,
+  PermitOptions,
+  AuthErrorCode,
+} from 'sentri';
 
-// Yang diterima adapter dari library saat membuat user
-interface CreateUserData {
-  identifier: string;
-  passwordHash: string; // sudah di-hash, jangan hash lagi
-  roles: string[];
-}
+import { AuthError, createAuth } from 'sentri';
 ```
 
 ---
 
 ## Error Handling
 
-Semua error dari library dilempar sebagai instance `AuthError` dan diteruskan via `next(err)`.
+All errors thrown by the library are instances of `AuthError` with a machine-readable `code`:
 
-### Menangkap di error handler global
+| Code | HTTP | Meaning |
+|---|---|---|
+| `INVALID_CREDENTIALS` | 401 | Wrong identifier or password |
+| `USER_ALREADY_EXISTS` | 409 | Signup 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 on the request |
+| `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:
 
 ```typescript
 import { AuthError } from 'sentri';
 
-app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
+app.use((err, req, res, next) => {
   if (err instanceof AuthError) {
-    const statusMap: Partial<Record<typeof err.code, number>> = {
-      UNAUTHORIZED:       401,
-      TOKEN_EXPIRED:      401,
-      TOKEN_INVALID:      401,
-      FORBIDDEN:          403,
-      USER_ALREADY_EXISTS: 409,
-    };
-    const status = statusMap[err.code] ?? 400;
-    res.status(status).json({ code: err.code, message: err.message });
-    return;
+    const status =
+      err.code === 'UNAUTHORIZED' || err.code === 'TOKEN_EXPIRED' || err.code === 'TOKEN_INVALID' || err.code === 'INVALID_CREDENTIALS' ? 401
+      : err.code === 'FORBIDDEN' ? 403
+      : err.code === 'USER_NOT_FOUND' ? 404
+      : err.code === 'USER_ALREADY_EXISTS' ? 409
+      : 400;
+
+    return res.status(status).json({ error: true, statusCode: status, message: err.message, data: null });
   }
-  // Error lain (database error, dsb)
-  console.error(err);
-  res.status(500).json({ message: 'Internal server error' });
+  next(err);
 });
 ```
-
-### Daftar error code
-
-| Code | Status HTTP Umum | Kapan muncul |
-|---|---|---|
-| `UNAUTHORIZED` | 401 | Tidak ada atau token tidak valid di header |
-| `TOKEN_EXPIRED` | 401 | Access token / refresh token sudah expire |
-| `TOKEN_INVALID` | 401 | Signature JWT salah, format rusak, atau tipe token keliru |
-| `INVALID_CREDENTIALS` | 401 | Identifier atau password salah |
-| `FORBIDDEN` | 403 | Login tapi tidak punya role / izin yang dibutuhkan |
-| `USER_ALREADY_EXISTS` | 409 | Signup dengan identifier yang sudah terdaftar |
-| `USER_NOT_FOUND` | 404 | Operasi butuh user yang tidak ada |
-| `INVALID_ROLE` | 400 | Signup meminta role yang tidak ada di `validRoles` |
-| `VALIDATION_ERROR` | 400 | Field wajib kosong atau format tidak valid |
-| `CONFIGURATION_ERROR` | — | `createAuth()` dipanggil dengan config yang tidak valid (throw di startup) |
-
-> `INVALID_CREDENTIALS` sengaja dipakai untuk dua kondisi (identifier tidak ditemukan **dan** password salah). Ini mencegah attacker menebak identifier mana yang terdaftar.
-
----
-
-## Type Exports
-
-Semua type yang perlu diimport dari library:
-
-```typescript
-import {
-  // Fungsi utama
-  createAuth,
-  AuthError,
-
-  // Types untuk konfigurasi
-  type AuthConfig,
-  type CookieConfig,
-  type AuthAdapter,
-  type UserRecord,
-  type SessionRecord,
-  type CreateUserData,
-
-  // Types untuk auth flow
-  type AuthUser,       // { id, identifier, roles } — isi req.user
-  type AuthResult,     // return type signup/login
-  type RefreshResult,  // return type refresh
-  type SignupInput,
-  type LoginInput,
-
-  // Types untuk permit middleware
-  type PermitCheck,
-  type PermitOptions,
-
-  // Types untuk error
-  type AuthErrorCode,
-  type AuthClient,
-} from 'sentri';
-```
-
-### Menggunakan tipe di luar library
-
-```typescript
-import type { AuthUser, PermitCheck } from 'sentri';
-import type { AppRole } from './lib/auth.js';
-
-// Tipe req.user sudah otomatis tersedia setelah import dari sentri
-// Tidak perlu extend Request manual
-function getUser(req: express.Request): AuthUser<AppRole> | undefined {
-  return req.user as AuthUser<AppRole> | undefined;
-}
-
-// Buat fungsi permission yang bisa di-reuse
-const isOwner: PermitCheck = (req) => req.user!.id === req.params['userId'];
-
-router.put('/:userId', auth.protect(), auth.permit(isOwner), handler);
-router.delete('/:userId', auth.protect(), auth.permit(isOwner), handler);
-```
-
----
-
-## Keamanan
-
-| Aspek | Implementasi |
-|---|---|
-| **Password hashing** | bcrypt, cost factor 12 (min 10), max input 72 karakter (batas bcrypt) |
-| **Token signing** | HMAC — satu secret menghasilkan dua key terpisah: `secret:access` dan `secret:refresh` |
-| **Anti-enumeration** | `INVALID_CREDENTIALS` dipakai untuk password salah **dan** identifier tidak ditemukan |
-| **Refresh token revocation** | Berbasis session di DB — hapus row = token langsung tidak berlaku, tanpa blacklist |
-| **Token rotation** | Setiap refresh, session lama dihapus dan session baru dibuat |
-| **Config validation** | Secret min 32 karakter, saltRounds 10–31, validRoles tidak boleh kosong — dicek saat startup |
-| **Input sanitization** | Identifier di-trim whitespace; max identifier 255 karakter, max password 72 karakter |
-| **Cookie mode** | httpOnly cookie mencegah akses JavaScript; `SameSite=strict` secara default; `maxAge` sesuai `refreshExpiresIn` |