sumor 2.0.3 → 3.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Sumor Cloud
+Copyright (c) 2024 Lycoo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1 +1,467 @@
-# Sumor Cloud Application Framework
+# Sumor - OAuth Authentication Framework
+
+[![npm version](https://img.shields.io/npm/v/sumor.svg)](https://www.npmjs.com/package/sumor)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+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
+
+- **🔐 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
+
+## 📦 Installation
+
+```bash
+npm install sumor
+```
+
+## 🚀 Quick Start
+
+### Basic Setup
+
+```typescript
+import express from 'express'
+import setupSumor from 'sumor'
+
+const app = express()
+
+// Define permissions for your application
+// Format: <module>:<operation>
+// Operations: view, create, edit, delete
+const permissions = {
+  permissions: [
+    'users:view', // View user information
+    'users:edit', // Edit users
+    'posts:view', // View posts
+    'posts:create', // Create posts
+    'posts:edit', // Edit posts
+    'posts:delete' // Delete posts
+  ],
+  permissionLabels: [
+    {
+      module: 'users',
+      zh: '用户管理',
+      en: 'User Management'
+    },
+    {
+      module: 'posts',
+      zh: '文章管理',
+      en: 'Posts Management'
+    }
+  ]
+}
+
+// Initialize Sumor OAuth
+await setupSumor(app, permissions)
+
+// Now your app has:
+// - OAuth routes: /api/oauth/authorize, /api/oauth/callback, etc.
+// - JWT middleware: Automatically validates tokens on protected routes
+// - req.sumor: OAuth service available in all request handlers
+// - req.jwtUser: User info from JWT token
+
+app.listen(3000, () => console.log('Server ready'))
+```
+
+### 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
+
+  res.json({
+    userId: user.userId,
+    roles: user.roles?.split(','),
+    permissions: user.permissions?.split(','),
+    verified: user.isVerified
+  })
+})
+
+// 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 })
+  }
+})
+```
+
+## 📚 API Reference
+
+### setupSumor(app, permissions)
+
+Initialize Sumor OAuth with your Express application.
+
+**Parameters:**
+
+- `app` (Express.Application) - Your Express app instance
+- `permissions` (Object) - Permission configuration:
+  - `permissions` (string[]) - List of available permissions
+  - `permissionLabels` (Array) - Human-readable labels for permission modules
+
+**Returns:** Promise<void>
+
+**Example:**
+
+```typescript
+const permissions = {
+  permissions: ['posts:view', 'posts:edit', 'posts:delete', 'users:view', 'users:create'],
+  permissionLabels: [
+    {
+      module: 'posts',
+      zh: '帖子管理',
+      en: 'Posts Management'
+    }
+  ]
+}
+await setupSumor(app, permissions)
+```
+
+### req.jwtUser
+
+Available in all route handlers after middleware initialization. Contains the user info from JWT token.
+
+**Properties:**
+
+- `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
+
+**Example:**
+
+```typescript
+app.get('/api/protected', (req: any, res) => {
+  const { userId, roles, permissions } = req.jwtUser
+  res.json({ userId, roles: roles?.split(','), permissions: permissions?.split(',') })
+})
+```
+
+### req.sumor (OAuthService)
+
+Available in all route handlers. Provides methods to call the OAuth provider's API.
+
+**Methods:**
+
+#### getUserInfo(userId)
+
+Get detailed user information from the OAuth provider.
+
+```typescript
+const userInfo = await req.sumor.getUserInfo('user123')
+// Returns: { userId, name, email, avatar, ... }
+```
+
+#### getUsersInfo(userIds)
+
+Get information for multiple users.
+
+```typescript
+const users = await req.sumor.getUsersInfo(['user1', 'user2'])
+// Returns: [{ userId, name, ... }, ...]
+```
+
+#### searchUsers(searchTerm, limit)
+
+Search for users by name or email.
+
+```typescript
+const results = await req.sumor.searchUsers('john', 20)
+// Returns: [{ userId, name, email, ... }, ...]
+```
+
+#### exchangeCode(grantType, code, redirectUri, codeVerifier)
+
+Exchange authorization code for tokens (internal use).
+
+```typescript
+const tokens = await req.sumor.exchangeCode(
+  'authorization_code',
+  authCode,
+  'http://localhost:3000/callback',
+  codeVerifier
+)
+// Returns: { accessToken, refreshToken, expiresIn, tokenType }
+```
+
+#### checkBlacklist(sessionId)
+
+Check if a session token is revoked.
+
+```typescript
+const isBlacklisted = await req.sumor.checkBlacklist(sessionId)
+```
+
+#### revokeSession(sessionId)
+
+Revoke (logout) a session.
+
+```typescript
+await req.sumor.revokeSession(sessionId)
+```
+
+### OAuth Routes
+
+Sumor automatically registers these routes:
+
+- `GET /api/oauth/info` - Get OAuth provider info and authorization URL (no auth required)
+- `GET /api/oauth/callback` - Handle OAuth provider callback with authorization code (no auth required)
+- `PUT /api/oauth/token` - Refresh access token (can use refreshToken from body or cookie)
+- `POST /api/oauth/logout` - Logout and revoke session (requires valid token)
+
+## 🔧 Configuration
+
+Sumor uses environment variables for configuration. The key is configuring the OAuth provider endpoint:
+
+```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
+
+# 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
+```
+
+## 📚 Usage Examples
+
+### Example 1: Protect Routes with Permission Checks
+
+```typescript
+app.post('/api/posts', (req: any, res) => {
+  // Check if user has permission
+  const permissions = req.jwtUser.permissions?.split(',') || []
+
+  if (!permissions.includes('posts:create')) {
+    return res.status(403).json({ error: 'Insufficient permissions' })
+  }
+
+  // Create post logic here
+  res.json({ postId: 123 })
+})
+```
+
+### Example 2: Multi-Tenant Support
+
+```typescript
+app.get('/api/tenant/users', (req: any, res) => {
+  const tenantId = req.jwtUser.tenantId
+
+  // Fetch users for the user's tenant
+  db.query('SELECT * FROM users WHERE tenant_id = ?', [tenantId]).then(users => res.json(users))
+})
+```
+
+### Example 3: Fetch Related User Data
+
+```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 })
+  }
+})
+```
+
+### Example 4: User Search with Pagination
+
+```typescript
+app.get('/api/search/users', async (req: any, res) => {
+  const { q, limit = 20 } = req.query
+
+  if (!q) {
+    return res.status(400).json({ error: 'Search term required' })
+  }
+
+  try {
+    const results = await req.sumor.searchUsers(q, limit)
+    res.json(results)
+  } catch (error) {
+    res.status(500).json({ error: error.message })
+  }
+})
+```
+
+## 🛡️ Security Considerations
+
+### Token Storage
+
+- 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
+
+### Permission Validation
+
+Always validate permissions on sensitive operations:
+
+```typescript
+const userPermissions = req.jwtUser.permissions?.split(',') || []
+
+if (!userPermissions.includes('users:edit')) {
+  return res.status(403).json({ error: 'User edit permission required' })
+}
+```
+
+### Session Revocation
+
+Logout invalidates tokens immediately:
+
+```typescript
+// On logout
+await req.sumor.revokeSession(req.jwtUser.jti)
+// Token is added to blacklist and becomes invalid
+```
+
+### CSRF Protection
+
+Implement CSRF tokens for state-changing operations:
+
+```typescript
+const csrf = require('csurf')
+const csrfProtection = csrf({ cookie: false })
+
+app.post('/api/posts', csrfProtection, (req: any, res) => {
+  // Handle POST with CSRF protection
+})
+```
+
+## 🐛 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`
+
+### "Unauthorized" on protected routes
+
+**Cause:** Missing or invalid JWT token in request
+
+**Solution:** Client must include Authorization header:
+
+```
+Authorization: Bearer <JWT_TOKEN>
+```
+
+### "Session not found" when revoking
+
+**Cause:** Session ID (jti) is invalid or already revoked
+
+**Solution:** Check that `req.jwtUser.jti` contains a valid session ID
+
+### Permission check always fails
+
+**Cause:** Permissions string format is incorrect
+
+**Solution:** Permissions are comma-separated strings. Parse correctly:
+
+```typescript
+const permissions = req.jwtUser.permissions?.split(',').map(p => p.trim()) || []
+```
+
+## 🔄 Architecture
+
+```
+┌──────────────────────────────────────┐
+│      Browser / Mobile Client         │
+└───────────────┬──────────────────────┘
+                │ (1) Click Login
+                ▼
+┌──────────────────────────────────────┐
+│    Your Express App (Port 3000)      │
+│  ┌────────────────────────────────┐  │
+│  │ GET /api/oauth/info            │  │ (2) Get OAuth URL
+│  │ 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
+```
+
+**Flow Steps:**
+
+1. User clicks "Login" on your app
+2. App calls `GET /api/oauth/info` to get OAuth provider URL
+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 ITS OAuth API
+6. Server verifies JWT signature using ITS 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`
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.
+
+## � License
+
+MIT License - see [LICENSE](LICENSE) for details
+
+## 📞 Support
+
+For issues, questions, or suggestions, please open an issue on GitHub.
+
+---
+
+Made with ❤️ by [Lycoo](https://lycoo.com)

package/dist/server/controllers/getAuthorizeUrlController.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 获取授权 URL 控制器
+ * GET /api/oauth/authorize
+ *
+ * 返回跳转到 ITS 的授权 URL，前端将用此 URL 进行重定向
+ */
+import { Request, Response } from 'express';
+export default function getAuthorizeUrlController(req: Request, res: Response): void;
+//# sourceMappingURL=getAuthorizeUrlController.d.ts.map

package/dist/server/controllers/getAuthorizeUrlController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAuthorizeUrlController.d.ts","sourceRoot":"","sources":["../../../server/controllers/getAuthorizeUrlController.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AA+D3C,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,QAgB5E"}

package/dist/server/controllers/getAuthorizeUrlController.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * 获取授权 URL 控制器
+ * GET /api/oauth/authorize
+ *
+ * 返回跳转到 ITS 的授权 URL，前端将用此 URL 进行重定向
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getAuthorizeUrlController;
+const crypto_1 = __importDefault(require("crypto"));
+const config_1 = __importDefault(require("../utils/config"));
+/**
+ * 生成 PKCE code_challenge 和 code_verifier
+ */
+function generateCodeChallenge() {
+    const codeVerifier = crypto_1.default.randomBytes(32).toString('hex');
+    const challenge = crypto_1.default
+        .createHash('sha256')
+        .update(codeVerifier)
+        .digest('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+    return {
+        codeChallenge: challenge,
+        codeVerifier: codeVerifier
+    };
+}
+/**
+ * 生成随机 state 参数
+ */
+function generateState() {
+    return crypto_1.default.randomBytes(32).toString('hex');
+}
+/**
+ * 生成授权 URL
+ * RFC 6749 §4.1.1，支持 PKCE（RFC 7636）用于增强安全性
+ */
+function generateAuthorizationUrl() {
+    const { codeChallenge, codeVerifier } = generateCodeChallenge();
+    const uri = config_1.default.redirectUri;
+    if (!uri || uri.trim() === '') {
+        throw new Error('redirectUri 为空或未配置，无法生成授权 URL');
+    }
+    const randomState = generateState();
+    const encryptedState = Buffer.from(codeVerifier).toString('base64') + ':' + randomState;
+    const params = new URLSearchParams({
+        clientKey: config_1.default.clientKey,
+        redirectUri: uri,
+        responseType: 'code',
+        scope: 'profile',
+        state: encryptedState,
+        codeChallenge: codeChallenge,
+        codeChallengeMethod: 'S256'
+    });
+    const authUrl = `${config_1.default.baseUrl}/authorize?${params.toString()}`;
+    return authUrl;
+}
+function getAuthorizeUrlController(req, res) {
+    try {
+        const authUrl = generateAuthorizationUrl();
+        res.json({
+            code: 'OK',
+            data: {
+                authUrl
+            }
+        });
+    }
+    catch (error) {
+        res.status(500).json({
+            code: 'ERROR',
+            message: error.message
+        });
+    }
+}
+//# sourceMappingURL=getAuthorizeUrlController.js.map

package/dist/server/controllers/getAuthorizeUrlController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAuthorizeUrlController.js","sourceRoot":"","sources":["../../../server/controllers/getAuthorizeUrlController.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AAkEH,4CAgBC;AAhFD,oDAA2B;AAE3B,6DAAyC;AAEzC;;GAEG;AACH,SAAS,qBAAqB;IAI5B,MAAM,YAAY,GAAG,gBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC3D,MAAM,SAAS,GAAG,gBAAM;SACrB,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CAAC,YAAY,CAAC;SACpB,MAAM,CAAC,QAAQ,CAAC;SAChB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAEpB,OAAO;QACL,aAAa,EAAE,SAAS;QACxB,YAAY,EAAE,YAAY;KAC3B,CAAA;AACH,CAAC;AAED;;GAEG;AACH,SAAS,aAAa;IACpB,OAAO,gBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,wBAAwB;IAC/B,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,qBAAqB,EAAE,CAAA;IAE/D,MAAM,GAAG,GAAG,gBAAW,CAAC,WAAW,CAAA;IAEnC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;IAClD,CAAC;IAED,MAAM,WAAW,GAAG,aAAa,EAAE,CAAA;IACnC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,GAAG,GAAG,WAAW,CAAA;IAEvF,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,SAAS,EAAE,gBAAW,CAAC,SAAS;QAChC,WAAW,EAAE,GAAG;QAChB,YAAY,EAAE,MAAM;QACpB,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,cAAc;QACrB,aAAa,EAAE,aAAa;QAC5B,mBAAmB,EAAE,MAAM;KAC5B,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,GAAG,gBAAW,CAAC,OAAO,cAAc,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAA;IAEvE,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,SAAwB,yBAAyB,CAAC,GAAY,EAAE,GAAa;IAC3E,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,wBAAwB,EAAE,CAAA;QAE1C,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,OAAO;aACR;SACF,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAA;IACJ,CAAC;AACH,CAAC"}

package/dist/server/controllers/infoController.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OAuth 信息控制器
+ * 获取 ITS 端点信息
+ */
+/**
+ * 获取 ITS 配置信息
+ * GET /api/oauth/info
+ *
+ * 无需认证 - 在 JWT 中间件之前调用
+ */
+export declare const getItsInfo: (req: any, res: any, next: any) => Promise<void>;
+//# sourceMappingURL=infoController.d.ts.map

package/dist/server/controllers/infoController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infoController.d.ts","sourceRoot":"","sources":["../../../server/controllers/infoController.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiEH;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAU,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,kBAc7D,CAAA"}

package/dist/server/controllers/infoController.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * OAuth 信息控制器
+ * 获取 ITS 端点信息
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getItsInfo = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const config_1 = __importDefault(require("../utils/config"));
+/**
+ * 生成 PKCE code_challenge 和 code_verifier
+ */
+function generateCodeChallenge() {
+    const codeVerifier = crypto_1.default.randomBytes(32).toString('hex');
+    const challenge = crypto_1.default
+        .createHash('sha256')
+        .update(codeVerifier)
+        .digest('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+    return {
+        codeChallenge: challenge,
+        codeVerifier: codeVerifier
+    };
+}
+/**
+ * 生成随机 state 参数
+ */
+function generateState() {
+    return crypto_1.default.randomBytes(32).toString('hex');
+}
+/**
+ * 生成授权 URL
+ * RFC 6749 §4.1.1，支持 PKCE（RFC 7636）用于增强安全性
+ */
+function generateAuthorizationUrl() {
+    const { codeChallenge, codeVerifier } = generateCodeChallenge();
+    const uri = config_1.default.redirectUri;
+    if (!uri || uri.trim() === '') {
+        throw new Error('redirectUri 为空或未配置，无法生成授权 URL');
+    }
+    const randomState = generateState();
+    const encryptedState = Buffer.from(codeVerifier).toString('base64') + ':' + randomState;
+    const params = new URLSearchParams({
+        clientKey: config_1.default.clientKey,
+        redirectUri: uri,
+        responseType: 'code',
+        scope: 'profile',
+        state: encryptedState,
+        codeChallenge: codeChallenge,
+        codeChallengeMethod: 'S256'
+    });
+    const authUrl = `${config_1.default.baseUrl}/authorize?${params.toString()}`;
+    return authUrl;
+}
+/**
+ * 获取 ITS 配置信息
+ * GET /api/oauth/info
+ *
+ * 无需认证 - 在 JWT 中间件之前调用
+ */
+const getItsInfo = async (req, res, next) => {
+    try {
+        const oauthAuthorizeUrl = generateAuthorizationUrl();
+        res.json({
+            code: 'OK',
+            data: {
+                endpoint: req.config.its?.endpoint,
+                authorizeUrl: oauthAuthorizeUrl
+            }
+        });
+    }
+    catch (error) {
+        next(error);
+    }
+};
+exports.getItsInfo = getItsInfo;
+//# sourceMappingURL=infoController.js.map

package/dist/server/controllers/infoController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infoController.js","sourceRoot":"","sources":["../../../server/controllers/infoController.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;AAEH,oDAA2B;AAC3B,6DAAyC;AAEzC;;GAEG;AACH,SAAS,qBAAqB;IAI5B,MAAM,YAAY,GAAG,gBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC3D,MAAM,SAAS,GAAG,gBAAM;SACrB,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CAAC,YAAY,CAAC;SACpB,MAAM,CAAC,QAAQ,CAAC;SAChB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAEpB,OAAO;QACL,aAAa,EAAE,SAAS;QACxB,YAAY,EAAE,YAAY;KAC3B,CAAA;AACH,CAAC;AAED;;GAEG;AACH,SAAS,aAAa;IACpB,OAAO,gBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,wBAAwB;IAC/B,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,qBAAqB,EAAE,CAAA;IAE/D,MAAM,GAAG,GAAG,gBAAW,CAAC,WAAW,CAAA;IAEnC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;IAClD,CAAC;IAED,MAAM,WAAW,GAAG,aAAa,EAAE,CAAA;IACnC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,GAAG,GAAG,WAAW,CAAA;IAEvF,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,SAAS,EAAE,gBAAW,CAAC,SAAS;QAChC,WAAW,EAAE,GAAG;QAChB,YAAY,EAAE,MAAM;QACpB,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,cAAc;QACrB,aAAa,EAAE,aAAa;QAC5B,mBAAmB,EAAE,MAAM;KAC5B,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,GAAG,gBAAW,CAAC,OAAO,cAAc,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAA;IAEvE,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACI,MAAM,UAAU,GAAG,KAAK,EAAE,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;IAChE,IAAI,CAAC;QACH,MAAM,iBAAiB,GAAG,wBAAwB,EAAE,CAAA;QAEpD,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ;gBAClC,YAAY,EAAE,iBAAiB;aAChC;SACF,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAdY,QAAA,UAAU,cActB"}

package/dist/server/controllers/logoutController.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OAuth 用户登出控制器
+ */
+import { Response } from 'express';
+/**
+ * 用户登出
+ * POST /api/oauth/logout
+ *
+ * 撤销 OAuth Token（可选）并清理会话
+ */
+export declare function logout(req: Record<string, any>, res: Response): Promise<Response<any, Record<string, any>>>;
+//# sourceMappingURL=logoutController.d.ts.map

package/dist/server/controllers/logoutController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logoutController.d.ts","sourceRoot":"","sources":["../../../server/controllers/logoutController.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAIlC;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,QAAQ,+CAsDnE"}