sumor 3.2.3 → 3.3.0

package/README.md

@@ -5,614 +5,573 @@
 
 A comprehensive OAuth 2.0 authentication framework for Express.js applications with role-based access control (RBAC). Sumor simplifies OAuth integration, token management, and permission-based route protection in multi-service architectures.
 
-## ✨ Key Features
+[中文文档](README.zh-CN.md)
 
-- **🔐 OAuth 2.0 Complete Flow**: Full authorization code flow with PKCE support
-- **🔑 Session & Token Management**: Secure token exchange, refresh, and blacklisting
-- **🛡️ JWT Verification**: Built-in JWT validation using JWKS (JSON Web Key Set)
-- **👥 Role-Based Access Control (RBAC)**: Permission-based route protection and middleware
-- **📝 TypeScript First**: Full TypeScript support with complete type definitions
-- **🚀 Express Integration**: Drop-in middleware and route setup
-- **🎯 Permission Sync**: Automatic permission synchronization with OAuth provider
-- **💾 Session Revocation**: Token blacklist support for logout and session management
-- **🌐 Multi-Domain Support**: Built-in domain and origin handling
-- **⚡ Request Context**: Access user info and OAuth service in Express request object
+## Key Features
 
-## 📦 Installation
+- **OAuth 2.0 Complete Flow**: Full authorization code flow with automatic token exchange
+- **Session & Token Management**: Secure token exchange, refresh via HTTP-only cookies
+- **JWT Verification**: Built-in JWT validation using JWKS (JSON Web Key Set)
+- **Role-Based Access Control (RBAC)**: Permission sync and runtime permission/role checks
+- **TypeScript First**: Full TypeScript support with complete type definitions
+- **Express Integration**: Drop-in middleware and pre-configured route setup
+- **Permission Sync**: Register application permissions to the OAuth provider at startup
+- **Mock Mode**: Zero-dependency local development without a real OAuth server
+- **Web Client SDK**: Browser-side token refresh, user state, and permission utilities
+
+## Installation
 
 ```bash
 npm install sumor
 ```
 
-## 🚀 Quick Start
+## Architecture Overview
 
-### Server Setup
+Sumor is split into two entry points:
 
