sentri 1.0.0

package/README.md

@@ -0,0 +1,1044 @@
+# 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
+
+---
+
+## 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)
+
+---
+
+## Instalasi
+
+```bash
+npm install sentri express
+npm install -D @types/express typescript
+```
+
+---
+
+## Cara Kerja
+
+Sebelum mulai, penting memahami dua konsep utama:
+
+### Dua token, satu secret
+
+```
+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
+
+| | 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 |
+
+### Session-based revocation
+
+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.
+
+```
+Login  →  buat session di DB  →  refresh token berisi sessionId
+Logout →  hapus session di DB →  refresh token langsung tidak berlaku
+```
+
+---
+
+## Setup Lengkap dari Nol
+
+### Langkah 1: Struktur project
+
+```
+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
+
+```bash
+# .env
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+JWT_SECRET="ganti-dengan-string-acak-minimal-32-karakter-ini"
+PORT=3000
+```
+
+> **Penting:** `JWT_SECRET` harus minimal 32 karakter. `createAuth()` akan throw `CONFIGURATION_ERROR` jika kurang dari itu.
+
+### Langkah 3: Siapkan tabel database
+
+Library membutuhkan empat tabel: **User**, **Role**, **UserRole**, dan **Session**.
+
+**Contoh Prisma schema** (`prisma/schema.prisma`):
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+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[]
+}
+
+model UserRole {
+  userId String
+  roleId String
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  role   Role   @relation(fields: [roleId], references: [id], onDelete: Cascade)
+
+  @@id([userId, roleId])
+}
+
+model Session {
+  id        String   @id @default(cuid())
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  expiresAt DateTime
+  createdAt DateTime @default(now())
+}
+```
+
+```bash
+npx prisma db push   # atau prisma migrate dev
+npx prisma generate
+```
+
+### Langkah 4: Buat adapter
+
+Adapter adalah jembatan antara library dan database kamu. Library mendefinisikan interface-nya, kamu mengisi implementasinya.
+
+```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 = {
+  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 };
+    },
+  },
+
+  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 } });
+    },
+  },
+};
+```
+
+### Langkah 5: Buat auth client
+
+```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',
+});
+```
+
+Setelah ini, TypeScript tahu persis role apa yang valid. `auth.authorize('superuser')` adalah **compile error**.
+
+### Langkah 6: Pasang di Express
+
+```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';
+
+const app = express();
+
+// 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);
+
+// 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);
+});
+```
+
+### 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` }),
+);
+```
+
+---
+
+## Contoh HTTP Request & Response
+
+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"] }'
+```
+
+```json
+// 201 Created
+{
+  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "user": {
+    "id": "clx1234abcd",
+    "identifier": "alice@example.com",
+    "roles": ["user"]
+  }
+}
+```
+
+```json
+// 409 Conflict — identifier sudah terdaftar
+{ "code": "USER_ALREADY_EXISTS", "message": "User already exists" }
+```
+
+```json
+// 400 Bad Request — role tidak ada di validRoles
+{ "code": "INVALID_ROLE", "message": "Invalid roles: superuser" }
+```
+
+### Login
+
+```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"]
+  }
+}
+```
+
+```json
+// 401 Unauthorized — identifier atau password salah
+{ "code": "INVALID_CREDENTIALS", "message": "Invalid credentials" }
+```
+
+### Akses endpoint protected
+
+Kirim `accessToken` di header `Authorization`:
+
+```bash
+curl http://localhost:3000/user/me \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+```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" }
+```
+
+```json
+// 401 Unauthorized — token sudah expire
+{ "code": "TOKEN_EXPIRED", "message": "Token has expired" }
+```
+
+```json
+// 403 Forbidden — tidak punya role yang dibutuhkan
+{ "code": "FORBIDDEN", "message": "Requires one of roles: admin" }
+```
+
+### Refresh token
+
+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).
+
+```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..."
+}
+```
+
+```json
+// 401 Unauthorized — refresh token sudah dipakai / session di-logout
+{ "code": "UNAUTHORIZED", "message": "Session not found or revoked" }
+```
+
+### Logout
+
+Hapus session saat ini. Refresh token yang terkait langsung tidak berlaku.
+
+```bash
+curl -X POST http://localhost:3000/auth/logout \
+  -H "Content-Type: application/json" \
+  -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'
+```
+
+```json
+// 200 OK
+{ "message": "logged out" }
+```
+
+### Logout semua device
+
+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..."
+```
+
+```json
+// 200 OK
+{ "message": "all sessions revoked" }
+```
+
+### Cek user saat ini
+
+Mengembalikan data user yang sedang login berdasarkan access token. Endpoint ini membutuhkan access token yang valid.
+
+```bash
+curl http://localhost:3000/auth/me \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+```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" }
+```
+
+---
+
+## Middleware
+
+Library menyediakan tiga middleware yang bisa dikombinasikan:
+
+```
+protect()    → autentikasi: siapa yang request?
+authorize()  → otorisasi role: role apa yang boleh?
+permit()     → otorisasi resource: boleh akses data ini?
+```
+
+Ketiganya bekerja seperti rantai. `authorize` dan `permit` selalu dipasang **setelah** `protect`.
+
+### `auth.protect()`
+
+Verifikasi access token dari header `Authorization: Bearer <token>`. Jika valid, `req.user` tersedia di handler berikutnya.
+
+```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,
+  });
+});
+```
+
+### `auth.authorize(...roles)`
+
+Cek apakah user punya minimal satu dari role yang disebutkan.
+
+```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);
+```
+
+### `auth.permit(check | options)`
+
+Cek kepemilikan resource atau kondisi apapun yang butuh data dari request. Cocok untuk aturan seperti "hanya pemilik yang bisa edit".
+
+**Bentuk 1 — fungsi check saja:**
+
+```typescript
+// User hanya bisa akses data miliknya sendiri
+router.get('/orders/:orderId',
+  auth.protect(),
+  auth.permit(async (req) => {
+    const order = await db.order.findUnique({ where: { id: req.params['orderId'] } });
+    return order?.userId === req.user!.id;
+  }),
+  getOrderHandler,
+);
+```
+
+**Bentuk 2 — dengan role bypass:**
+
+```typescript
+// Admin bisa akses semua; user biasa hanya miliknya
+router.delete('/orders/:orderId',
+  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;
+    },
+  }),
+  updateArticleHandler,
+);
+```
+
+---
+
+## Custom Routes
+
+Jika `auth.router()` tidak sesuai kebutuhan, kamu bisa tulis route sendiri menggunakan method `auth.signup()`, `auth.login()`, dll secara langsung.
+
+```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);
+  }
+});
+
+// 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' });
+
+    const result = await auth.refresh(refreshToken);
+    if (!result.success) return res.status(401).json({ error: result.error.code });
+
+    res.cookie('refreshToken', result.refreshToken, { httpOnly: true, secure: true });
+    res.json({ accessToken: result.accessToken });
+  } catch (err) {
+    next(err);
+  }
+});
+```
+
+---
+
+## 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:
+
+```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
+
+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"] }
+}
+```
+
+```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..." }
+```
+
+```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
+
+```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;
+}
+
+// Yang diterima adapter dari library saat membuat user
+interface CreateUserData {
+  identifier: string;
+  passwordHash: string; // sudah di-hash, jangan hash lagi
+  roles: string[];
+}
+```
+
+---
+
+## Error Handling
+
+Semua error dari library dilempar sebagai instance `AuthError` dan diteruskan via `next(err)`.
+
+### Menangkap di error handler global
+
+```typescript
+import { AuthError } from 'sentri';
+
+app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
+  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;
+  }
+  // Error lain (database error, dsb)
+  console.error(err);
+  res.status(500).json({ message: 'Internal server error' });
+});
+```
+
+### 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` |