@55387.ai/uniauth-server 1.2.1 → 1.2.4

package/README.md

@@ -1,244 +1,151 @@
 # @55387.ai/uniauth-server
 
-UniAuth 后端 SDK，用于在 Node.js 后端服务中验证用户令牌。
+> UniAuth Backend SDK — Token verification & middleware for Node.js servers.
+>
+> UniAuth 后端 SDK — Node.js 服务端令牌验证和中间件。
 
-## 安装
+**Version / 版本:** 1.2.2
+
+## Install / 安装
 
 ```bash
 npm install @55387.ai/uniauth-server
-# or
+# or / 或
 pnpm add @55387.ai/uniauth-server
 ```
 
-## 快速开始
+## Quick Start / 快速开始
 
 ```typescript
 import { UniAuthServer } from '@55387.ai/uniauth-server';
 
 const auth = new UniAuthServer({
   baseUrl: 'https://sso.55387.xyz',
-  clientId: 'your-client-id',
-  clientSecret: 'your-client-secret',
+  clientId: process.env.UNIAUTH_CLIENT_ID!,
+  clientSecret: process.env.UNIAUTH_CLIENT_SECRET!,
 });
 
-// 验证令牌
+// Verify token / 验证令牌
 const payload = await auth.verifyToken(accessToken);
 console.log('User ID:', payload.sub);
 ```
 
-## Express 中间件
+## Middleware / 中间件
+
+### Express
 
 ```typescript
 import express from 'express';
-import { UniAuthServer } from '@55387.ai/uniauth-server';
-
 const app = express();
-const auth = new UniAuthServer({ ... });
 
-// 保护 API 路由
 app.use('/api/*', auth.middleware());
 
-// 在路由中使用用户信息
 app.get('/api/profile', (req, res) => {
   res.json({ user: req.user, payload: req.authPayload });
 });
 ```
 
-## Hono 中间件
+### Hono
 
 ```typescript
 import { Hono } from 'hono';
-import { UniAuthServer } from '@55387.ai/uniauth-server';
-
 const app = new Hono();
-const auth = new UniAuthServer({ ... });
 
-// 保护 API 路由
 app.use('/api/*', auth.honoMiddleware());
 
-// 在路由中使用用户信息
 app.get('/api/profile', (c) => {
-  const user = c.get('user');
-  return c.json({ user });
+  return c.json({ user: c.get('user') });
 });
 ```
 
-## SSO OAuth2 后端代理登录
+## SSO Backend Proxy / SSO 后端代理
 
-当应用配置为 **Confidential Client**（机密客户端）时，需要通过后端完成 Token 交换。
+When your app is a **Confidential Client**, token exchange must happen on the server.
 
-### 流程概述
+当应用配置为 **机密客户端** 时，Token 交换必须在服务端完成。
 
 ```
-用户 → 前端 → /api/auth/login → 后端生成授权 URL → 重定向到 SSO
-                                                    ↓
-用户 ← 前端 ← /                ← 后端设置 Cookie ← SSO 回调到 /api/auth/callback
-                                                    ↑
-                                        后端用 client_secret 交换 Token
+User → Frontend → /api/auth/login → Backend → redirect to UniAuth SSO
+                                                      ↓
+User ← Frontend ← redirect ← Backend (set cookie) ← SSO callback
+                                      ↑
+                         Backend exchanges code with client_secret
 ```
 