-```typescript
-import { OAuthService, loadJwtUserMiddleware, oauthRoutes } from 'sumor'
+| Entry       | Purpose                         |
+| ----------- | ------------------------------- |
+| `sumor`     | Server-side (Node.js / Express) |
+| `sumor/web` | Client-side (browser)           |
 
-// Define permissions for your application
-const permissionConfig = {
-  permissions: ['posts:view', 'posts:edit', 'posts:delete'],
-  permissionLabels: [
-    {
-      module: 'posts',
-      zh: '帖子管理',
-      en: 'Posts Management'
-    }
-  ]
-}
-
-// Initialize OAuth
-const oauthService = new OAuthService()
-await oauthService.updatePermissions(permissionConfig)
-
-// Register JWT middleware and OAuth routes
-app.use('/api', loadJwtUserMiddleware)
-app.use('/api/oauth', oauthRoutes)
+```
+Browser App
+  │  (1) refreshToken() on init
+  │  (2) login() → redirect to OAuth provider
+  │  (3) OAuth callback → /api/oauth/callback
+  │  (4) Subsequent requests carry HttpOnly cookie
+  ▼
+Your Express App
+  ├── oauthRoutes          ← /api/oauth/* (token refresh, callback, logout)
+  ├── loadJwtUserMiddleware ← validates JWT, injects req.jwtUser
+  └── Your routes          ← access req.jwtUser, call OAuthService methods
+  ▼
+OAuth Provider
+  └── issues JWT, manages users & permissions, exposes JWKS
 ```
 
-### Accessing User Info in Routes
+---
 
-```typescript
-// User info from JWT token is available in req.jwtUser
-app.get('/api/user/profile', (req: any, res) => {
-  const user = req.jwtUser
+## Server-Side Usage
 
-  res.json({
-    userId: user.userId,
-    roles: user.roles?.split(','),
-    permissions: user.permissions?.split(','),
-    verified: user.isVerified
-  })
-})
+### Install
 
-// Call OAuth service methods via req.sumor
-app.get('/api/users/:userId', async (req: any, res) => {
-  try {
-    // Fetch user info from OAuth provider
-    const userInfo = await req.sumor.getUserInfo(req.params.userId)
-    res.json(userInfo)
-  } catch (error) {
-    res.status(400).json({ error: error.message })
-  }
-})
+```typescript
+import { OAuthService, loadJwtUserMiddleware, oauthRoutes } from 'sumor'
 ```
 
-## 📚 API Reference
+### Exports
 
-### OAuthService Class
+| Export                  | Type           | Description                           |
+| ----------------------- | -------------- | ------------------------------------- |
+| `OAuthService`          | Class          | Interact with the OAuth provider API  |
+| `loadJwtUserMiddleware` | Middleware     | Validate JWT and inject `req.jwtUser` |
+| `oauthRoutes`           | Express Router | Pre-configured OAuth routes           |
 
-#### updatePermissions(config)
+### Setup
 
-Synchronize permissions to the OAuth provider.
+Register the OAuth routes and middleware in your Express app:
 
-**Parameters:**
+```typescript
+import express from 'express'
+import { OAuthService, loadJwtUserMiddleware, oauthRoutes } from 'sumor'
 
-- `config` (Object):
-  - `permissions` (string[]) - List of permission strings in format `<module>:<operation>`
-  - `permissionLabels` (Array) - Labels with `module`, `zh`, `en` fields
+const app = express()
 
-**Example:**
+// Register pre-configured OAuth routes (callback, token refresh, logout)
+app.use('/api/oauth', oauthRoutes)
 
-```typescript
-const oauthService = new OAuthService()
-await oauthService.updatePermissions({
-  permissions: ['posts:view', 'posts:edit', 'posts:delete'],
-  permissionLabels: [
-    {
-      module: 'posts',
-      zh: '帖子管理',
-      en: 'Posts Management'
-    }
-  ]
-})
+// JWT middleware: validates token and injects req.jwtUser for all routes below
+app.use(loadJwtUserMiddleware)
+
+// Your protected routes go here
+app.use('/api/user', userRoutes)
 ```
 
-### Middleware & Routes
+> **Note:** Register `oauthRoutes` before `loadJwtUserMiddleware` so that OAuth callback endpoints (`/api/oauth/callback`) are publicly accessible.
 
-#### loadJwtUserMiddleware
+### Sync Permissions on Startup
 
-Middleware that validates JWT tokens and extracts user information into `req.jwtUser`.
+Register your application's permission definitions with the OAuth provider once on startup:
 
 ```typescript
-app.use('/api', loadJwtUserMiddleware)
+const oauthService = new OAuthService()
+
+await oauthService.updatePermissions({
+  permissions: ['posts:view', 'posts:create', 'posts:edit', 'posts:delete'],
+  permissionLabels: [{ module: 'posts', zh: '文章管理', en: 'Posts Management' }]
+})
 ```
 
-#### oauthRoutes
+Permission strings follow the format `<module>:<operation>`.
 
-Pre-configured OAuth routes:
+### Access User Info in Routes
 
-- `GET /api/oauth/callback` - Handle OAuth callback (no auth required)
-- `PUT /api/oauth/token` - Refresh token and get user info + authorization URL
-- `POST /api/oauth/logout` - Logout and revoke session
+After `loadJwtUserMiddleware`, `req.jwtUser` contains the decoded JWT payload:
 
 ```typescript
-app.use('/api/oauth', oauthRoutes)
-```
+app.get('/api/profile', (req, res) => {
+  const { userId, roles, permissions, isVerified } = req.jwtUser
 
-### req.jwtUser
+  res.json({
+    userId,
+    roles: roles?.split(',') ?? [],
+    permissions: permissions?.split(',') ?? [],
+    isVerified: isVerified === 1
+  })
+})
+```
 
-Available in all route handlers after middleware initialization. Contains the user info from JWT token.
+**`req.jwtUser` properties:**
 
-**Properties:**
+| Property      | Type     | Description                        |
+| ------------- | -------- | ---------------------------------- |
+| `userId`      | `string` | Unique user identifier             |
+| `roles`       | `string` | Comma-separated role IDs           |
+| `permissions` | `string` | Comma-separated permission strings |
+| `isVerified`  | `number` | `1` if verified, `0` otherwise     |
+| `tenantId`    | `string` | Multi-tenant identifier            |
+| `jti`         | `string` | JWT ID (session identifier)        |
+| `exp`         | `number` | Token expiration timestamp         |
+| `iat`         | `number` | Token issued-at timestamp          |
 
-- `userId` (string) - Unique user identifier
-- `roles` (string) - Comma-separated role IDs
-- `permissions` (string) - Comma-separated user permissions
-- `isVerified` (number) - Verification status
-- `tenantId` (string) - Multi-tenant identifier
-- `exp` (number) - Token expiration timestamp
-- `iat` (number) - Token issued at timestamp
+### OAuthService Methods
 
-**Example:**
+Create an instance anywhere in your server code — it reads configuration from environment variables automatically:
 
 ```typescript
-app.get('/api/protected', (req: any, res) => {
-  const { userId, roles, permissions } = req.jwtUser
-  res.json({ userId, roles: roles?.split(','), permissions: permissions?.split(',') })
-})
+const oauthService = new OAuthService()
 ```
 
-### req.sumor (OAuthService)
-
-Available in all route handlers. Provides methods to call the OAuth provider's API.
-
-**Methods:**
-
-#### getUserInfo(userId)
+#### `updatePermissions(config)`
 
-Get detailed user information from the OAuth provider.
+Synchronize the application's permission definitions to the OAuth provider.
 
 ```typescript
-const userInfo = await req.sumor.getUserInfo('user123')
-// Returns: { userId, name, email, avatar, ... }
+await oauthService.updatePermissions({
+  permissions: ['resource:view', 'resource:edit'],
+  permissionLabels: [{ module: 'resource', zh: '资源管理', en: 'Resource Management' }]
+})
 ```
 
-#### getUsersInfo(userIds)
+#### `getUserInfo(userId)`
 
-Get information for multiple users.
+Fetch detailed information for a single user.
 
 ```typescript
-const users = await req.sumor.getUsersInfo(['user1', 'user2'])
-// Returns: [{ userId, name, ... }, ...]
+const userInfo = await oauthService.getUserInfo('user-123')
+// Returns: { userId, username, nickname, email, avatar, ... }
 ```
 
-#### searchUsers(searchTerm, limit)
+#### `getUsersInfo(userIds)`
 
-Search for users by name or email.
+Fetch information for multiple users in one call.
 
 ```typescript
-const results = await req.sumor.searchUsers('john', 20)
-// Returns: [{ userId, name, email, ... }, ...]
+const users = await oauthService.getUsersInfo(['user-1', 'user-2', 'user-3'])
+// Returns: [{ userId, username, ... }, ...]
 ```
 
-#### exchangeCode(grantType, code, redirectUri, codeVerifier)
+#### `searchUsers(searchTerm, limit)`
 
-Exchange authorization code for tokens (internal use).
+Search users by name or email.
 
 ```typescript
-const tokens = await req.sumor.exchangeCode(
-  'authorization_code',
-  authCode,
-  'http://localhost:3000/callback',
-  codeVerifier
-)
-// Returns: { accessToken, refreshToken, expiresIn, tokenType }
+const results = await oauthService.searchUsers('alice', 20)
+// Returns: [{ userId, username, email, ... }, ...]
 ```
 
-#### checkBlacklist(sessionId)
+#### `revokeSession(sessionId)`
 
-Check if a session token is revoked.
+Revoke (blacklist) a session on logout.
 
 ```typescript
-const isBlacklisted = await req.sumor.checkBlacklist(sessionId)
+await oauthService.revokeSession(req.jwtUser.jti)
 ```
 
-#### revokeSession(sessionId)
+#### `checkBlacklist(sessionId)`
 
-Revoke (logout) a session.
+Check whether a session has been revoked.
 
 ```typescript
-await req.sumor.revokeSession(sessionId)
+const isRevoked = await oauthService.checkBlacklist(sessionId)
 ```
 
-### OAuth Routes
+### Pre-configured OAuth Routes
 
-Sumor automatically registers these routes:
+`oauthRoutes` registers the following endpoints automatically:
 
-- `GET /api/oauth/callback` - Handle OAuth provider callback with authorization code (no auth required)
-- `PUT /api/oauth/token` - Refresh access token and get user info + authorization URL (can use refreshToken from body or cookie)
-  - Response includes `endpoint` and `authorizeUrl` for OAuth configuration, and `user` object with current user info
-- `POST /api/oauth/logout` - Logout and revoke session (requires valid token)
+| Method | Path                  | Auth required | Description                                            |
+| ------ | --------------------- | ------------- | ------------------------------------------------------ |
+| `GET`  | `/api/oauth/callback` | No            | Exchange authorization code for tokens                 |
+| `PUT`  | `/api/oauth/token`    | No            | Refresh access token; returns user info and OAuth URLs |
+| `POST` | `/api/oauth/logout`   | Yes           | Revoke session and clear cookies                       |
 
-## 🎯 Web Client (Sumor Class)
+---
 
-The Sumor framework includes a client-side class for browser applications to manage OAuth and user state.
+## Client-Side Usage (`sumor/web`)
 
-### Basic Setup
+### Install
 
 ```typescript
-import { setupSumor } from 'sumor'
-
-// Call this on app initialization
-await setupSumor()
+import {
+  refreshToken,
+  login,
+  logout,
+  hasPermission,
+  hasRole,
+  oauthUrl,
+  oauthStore,
+  axios
+} from 'sumor/web'
+import type { ApiResponse } from 'sumor/web'
+```
+
+### Exports
+
+| Export          | Type           | Description                                           |
+| --------------- | -------------- | ----------------------------------------------------- |
+| `refreshToken`  | Function       | Refresh token and sync user state (call on app init)  |
+| `login`         | Function       | Redirect to OAuth login page                          |
+| `logout`        | Function       | Call logout endpoint and clear user state             |
+| `hasPermission` | Function       | Check if the current user has a specific permission   |
+| `hasRole`       | Function       | Check if the current user has a specific role         |
+| `oauthStore`    | Singleton      | In-memory user and OAuth state store                  |
+| `oauthUrl`      | Object         | Helpers to generate OAuth provider navigation URLs    |
+| `axios`         | Axios instance | Pre-configured Axios with automatic 401 token refresh |
+| `ApiResponse`   | Type           | Standard API response wrapper type                    |
+
+### Initialize on App Start
+
+Call `refreshToken()` once during application initialization to restore user state from the stored refresh token cookie:
 
-// Now use window.sumor to access the Sumor client
-console.log(window.sumor.user) // Current user info or null
-```
-
-### Sumor Client Properties
+```typescript
+// main.ts (or App.vue onMounted)
+import { refreshToken } from 'sumor/web'
 
-- `endpoint` - OAuth provider endpoint
-- `authorizeUrl` - Authorization URL for login redirect
-- `user` - Current user object or null
-  - `id` - User ID
-  - `isVerified` - Verification status
-  - `roles` - Comma-separated role list
-  - `permissions` - Comma-separated permission list
+await refreshToken()
 
-### Sumor Client Methods
+// User state is now available via oauthStore
+```
 
-#### refresh(force = false)
+> In SSR environments, `refreshToken()` is a no-op and returns immediately.
 
-Refresh OAuth configuration and user info from `PUT /api/oauth/token` using the stored refresh token.
+### Login and Logout
 
 ```typescript
-// Use cache if available
-await window.sumor.refresh()
+import { login, logout } from 'sumor/web'
 
-// Force refresh, ignore cache
-await window.sumor.refresh(true)
+// Redirect to OAuth authorization page
+login()
+
+// Logout: revokes session and clears user state
+await logout()
 ```
 
-#### login()
+### Subscribe to User Changes
 
-Redirect to OAuth authorization page.
+Use `oauthStore` to read the current user and react to state changes:
 
 ```typescript
-window.sumor.login()
-```
+import { oauthStore } from 'sumor/web'
 
-#### logout()
+// Read current user
+const user = oauthStore.getUser()
+// { id, isVerified, roles, permissions } or null
 
-Logout and clear local user state.
-
-```typescript
-await window.sumor.logout()
-// window.sumor.user becomes null
+// Subscribe to login/logout events
+oauthStore.onUserChange(user => {
+  if (user) {
+    console.log('Logged in:', user.id)
+  } else {
+    console.log('Logged out')
+  }
+})
 ```
 
-#### hasPermission(module, operation = '\*')
+**`UserInfo` properties:**
 
-Check if user has a specific permission.
+| Property      | Type     | Description                        |
+| ------------- | -------- | ---------------------------------- |
+| `id`          | `string` | User ID                            |
+| `isVerified`  | `number` | `1` if verified                    |
+| `roles`       | `string` | Comma-separated role IDs           |
+| `permissions` | `string` | Comma-separated permission strings |
+
+### Permission and Role Checks
 
 ```typescript
-// Check specific permission
-if (window.sumor.hasPermission('posts', 'edit')) {
+import { hasPermission, hasRole } from 'sumor/web'
+
+// Check a specific permission (module + operation)
+if (hasPermission('posts', 'edit')) {
   // User can edit posts
 }
 
-// Check module (any operation)
-if (window.sumor.hasPermission('posts')) {
+// Check any permission in a module (wildcard)
+if (hasPermission('posts', '*')) {
   // User has any posts permission
 }
 
-if (window.sumor.hasPermission('posts', '*')) {
-  // Same as above
+// Check role
+if (hasRole('admin')) {
+  // User is an admin
 }
 ```
 
-#### hasRole(role)
-
-Check if user has a specific role.
+### OAuth URL Helpers
 
 ```typescript
-if (window.sumor.hasRole('admin')) {
-  // User is admin
-}
+import { oauthUrl } from 'sumor/web'
+
+oauthUrl.avatar(userId) // URL for a user's avatar image
+oauthUrl.user() // URL for the user profile page
+oauthUrl.home() // URL for the OAuth provider home page
+oauthUrl.site() // URL for the site management page
+oauthUrl.feedback() // URL for the feedback page
 ```
 
-#### onUserChange(callback)
+In [Mock Mode](#mock-mode), these URLs point to placeholder pages served locally.
+
+### Making Authenticated HTTP Requests
 
-Subscribe to user state changes (login, logout, token refresh).
+The exported `axios` instance automatically handles 401 responses by refreshing the token and retrying:
 
 ```typescript
-window.sumor.onUserChange(user => {
-  if (user) {
-    console.log('User logged in:', user.id)
-  } else {
-    console.log('User logged out')
+import { axios } from 'sumor/web'
+import type { ApiResponse } from 'sumor/web'
+
+// GET
+const { data } = await axios.get<ApiResponse<UserInfo>>('/api/user/info')
+
+// POST
+const { data } = await axios.post<ApiResponse<Item>>('/api/items', { name: 'My Item' })
+
+// PUT
+const { data } = await axios.put<ApiResponse<Item>>(`/api/items/${id}`, updates)
+
+// DELETE
+const { data } = await axios.delete<ApiResponse<null>>(`/api/items/${id}`)
+
+// File upload with progress
+await axios.post<ApiResponse<UploadResult>>('/api/upload', formData, {
+  headers: { 'Content-Type': 'multipart/form-data' },
+  onUploadProgress: e => {
+    const percent = Math.round((e.loaded * 100) / (e.total ?? e.loaded))
+    console.log(`Upload progress: ${percent}%`)
   }
 })
 ```
 
-### Web Client Example
+**`ApiResponse<T>` type:**
 
 ```typescript
-import { setupSumor } from 'sumor'
-import { ref, watch } from 'vue'
-
-export default {
-  setup() {
-    const userInfo = ref(null)
-    const isLoggedIn = ref(false)
-
-    onMounted(async () => {
-      await setupSumor()
-
-      // Get initial user state
-      userInfo.value = window.sumor.user
-      isLoggedIn.value = !!window.sumor.user
-
-      // Subscribe to user changes
-      window.sumor.onUserChange(user => {
-        userInfo.value = user
-        isLoggedIn.value = !!user
-      })
-    })
-
-    return {
-      userInfo,
-      isLoggedIn,
-      login: () => window.sumor.login(),
-      logout: () => window.sumor.logout(),
-      canEdit: () => window.sumor.hasPermission('posts', 'edit')
-    }
-  }
+interface ApiResponse<T> {
+  code: string // 'OK' on success
+  message: string
+  data: T
 }
 ```
 
-## 📚 API Reference
+---
+
+## Configuration
 
-Sumor uses environment variables for configuration. The key is configuring the OAuth provider endpoint:
+Sumor reads all configuration from environment variables. No explicit constructor arguments are required.
+
+### Required Environment Variables
 
 ```bash
-# OAuth Provider Configuration
 OAUTH_ENDPOINT=https://auth.example.com
 OAUTH_CLIENT_KEY=your-app-client-id
 OAUTH_CLIENT_SECRET=your-app-client-secret
 OAUTH_REDIRECT_URI=http://localhost:3000/api/oauth/callback
 ```
 
-**How it works:**
-
-- `OAUTH_ENDPOINT` - Base URL of your OAuth provider (e.g., `https://auth.example.com`)
-- OAuth endpoints are automatically derived: `{OAUTH_ENDPOINT}/api/oauth/...`
-- `OAUTH_CLIENT_KEY` and `OAUTH_CLIENT_SECRET` - OAuth application credentials
-- `OAUTH_REDIRECT_URI` - Callback URL that matches your OAuth provider configuration
-- JWT tokens are verified using JWKS public keys from the OAuth provider (no local secret needed)
-
-**Example configurations:**
-
-```bash
-# Local development
-OAUTH_ENDPOINT=http://localhost:3001
-OAUTH_CLIENT_KEY=myapp-dev
-OAUTH_CLIENT_SECRET=myapp-dev-secret
-OAUTH_REDIRECT_URI=http://localhost:3000/api/oauth/callback
+| Variable              | Description                                            |
+| --------------------- | ------------------------------------------------------ |
+| `OAUTH_ENDPOINT`      | Base URL of the OAuth provider                         |
+| `OAUTH_CLIENT_KEY`    | OAuth application client ID                            |
+| `OAUTH_CLIENT_SECRET` | OAuth application client secret                        |
+| `OAUTH_REDIRECT_URI`  | Callback URL (must match OAuth provider configuration) |
 
-# Production
-OAUTH_ENDPOINT=https://auth.mycompany.com
-OAUTH_CLIENT_KEY=myapp-prod
-OAUTH_CLIENT_SECRET=<secure-secret>
-OAUTH_REDIRECT_URI=https://app.mycompany.com/api/oauth/callback
-```
+JWT tokens are verified using JWKS public keys fetched from `{OAUTH_ENDPOINT}/api/oauth/jwks` — no local secret is required.
 
-## 📚 Usage Examples
+---
 
-### Example 1: Protect Routes with Permission Checks
+## Mock Mode
 
-```typescript
-// Server-side: Express route with permission check
-app.post('/api/posts', (req: any, res) => {
-  // Check if user has permission
-  const permissions = req.jwtUser.permissions?.split(',') || []
+Mock Mode allows local development without a running OAuth server. Enable it by setting `OAUTH_MOCK=true`. In this mode, Sumor issues locally signed JWT tokens using HS256 and exposes additional mock-only endpoints.
 
-  if (!permissions.includes('posts:create')) {
-    return res.status(403).json({ error: 'Insufficient permissions' })
-  }
+### How It Works
 
-  // Create post logic here
-  res.json({ postId: 123 })
-})
+When `OAUTH_MOCK=true`:
 
-// Client-side: Vue component with permission check
-export default {
-  setup() {
-    return {
-      canCreatePost: () => window.sumor.hasPermission('posts', 'create')
-    }
-  }
-}
+- `oauthRoutes` registers extra sub-routes under `/api/oauth/mock/`
+- The `PUT /api/oauth/token` route validates mock tokens locally instead of calling the OAuth provider
+- `login()` on the web client calls `POST /api/oauth/mock/login` directly instead of redirecting to the OAuth provider
+- `logout()` calls `POST /api/oauth/mock/logout` to clear cookies locally
+- `oauthUrl.*` helpers return local placeholder pages instead of external OAuth URLs
 
-// Template
-<button v-if="canCreatePost()" @click="createPost">Create Post</button>
-```
+### Mock Server Environment Variables
 
-### Example 2: Multi-Tenant Support
+```bash
+# Enable mock mode
+OAUTH_MOCK=true
 
-```typescript
-app.get('/api/tenant/users', (req: any, res) => {
-  const tenantId = req.jwtUser.tenantId
+# Mock user configuration (all optional — defaults shown)
+OAUTH_MOCK_USER_ID=mock-user-001
+OAUTH_MOCK_USER_ROLES=admin
+OAUTH_MOCK_USER_PERMISSIONS=
+OAUTH_MOCK_USER_IS_VERIFIED=1
 
-  // Fetch users for the user's tenant
-  db.query('SELECT * FROM users WHERE tenant_id = ?', [tenantId]).then(users => res.json(users))
-})
+# URLs returned by the mock token endpoint
+OAUTH_MOCK_ENDPOINT=http://localhost
+OAUTH_MOCK_REDIRECT_URI=http://localhost
 ```
 
-### Example 3: Fetch Related User Data
+| Variable                      | Default            | Description                               |
+| ----------------------------- | ------------------ | ----------------------------------------- |
+| `OAUTH_MOCK`                  | `false`            | Set to `true` to enable mock mode         |
+| `OAUTH_MOCK_USER_ID`          | `mock-user-001`    | Mock user ID                              |
+| `OAUTH_MOCK_USER_ROLES`       | `admin`            | Comma-separated mock roles                |
+| `OAUTH_MOCK_USER_PERMISSIONS` | _(empty)_          | Comma-separated mock permissions          |
+| `OAUTH_MOCK_USER_IS_VERIFIED` | `1`                | Mock verification status (`0` or `1`)     |
+| `OAUTH_MOCK_ENDPOINT`         | `http://localhost` | Endpoint value returned in token response |
+| `OAUTH_MOCK_REDIRECT_URI`     | `http://localhost` | Origin to redirect after mock login       |
 
-```typescript
-app.get('/api/followers', async (req: any, res) => {
-  try {
-    // Get list of follower IDs from your local database
-    const followerIds = await db.query(
-      'SELECT follower_id FROM relationships WHERE leader_id = ?',
-      [req.jwtUser.userId]
-    )
-
-    // Get detailed info for all followers from OAuth provider
-    const followerInfo = await req.sumor.getUsersInfo(followerIds.map(r => r.follower_id))
-
-    res.json(followerInfo)
-  } catch (error) {
-    res.status(500).json({ error: error.message })
-  }
-})
-```
+### Mock Routes (registered only when `OAUTH_MOCK=true`)
 
-### Example 4: User Search with Pagination
+| Method | Path                          | Description                                                 |
+| ------ | ----------------------------- | ----------------------------------------------------------- |
+| `POST` | `/api/oauth/mock/login`       | Issue mock tokens and return user info (no redirect needed) |
+| `POST` | `/api/oauth/mock/logout`      | Clear mock token cookies                                    |
+| `GET`  | `/api/oauth/mock/avatar/:id`  | Returns 404 (no avatar service in mock mode)                |
+| `GET`  | `/api/oauth/mock/nav/:target` | Placeholder page for OAuth provider navigation links        |
 
-```typescript
-app.get('/api/search/users', async (req: any, res) => {
-  const { q, limit = 20 } = req.query
+### Example Mock Setup
 
-  if (!q) {
-    return res.status(400).json({ error: 'Search term required' })
-  }
+**.env.development:**
 
-  try {
-    const results = await req.sumor.searchUsers(q, limit)
-    res.json(results)
-  } catch (error) {
-    res.status(500).json({ error: error.message })
-  }
-})
+```bash
+OAUTH_MOCK=true
+OAUTH_MOCK_USER_ID=dev-user-1
+OAUTH_MOCK_USER_ROLES=admin
+OAUTH_MOCK_USER_PERMISSIONS=posts:view,posts:edit,posts:delete
+OAUTH_MOCK_USER_IS_VERIFIED=1
 ```
 
-## 🛡️ Security Considerations
+No changes are needed in application code — the same `oauthRoutes`, `loadJwtUserMiddleware`, `login()`, and `logout()` calls work in both mock and production modes.
 
-### Token Storage
+### Security Notice
 
-- Tokens are stored in HTTP-only cookies by default (secure against XSS)
-- Always use HTTPS in production to prevent token interception
-- Refresh tokens should be rotated regularly
+Mock tokens are signed with a fixed HS256 secret and are identified by `iss: 'mock-oauth'` in the payload. **Never use `OAUTH_MOCK=true` in production.**
 
-### Permission Validation
+---
 
-Always validate permissions on sensitive operations:
+## Usage Examples
 
-```typescript
-const userPermissions = req.jwtUser.permissions?.split(',') || []
+### Server — Protect a Route with Permission Check
 
-if (!userPermissions.includes('users:edit')) {
-  return res.status(403).json({ error: 'User edit permission required' })
-}
-```
-
-### Session Revocation
+```typescript
+app.post('/api/posts', (req, res) => {
+  const permissions = req.jwtUser.permissions?.split(',') ?? []
 
-Logout invalidates tokens immediately:
+  if (!permissions.includes('posts:create')) {
+    return res.status(403).json({ code: 'FORBIDDEN', message: 'Insufficient permissions' })
+  }
 
-```typescript
-// On logout
-await req.sumor.revokeSession(req.jwtUser.jti)
-// Token is added to blacklist and becomes invalid
+  // Create post...
+  res.json({ code: 'OK', data: { id: 'new-post-id' } })
+})
 ```
 
-### CSRF Protection
-
-Implement CSRF tokens for state-changing operations:
+### Server — Fetch User Details from OAuth Provider
 
 ```typescript
-const csrf = require('csurf')
-const csrfProtection = csrf({ cookie: false })
+app.get('/api/posts/:id/author', async (req, res) => {
+  const post = await db.findPost(req.params.id)
+  const author = await oauthService.getUserInfo(post.authorId)
 
-app.post('/api/posts', csrfProtection, (req: any, res) => {
-  // Handle POST with CSRF protection
+  res.json({ code: 'OK', data: author })
 })
 ```
 
-## 🐛 Troubleshooting
-
-### "Token verification failed"
-
-**Cause:** JWT signature doesn't match JWKS public key
-
-**Solution:** Ensure `OAUTH_ENDPOINT` is correctly configured. Sumor automatically fetches JWKS from `{OAUTH_ENDPOINT}/api/oauth/jwks`
+### Web — Vue Component with Login/Logout
 
-### "Unauthorized" on protected routes
+```typescript
+import { login, logout, oauthStore, hasPermission } from 'sumor/web'
+import { ref, onMounted } from 'vue'
 
-**Cause:** Missing or invalid JWT token in request
+const user = ref(oauthStore.getUser())
 
-**Solution:** Client must include Authorization header:
+onMounted(() => {
+  oauthStore.onUserChange(u => {
+    user.value = u
+  })
+})
 
+const canEdit = () => hasPermission('posts', 'edit')
 ```
-Authorization: Bearer <JWT_TOKEN>
+
+```html
+<template>
+  <button v-if="!user" @click="login">Login</button>
+  <button v-else @click="logout">Logout</button>
+  <button v-if="canEdit()" @click="editPost">Edit</button>
+</template>
 ```
 
-### "Session not found" when revoking
+### Web — Vue Router Guard
 
-**Cause:** Session ID (jti) is invalid or already revoked
+```typescript
+import { refreshToken, hasPermission } from 'sumor/web'
 
-**Solution:** Check that `req.jwtUser.jti` contains a valid session ID
+// Restore user state before mounting router
+await refreshToken()
 
-### Permission check always fails
+router.beforeEach(to => {
+  if (to.meta.requiresPermission) {
+    const [module, operation] = (to.meta.requiresPermission as string).split(':')
+    if (!hasPermission(module, operation)) {
+      return '/403'
+    }
+  }
+})
+```
 
-**Cause:** Permissions string format is incorrect
+---
 
-**Solution:** Permissions are comma-separated strings. Parse correctly:
+## Security Considerations
 
-```typescript
-const permissions = req.jwtUser.permissions?.split(',').map(p => p.trim()) || []
-```
+- Tokens are stored in **HTTP-only cookies** and never exposed to JavaScript (XSS protection)
+- Always use **HTTPS** in production
+- JWT signatures are verified against JWKS public keys fetched from the OAuth provider
+- Logout immediately **blacklists** the session on the OAuth provider
+- Never enable `OAUTH_MOCK=true` outside of local development
 
-## 🔄 Architecture
+---
 
-```
-┌──────────────────────────────────────┐
-│      Browser / Mobile Client         │
-└───────────────┬──────────────────────┘
-                │ (1) Click Login
-                ▼
-┌──────────────────────────────────────┐
-│    Your Express App (Port 3000)      │
-│  ┌────────────────────────────────┐  │
-│  │ PUT /api/oauth/token           │  │ (2) Get OAuth URL & User Info
-│  │ GET /api/oauth/callback        │  │
-│  │ POST /api/oauth/logout         │  │
-│  └────────────────────────────────┘  │
-└───────────┬──────────────────────────┘
-            │ (3) Redirect to OAuth
-            ▼
-┌──────────────────────────────────────┐
-│      OAuth Provider                  │
-│   {OAUTH_ENDPOINT}/api/oauth/...     │
-│   - Issue JWT tokens                 │
-│   - Manage users & permissions       │
-│   - Provide JWKS public keys         │
-└──────────────────────────────────────┘
-            ▲
-            │ (4) Verify JWT
-            │
-        req.sumor
-```
+## Troubleshooting
 
-**Flow Steps:**
+### `req.jwtUser` is `undefined`
 
-1. User clicks "Login" on your app
-2. App calls `PUT /api/oauth/token` with refresh token to get OAuth provider URL and user info
-3. User redirected to OAuth provider
-4. OAuth provider authenticates and redirects back to `/api/oauth/callback` with authorization code
-5. Server exchanges code for JWT token via OAuth API
-6. Server verifies JWT signature using OAuth JWKS public keys
-7. Subsequent requests include JWT in Authorization header
-8. Middleware validates JWT and extracts user info (userId, roles, permissions)
-9. Routes access user info via `req.jwtUser` and call OAuth service via `req.sumor`
+Ensure that `loadJwtUserMiddleware` is registered before the routes that access `req.jwtUser`.
 
-## 🤝 Contributing
+### Token verification fails
 
-Contributions are welcome! Please feel free to submit issues and pull requests.
+Ensure `OAUTH_ENDPOINT` points to the correct OAuth provider. Sumor fetches JWKS from `{OAUTH_ENDPOINT}/api/oauth/jwks`.
 
-## � License
+### `refreshToken()` returns without setting a user
 
-MIT License - see [LICENSE](LICENSE) for details
+The refresh token cookie may be absent or expired. The user needs to log in again via `login()`.
 
-## 📞 Support
+### 401 on protected routes in mock mode
 
-For issues, questions, or suggestions, please open an issue on GitHub.
+Ensure `OAUTH_MOCK=true` is set both when the server starts and when checking tokens. Restart the server after changing this variable.
 
 ---
 
-Made with ❤️ by [Lycoo](https://lycoo.com)
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.