-### API 端点
-
-| 端点 | URL |
-|------|-----|
-| 授权端点 | `https://sso.55387.xyz/api/v1/oauth2/authorize` |
-| Token 端点 | `https://sso.55387.xyz/api/v1/oauth2/token` |
-| 用户信息端点 | `https://sso.55387.xyz/api/v1/oauth2/userinfo` |
-
-### 实现示例（Hono）
-
-```typescript
-import { Hono } from 'hono';
-import { setCookie, getCookie } from 'hono/cookie';
-
-const app = new Hono();
-
-// 登录端点 - 重定向到 SSO
-app.get('/api/auth/login', (c) => {
-  const origin = c.req.header('origin') || 'http://localhost:3000';
-  const redirectUri = `${origin}/api/auth/callback`;
-  
-  const params = new URLSearchParams({
-    client_id: process.env.UNIAUTH_CLIENT_ID,
-    redirect_uri: redirectUri,
-    response_type: 'code',
-    scope: 'openid profile email phone',
-    state: generateRandomState(),  // 生成随机 state 防止 CSRF
-  });
-  
-  return c.redirect(`https://sso.55387.xyz/api/v1/oauth2/authorize?${params}`);
-});
-
-// 回调端点 - 交换 Token
-app.get('/api/auth/callback', async (c) => {
-  const code = c.req.query('code');
-  const origin = c.req.header('referer')?.replace(/\/api\/auth\/callback.*$/, '') || 'http://localhost:3000';
-  
-  // 用授权码交换 Token
-  const response = await fetch('https://sso.55387.xyz/api/v1/oauth2/token', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      client_id: process.env.UNIAUTH_CLIENT_ID,
-      client_secret: process.env.UNIAUTH_CLIENT_SECRET,
-      code,
-      grant_type: 'authorization_code',
-      redirect_uri: `${origin}/api/auth/callback`,
-    }),
-  });
-  
-  const { access_token, id_token } = await response.json();
-  
-  // 将 Token 存储到 httpOnly Cookie
-  setCookie(c, 'auth_token', id_token, {
-    httpOnly: true,
-    secure: true,
-    sameSite: 'Lax',
-    maxAge: 60 * 60 * 24 * 7,  // 7 天
-  });
-  
-  return c.redirect('/');
-});
-
-// 检查登录状态
-app.get('/api/auth/status', async (c) => {
-  const token = getCookie(c, 'auth_token');
-  if (!token) {
-    return c.json({ authenticated: false });
-  }
-  
-  // 验证 Token
-  try {
-    const payload = await auth.verifyToken(token);
-    return c.json({ authenticated: true, userId: payload.sub });
-  } catch {
-    return c.json({ authenticated: false });
-  }
-});
-```
+See full implementation: [AI Integration Guide](../../docs/AI_INTEGRATION_GUIDE.md#2b-backend-proxy-confidential-client)
 
-### 前端调用
+完整实现见: [集成指南](../../docs/AI_INTEGRATION_GUIDE.md#2b-backend-proxy-confidential-client)
 
-```typescript
-// 触发登录
-const handleLogin = () => {
-  window.location.href = '/api/auth/login';
-};
-
-// 检查登录状态
-const checkAuth = async () => {
-  const response = await fetch('/api/auth/status', { credentials: 'include' });
-  const data = await response.json();
-  return data.authenticated;
-};
-```
+## Token Introspection / 令牌内省
 
-## OAuth2 Token Introspection (RFC 7662)
+RFC 7662 compliant token introspection:
 
 ```typescript
-// 内省令牌（资源服务器标准验证方式）
 const result = await auth.introspectToken(accessToken);
 
 if (result.active) {
-  console.log('Token 有效');
-  console.log('用户:', result.sub);
-  console.log('权限:', result.scope);
-} else {
-  console.log('Token 无效或已过期');
+  console.log('User:', result.sub);
+  console.log('Scope:', result.scope);
 }
 ```
 
-## API 参考
+## API Reference / API 参考
 
-### 初始化选项
+### Config / 配置
 
 ```typescript
 interface UniAuthServerConfig {
-  baseUrl: string;        // UniAuth 服务地址
-  clientId: string;       // OAuth2 客户端 ID
-  clientSecret: string;   // OAuth2 客户端密钥
-  jwtPublicKey?: string;  // JWT 公钥（用于本地验证）
+  baseUrl: string;        // UniAuth server URL
+  clientId: string;       // OAuth2 client ID
+  clientSecret: string;   // OAuth2 client secret
+  jwtPublicKey?: string;  // JWT public key (local verification)
 }
 ```
 
-### 方法
+### Methods / 方法
 
-| 方法 | 说明 |
-|------|------|
-| `verifyToken(token)` | 验证访问令牌 |
-| `introspectToken(token)` | RFC 7662 令牌内省 |
-| `isTokenActive(token)` | 检查令牌是否有效 |
-| `getUser(userId)` | 获取用户信息 |
-| `middleware()` | Express/Connect 中间件 |
-| `honoMiddleware()` | Hono 中间件 |
-| `clearCache()` | 清除令牌缓存 |
+| Method | Description / 说明 |
+|--------|-----------|
+| `verifyToken(token)` | Verify access token / 验证访问令牌 |
+| `introspectToken(token)` | RFC 7662 introspection / 令牌内省 |
+| `isTokenActive(token)` | Check if token is active / 检查令牌状态 |
+| `getUser(userId)` | Get user info / 获取用户信息 |
+| `middleware()` | Express middleware / Express 中间件 |
+| `honoMiddleware()` | Hono middleware / Hono 中间件 |
+| `clearCache()` | Clear token cache / 清除令牌缓存 |
 
-### 类型
+### Token Verification Flow / 令牌验证流程
+
+```
+verifyToken(token)
+  │
+  ├─ 1. POST /api/v1/auth/verify (App Key + Secret)
+  │     ↓ success → return payload
+  │     ↓ 404 or network error
+  │
+  ├─ 2. POST /api/v1/oauth2/introspect (Basic Auth, RFC 7662)
+  │     ↓ active:true → return payload
+  │     ↓ fail
+  │
+  └─ 3. Local JWT verification (if jwtPublicKey configured)
+```
+
+### Types / 类型
 
 ```typescript
 interface TokenPayload {
-  sub: string;           // 用户 ID
-  iss?: string;          // 签发者
-  aud?: string | string[]; // 受众
-  exp: number;           // 过期时间
-  iat: number;           // 签发时间
-  scope?: string;        // 权限范围
-  phone?: string;        // 手机号
-  email?: string;        // 邮箱
-}
-
-interface UserInfo {
-  id: string;
-  phone?: string;
-  email?: string;
-  nickname?: string;
-  avatar_url?: string;
-  phone_verified?: boolean;
-  email_verified?: boolean;
+  sub: string;              // User ID
+  iss?: string;             // Issuer
+  aud?: string | string[];  // Audience
+  exp: number;              // Expiration
+  iat: number;              // Issued at
+  scope?: string;           // Scopes
+  phone?: string;           // Phone number
+  email?: string;           // Email
 }
 ```
 
-## 错误处理
+## Error Handling / 错误处理
 
 ```typescript
 import { ServerAuthError, ServerErrorCode } from '@55387.ai/uniauth-server';
@@ -248,17 +155,31 @@ try {
 } catch (error) {
   if (error instanceof ServerAuthError) {
     switch (error.code) {
-      case ServerErrorCode.INVALID_TOKEN:
-        // 令牌无效
-        break;
-      case ServerErrorCode.TOKEN_EXPIRED:
-        // 令牌已过期
-        break;
+      case ServerErrorCode.INVALID_TOKEN:  // Invalid / 令牌无效
+      case ServerErrorCode.TOKEN_EXPIRED:  // Expired / 令牌过期
     }
   }
 }
 ```
 
+## 🤖 AI Agent Prompts / AI 智能体提示词
+
+This package includes an AI-ready integration prompt. Copy it into your AI coding assistant (Claude, Cursor, Copilot, etc.) to generate a complete backend protection setup automatically.
+
+本包附带 AI 集成提示词。将其复制到 AI 编程助手中，即可自动生成完整的后端保护代码。
+
+```bash
+# After install, find the prompt at:
+# 安装后，提示词文件位于：
+cat node_modules/@55387.ai/uniauth-server/ai-prompts/backend-protection.md
+```
+
+> [!TIP]
+> Replace placeholders like `YOUR_UNIAUTH_URL` and `YOUR_CLIENT_SECRET` before pasting into your AI assistant.
+> 粘贴到 AI 助手前，请替换 `YOUR_UNIAUTH_URL` 和 `YOUR_CLIENT_SECRET` 等占位符。
+
+See all prompts: [docs/ai-prompts/](../../docs/ai-prompts/README.md)
+
 ## License
 
 MIT

package/ai-prompts/backend-protection.md

@@ -0,0 +1,197 @@
+# 🤖 AI Prompt: Backend API Protection
+
+> Copy everything below the line and paste into your AI coding assistant.
+>
+> 复制下方分割线以下的全部内容，粘贴到你的 AI 编程助手中。
+
+---
+
+You are an expert Node.js/TypeScript backend developer. Help me protect my API routes using UniAuth token verification with the official `@55387.ai/uniauth-server` SDK.
+
+## Project Context
+
+- **UniAuth Server URL**: `YOUR_UNIAUTH_URL` (e.g. `https://auth.55387.xyz`)
+- **Client ID**: `YOUR_CLIENT_ID`
+- **Client Secret**: `YOUR_CLIENT_SECRET`
+- **Framework**: Express / Hono / Next.js API Routes (choose based on my project)
+
+## SDK Reference
+
+### Installation
+
+```bash
+npm install @55387.ai/uniauth-server
+```
+
+### UniAuthServer Class
+
+```typescript
+import { UniAuthServer } from '@55387.ai/uniauth-server';
+
+const auth = new UniAuthServer({
+  baseUrl: 'YOUR_UNIAUTH_URL',
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  jwtPublicKey: process.env.JWT_PUBLIC_KEY, // optional, for local verification
+});
+```
+
+### Core Methods
+
+```typescript
+// Verify an access token (remote → introspection → local JWT fallback)
+const payload = await auth.verifyToken(accessToken);
+// Returns: TokenPayload { sub, iss, aud, iat, exp, scope, azp, phone, email }
+
+// Token introspection (RFC 7662)
+const result = await auth.introspectToken(token, 'access_token');
+// Returns: IntrospectionResult { active, scope, client_id, sub, exp, ... }
+
+// Check if token is active
+const isActive = await auth.isTokenActive(token);
+
+// Get user info by ID
+const user = await auth.getUser(userId);
+// Returns: UserInfo { id, phone, email, nickname, avatar_url, ... }
+
+// Cache management
+auth.clearCache();
+auth.getCacheStats(); // { size, entries }
+```
+
+### Express Middleware
+
+```typescript
+import express from 'express';
+
+const app = express();
+
+// Protect all /api routes
+app.use('/api/*', auth.middleware());
+
+// Access user info in route handlers
+app.get('/api/profile', (req, res) => {
+  // req.authPayload — TokenPayload (always available)
+  // req.user — UserInfo (fetched automatically, may be undefined)
+  res.json({ user: req.user, payload: req.authPayload });
+});
+```
+
+### Hono Middleware
+
+```typescript
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+// Protect all /api routes
+app.use('/api/*', auth.honoMiddleware());
+
+// Access user info in route handlers
+app.get('/api/profile', (c) => {
+  const user = c.get('user');           // UserInfo
+  const payload = c.get('authPayload'); // TokenPayload
+  return c.json({ user, payload });
+});
+```
+
+### Next.js API Route Protection
+
+```typescript
+// middleware.ts or in each API route
+import { UniAuthServer } from '@55387.ai/uniauth-server';
+
+const auth = new UniAuthServer({
+  baseUrl: process.env.UNIAUTH_URL!,
+  clientId: process.env.UNIAUTH_CLIENT_ID!,
+  clientSecret: process.env.UNIAUTH_CLIENT_SECRET!,
+});
+
+export async function protectRoute(req: Request) {
+  const authHeader = req.headers.get('authorization');
+  if (!authHeader?.startsWith('Bearer ')) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+  const payload = await auth.verifyToken(authHeader.substring(7));
+  return payload; // Use in your handler
+}
+```
+
+### Types
+
+```typescript
+interface TokenPayload {
+  sub: string;       // User ID or Client ID (for M2M tokens)
+  iss?: string;      // Issuer
+  aud?: string | string[];
+  iat: number;       // Issued at
+  exp: number;       // Expiration
+  scope?: string;    // Scopes (space-separated)
+  azp?: string;      // Authorized party (client_id)
+  phone?: string;
+  email?: string;
+}
+
+interface UserInfo {
+  id: string;
+  phone?: string | null;
+  email?: string | null;
+  nickname?: string | null;
+  avatar_url?: string | null;
+  phone_verified?: boolean;
+  email_verified?: boolean;
+  created_at?: string;
+  updated_at?: string;
+}
+
+// Error handling
+import { ServerAuthError, ServerErrorCode } from '@55387.ai/uniauth-server';
+
+try {
+  await auth.verifyToken(token);
+} catch (error) {
+  if (error instanceof ServerAuthError) {
+    // error.code: 'INVALID_TOKEN' | 'TOKEN_EXPIRED' | 'UNAUTHORIZED' | ...
+    // error.statusCode: 401
+    // error.message: human-readable message
+  }
+}
+```
+
+### Error Codes
+
+| Code | Meaning |
+|------|---------|
+| `INVALID_TOKEN` | Token is malformed or invalid |
+| `TOKEN_EXPIRED` | Token has expired |
+| `VERIFICATION_FAILED` | Remote verification failed |
+| `USER_NOT_FOUND` | User ID from token not found |
+| `UNAUTHORIZED` | Missing or invalid Authorization header |
+| `NO_PUBLIC_KEY` | JWT public key not configured for local verification |
+| `NETWORK_ERROR` | Cannot reach UniAuth server |
+
+## Requirements
+
+1. **Middleware Setup**: Configure `UniAuthServer` and apply middleware to protect API routes.
+
+2. **Public vs Protected**: Some routes should be public (e.g. health check, login). Apply middleware selectively.
+
+3. **Error Handling**: Return proper JSON error responses with appropriate HTTP status codes. Never expose internal errors.
+
+4. **M2M Support**: Handle both user tokens (`sub` = user ID) and machine-to-machine tokens (`sub` = client ID, no user info).
+
+5. **CORS**: Configure CORS to allow requests from your frontend origin with `Authorization` header.
+
+6. **Rate Limiting**: Add basic rate limiting to prevent abuse.
+
+7. **Environment Variables**:
+```env
+UNIAUTH_URL=YOUR_UNIAUTH_URL
+UNIAUTH_CLIENT_ID=YOUR_CLIENT_ID
+UNIAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET
+JWT_PUBLIC_KEY=optional_for_local_verification
+```
+
+8. **Testing**: Include unit tests using Vitest. Mock the `UniAuthServer` for testing.
+
+Generate the complete implementation based on my project's framework.

package/dist/index.cjs

@@ -113,6 +113,24 @@ var UniAuthServer = class {
       if (error instanceof ServerAuthError) {
         throw error;
       }
+      try {
+        const introspectionResult = await this.introspectToken(token);
+        if (introspectionResult.active) {
+          const payload = {
+            sub: introspectionResult.sub || "",
+            iss: introspectionResult.iss || "",
+            aud: introspectionResult.aud || "",
+            iat: introspectionResult.iat || 0,
+            exp: introspectionResult.exp || 0,
+            scope: introspectionResult.scope,
+            azp: introspectionResult.client_id
+          };
+          const cacheExpiry = Math.min(payload.exp * 1e3, Date.now() + 60 * 1e3);
+          this.tokenCache.set(token, { payload, expiresAt: cacheExpiry });
+          return payload;
+        }
+      } catch {
+      }
       if (this.config.jwtPublicKey) {
         return this.verifyTokenLocally(token);
       }

package/dist/index.js

@@ -76,6 +76,24 @@ var UniAuthServer = class {
       if (error instanceof ServerAuthError) {
         throw error;
       }
+      try {
+        const introspectionResult = await this.introspectToken(token);
+        if (introspectionResult.active) {
+          const payload = {
+            sub: introspectionResult.sub || "",
+            iss: introspectionResult.iss || "",
+            aud: introspectionResult.aud || "",
+            iat: introspectionResult.iat || 0,
+            exp: introspectionResult.exp || 0,
+            scope: introspectionResult.scope,
+            azp: introspectionResult.client_id
+          };
+          const cacheExpiry = Math.min(payload.exp * 1e3, Date.now() + 60 * 1e3);
+          this.tokenCache.set(token, { payload, expiresAt: cacheExpiry });
+          return payload;
+        }
+      } catch {
+      }
       if (this.config.jwtPublicKey) {
         return this.verifyTokenLocally(token);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@55387.ai/uniauth-server",
-    "version": "1.2.1",
+    "version": "1.2.4",
     "description": "UniAuth Server SDK - Token verification for Node.js backends",
     "type": "module",
     "main": "./dist/index.js",
@@ -9,7 +9,7 @@
     "files": [
         "dist",
         "README.md",
-        "INTEGRATION.md"
+        "ai-prompts"
     ],
     "exports": {
         ".": {
@@ -45,4 +45,4 @@
         "jwt",
         "sdk"
     ]
-}
+}