@55387.ai/uniauth-server 1.2.0 → 1.2.3

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('/');
-});
+See full implementation: [AI Integration Guide](../../docs/AI_INTEGRATION_GUIDE.md#2b-backend-proxy-confidential-client)
 
-// 检查登录状态
-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 });
-  }
-});
-```
+完整实现见: [集成指南](../../docs/AI_INTEGRATION_GUIDE.md#2b-backend-proxy-confidential-client)
 
-### 前端调用
+## Token Introspection / 令牌内省
 
-```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;
-};
-```
-
-## 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 / 方法
+
+| 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 / 清除令牌缓存 |
 
-| 方法 | 说明 |
-|------|------|
-| `verifyToken(token)` | 验证访问令牌 |
-| `introspectToken(token)` | RFC 7662 令牌内省 |
-| `isTokenActive(token)` | 检查令牌是否有效 |
-| `getUser(userId)` | 获取用户信息 |
-| `middleware()` | Express/Connect 中间件 |
-| `honoMiddleware()` | Hono 中间件 |
-| `clearCache()` | 清除令牌缓存 |
+### 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,12 +155,8 @@ 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 / 令牌过期
     }
   }
 }

package/package.json

@@ -1,11 +1,15 @@
 {
     "name": "@55387.ai/uniauth-server",
-    "version": "1.2.0",
+    "version": "1.2.3",
     "description": "UniAuth Server SDK - Token verification for Node.js backends",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.ts",
+    "files": [
+        "dist",
+        "README.md"
+    ],
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",

package/src/index.ts

@@ -1,581 +0,0 @@
-/**
- * UniAuth Server SDK
- * 统一认证后端 SDK
- *
- * Usage:
- * ```typescript
- * import { UniAuthServer } from '@55387.ai/uniauth-server';
- *
- * const auth = new UniAuthServer({
- *   baseUrl: 'https://auth.example.com',
- *   clientId: 'your-client-id',
- *   clientSecret: 'your-client-secret',
- * });
- *
- * // Verify token
- * const payload = await auth.verifyToken(accessToken);
- *
- * // Introspect token (RFC 7662)
- * const introspectResult = await auth.introspectToken(accessToken);
- *
- * // Express middleware
- * app.use('/api/*', auth.middleware());
- *
- * // Hono middleware
- * app.use('/api/*', auth.honoMiddleware());
- * ```
- */
-
-import * as jose from 'jose';
-
-// ============================================
-// Types
-// ============================================
-
-export interface UniAuthServerConfig {
-    /** API base URL */
-    baseUrl: string;
-    /** OAuth2 Client ID (also used as appKey) */
-    clientId: string;
-    /** OAuth2 Client Secret (also used as appSecret) */
-    clientSecret: string;
-    /** JWT public key (optional, for local verification) */
-    jwtPublicKey?: string;
-    /** @deprecated Use clientId instead */
-    appKey?: string;
-    /** @deprecated Use clientSecret instead */
-    appSecret?: string;
-}
-
-export interface TokenPayload {
-    /** User ID or Client ID (for M2M) */
-    sub: string;
-    /** Issuer */
-    iss?: string;
-    /** Audience */
-    aud?: string | string[];
-    /** Issued at timestamp */
-    iat: number;
-    /** Expiration timestamp */
-    exp: number;
-    /** Scopes */
-    scope?: string;
-    /** Authorized party (client_id that requested this token) */
-    azp?: string;
-    /** Phone number (optional) */
-    phone?: string;
-    /** Email address (optional) */
-    email?: string;
-}
-
-export 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;
-}
-
-export interface VerifyResult {
-    valid: boolean;
-    payload?: TokenPayload;
-    error?: string;
-}
-
-/**
- * RFC 7662 Token Introspection Response
- * 令牌内省响应
- */
-export interface IntrospectionResult {
-    /** Whether the token is active */
-    active: boolean;
-    /** Scopes associated with this token */
-    scope?: string;
-    /** Client ID that requested the token */
-    client_id?: string;
-    /** Username or user identifier */
-    username?: string;
-    /** Token type (usually "Bearer") */
-    token_type?: string;
-    /** Expiration timestamp */
-    exp?: number;
-    /** Issued at timestamp */
-    iat?: number;
-    /** Not before timestamp */
-    nbf?: number;
-    /** Subject (user ID or client ID) */
-    sub?: string;
-    /** Audience */
-    aud?: string | string[];
-    /** Issuer */
-    iss?: string;
-    /** JWT ID */
-    jti?: string;
-}
-
-/**
- * Error codes for UniAuth Server SDK
- * UniAuth 服务端 SDK 错误码
- */
-export const ServerErrorCode = {
-    INVALID_TOKEN: 'INVALID_TOKEN',
-    TOKEN_EXPIRED: 'TOKEN_EXPIRED',
-    VERIFICATION_FAILED: 'VERIFICATION_FAILED',
-    USER_NOT_FOUND: 'USER_NOT_FOUND',
-    UNAUTHORIZED: 'UNAUTHORIZED',
-    NO_PUBLIC_KEY: 'NO_PUBLIC_KEY',
-    NETWORK_ERROR: 'NETWORK_ERROR',
-    INTERNAL_ERROR: 'INTERNAL_ERROR',
-} as const;
-
-export type ServerErrorCodeType = typeof ServerErrorCode[keyof typeof ServerErrorCode];
-
-/**
- * Custom error class for server SDK
- * 服务端 SDK 自定义错误类
- */
-export class ServerAuthError extends Error {
-    code: ServerErrorCodeType | string;
-    statusCode: number;
-
-    constructor(code: ServerErrorCodeType | string, message: string, statusCode: number = 401) {
-        super(message);
-        this.name = 'ServerAuthError';
-        this.code = code;
-        this.statusCode = statusCode;
-
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, ServerAuthError);
-        }
-    }
-}
-
-// API Response types
-interface ApiErrorResponse {
-    success: false;
-    error?: {
-        code?: string;
-        message?: string;
-    };
-}
-
-interface ApiSuccessResponse<T> {
-    success: true;
-    data: T;
-}
-
-// Express-compatible request/response types
-interface ExpressRequest {
-    headers: Record<string, string | string[] | undefined>;
-    user?: UserInfo;
-    authPayload?: TokenPayload;
-}
-
-interface ExpressResponse {
-    status(code: number): ExpressResponse;
-    json(data: unknown): void;
-}
-
-type NextFunction = (error?: Error) => void;
-
-// Hono-compatible types
-interface HonoContext {
-    req: {
-        header(name: string): string | undefined;
-    };
-    set(key: string, value: unknown): void;
-    get(key: string): unknown;
-    json(data: unknown, status?: number): Response;
-}
-
-type HonoMiddlewareHandler = (c: HonoContext, next: () => Promise<void>) => Promise<Response | void>;
-
-/**
- * UniAuth Server SDK
- * 统一认证后端 SDK
- */
-export class UniAuthServer {
-    private config: UniAuthServerConfig;
-    private tokenCache: Map<string, { payload: TokenPayload; expiresAt: number }> = new Map();
-
-    constructor(config: UniAuthServerConfig) {
-        // Support both new naming (clientId/clientSecret) and legacy (appKey/appSecret)
-        this.config = {
-            ...config,
-            clientId: config.clientId || config.appKey || '',
-            clientSecret: config.clientSecret || config.appSecret || '',
-        };
-    }
-
-    // ============================================
-    // Token Verification
-    // ============================================
-
-    /**
-     * Verify access token
-     * 验证访问令牌
-     *
-     * @param token - JWT access token
-     * @returns Token payload if valid
-     * @throws ServerAuthError if token is invalid
-     */
-    async verifyToken(token: string): Promise<TokenPayload> {
-        // Check cache first
-        const cached = this.tokenCache.get(token);
-        if (cached && cached.expiresAt > Date.now()) {
-            return cached.payload;
-        }
-
-        try {
-            // Verify with remote endpoint
-            const response = await fetch(`${this.config.baseUrl}/api/v1/auth/verify`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'X-App-Key': this.config.clientId,
-                    'X-App-Secret': this.config.clientSecret,
-                },
-                body: JSON.stringify({ token }),
-            });
-
-            if (!response.ok) {
-                const errorResponse = await response.json() as ApiErrorResponse;
-                throw new ServerAuthError(
-                    errorResponse.error?.code || ServerErrorCode.INVALID_TOKEN,
-                    errorResponse.error?.message || 'Invalid token',
-                    401
-                );
-            }
-
-            const data = await response.json() as ApiSuccessResponse<TokenPayload>;
-            const payload = data.data;
-
-            // Cache the result (for 1 minute or until expiry, whichever is sooner)
-            const cacheExpiry = Math.min(payload.exp * 1000, Date.now() + 60 * 1000);
-            this.tokenCache.set(token, { payload, expiresAt: cacheExpiry });
-
-            return payload;
-        } catch (error) {
-            if (error instanceof ServerAuthError) {
-                throw error;
-            }
-
-            // Try local verification as fallback
-            if (this.config.jwtPublicKey) {
-                return this.verifyTokenLocally(token);
-            }
-
-            throw new ServerAuthError(
-                ServerErrorCode.VERIFICATION_FAILED,
-                error instanceof Error ? error.message : 'Token verification failed',
-                401
-            );
-        }
-    }
-
-    /**
-     * Verify token locally using JWT public key
-     * 使用 JWT 公钥本地验证令牌
-     */
-    private async verifyTokenLocally(token: string): Promise<TokenPayload> {
-        if (!this.config.jwtPublicKey) {
-            throw new ServerAuthError(ServerErrorCode.NO_PUBLIC_KEY, 'JWT public key not configured', 500);
-        }
-
-        try {
-            const publicKey = await jose.importSPKI(this.config.jwtPublicKey, 'RS256');
-            const { payload } = await jose.jwtVerify(token, publicKey);
-
-            return {
-                sub: payload.sub as string,
-                iss: payload.iss as string,
-                aud: payload.aud as string | string[],
-                iat: payload.iat as number,
-                exp: payload.exp as number,
-                scope: payload.scope as string | undefined,
-                azp: payload.azp as string | undefined,
-                phone: payload.phone as string | undefined,
-                email: payload.email as string | undefined,
-            };
-        } catch (error) {
-            throw new ServerAuthError(
-                ServerErrorCode.INVALID_TOKEN,
-                error instanceof Error ? error.message : 'Invalid token',
-                401
-            );
-        }
-    }
-
-    // ============================================
-    // OAuth2 Token Introspection (RFC 7662)
-    // ============================================
-
-    /**
-     * Introspect a token (RFC 7662)
-     * 内省令牌（RFC 7662 标准）
-     * 
-     * This is the standard way for resource servers to validate tokens.
-     * 
-     * @param token - The token to introspect
-     * @param tokenTypeHint - Optional hint about the token type ('access_token' or 'refresh_token')
-     * @returns Introspection result
-     * 
-     * @example
-     * ```typescript
-     * const result = await auth.introspectToken(accessToken);
-     * if (result.active) {
-     *   console.log('Token is valid, user:', result.sub);
-     * }
-     * ```
-     */
-    async introspectToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<IntrospectionResult> {
-        try {
-            // Use Basic Auth for client authentication
-            const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
-
-            const body: Record<string, string> = { token };
-            if (tokenTypeHint) {
-                body.token_type_hint = tokenTypeHint;
-            }
-
-            const response = await fetch(`${this.config.baseUrl}/api/v1/oauth2/introspect`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Authorization': `Basic ${credentials}`,
-                },
-                body: JSON.stringify(body),
-            });
-
-            const result = await response.json() as IntrospectionResult;
-            return result;
-        } catch (error) {
-            // On network error, return inactive
-            return { active: false };
-        }
-    }
-
-    /**
-     * Check if a token is active
-     * 检查令牌是否有效
-     * 
-     * @param token - The token to check
-     * @returns true if token is active
-     */
-    async isTokenActive(token: string): Promise<boolean> {
-        const result = await this.introspectToken(token);
-        return result.active;
-    }
-
-    // ============================================
-    // User Management
-    // ============================================
-
-    /**
-     * Get user info by ID
-     * 根据 ID 获取用户信息
-     */
-    async getUser(userId: string): Promise<UserInfo> {
-        const response = await fetch(`${this.config.baseUrl}/api/v1/admin/users/${userId}`, {
-            method: 'GET',
-            headers: {
-                'Content-Type': 'application/json',
-                'X-App-Key': this.config.clientId,
-                'X-App-Secret': this.config.clientSecret,
-            },
-        });
-
-        if (!response.ok) {
-            const errorResponse = await response.json() as ApiErrorResponse;
-            throw new ServerAuthError(
-                errorResponse.error?.code || ServerErrorCode.USER_NOT_FOUND,
-                errorResponse.error?.message || 'User not found',
-                response.status
-            );
-        }
-
-        const data = await response.json() as ApiSuccessResponse<UserInfo>;
-        return data.data;
-    }
-
-    // ============================================
-    // Express/Connect Middleware
-    // ============================================
-
-    /**
-     * Express/Connect middleware for authentication
-     * Express/Connect 认证中间件
-     * 
-     * @example
-     * ```typescript
-     * import express from 'express';
-     * 
-     * const app = express();
-     * app.use('/api/*', auth.middleware());
-     * 
-     * app.get('/api/profile', (req, res) => {
-     *   res.json({ user: req.user });
-     * });
-     * ```
-     */
-    middleware() {
-        return async (
-            req: ExpressRequest,
-            res: ExpressResponse,
-            next: NextFunction
-        ): Promise<void> => {
-            const authHeader = req.headers['authorization'];
-
-            if (!authHeader || typeof authHeader !== 'string' || !authHeader.startsWith('Bearer ')) {
-                res.status(401).json({
-                    success: false,
-                    error: {
-                        code: ServerErrorCode.UNAUTHORIZED,
-                        message: 'Authorization header is required / 需要授权头',
-                    },
-                });
-                return;
-            }
-
-            const token = authHeader.substring(7);
-
-            try {
-                const payload = await this.verifyToken(token);
-
-                // Attach payload to request
-                req.authPayload = payload;
-
-                // Optionally fetch full user info
-                try {
-                    req.user = await this.getUser(payload.sub);
-                } catch {
-                    // User info not required for middleware to pass
-                }
-
-                next();
-            } catch (error) {
-                const authError = error instanceof ServerAuthError ? error : new ServerAuthError(
-                    ServerErrorCode.UNAUTHORIZED,
-                    'Authentication failed',
-                    401
-                );
-                res.status(authError.statusCode).json({
-                    success: false,
-                    error: {
-                        code: authError.code,
-                        message: authError.message,
-                    },
-                });
-            }
-        };
-    }
-
-    // ============================================
-    // Hono Middleware
-    // ============================================
-
-    /**
-     * Hono middleware for authentication
-     * Hono 认证中间件
-     * 
-     * @example
-     * ```typescript
-     * import { Hono } from 'hono';
-     * 
-     * const app = new Hono();
-     * app.use('/api/*', auth.honoMiddleware());
-     * 
-     * app.get('/api/profile', (c) => {
-     *   const user = c.get('user');
-     *   return c.json({ user });
-     * });
-     * ```
-     */
-    honoMiddleware(): HonoMiddlewareHandler {
-        return async (c: HonoContext, next: () => Promise<void>): Promise<Response | void> => {
-            const authHeader = c.req.header('authorization') || c.req.header('Authorization');
-
-            if (!authHeader || !authHeader.startsWith('Bearer ')) {
-                return c.json({
-                    success: false,
-                    error: {
-                        code: ServerErrorCode.UNAUTHORIZED,
-                        message: 'Authorization header is required / 需要授权头',
-                    },
-                }, 401);
-            }
-
-            const token = authHeader.substring(7);
-
-            try {
-                const payload = await this.verifyToken(token);
-
-                // Attach to context
-                c.set('authPayload', payload);
-
-                // Optionally fetch full user info
-                try {
-                    const user = await this.getUser(payload.sub);
-                    c.set('user', user);
-                } catch {
-                    // User info not required for middleware to pass
-                }
-
-                await next();
-            } catch (error) {
-                const authError = error instanceof ServerAuthError ? error : new ServerAuthError(
-                    ServerErrorCode.UNAUTHORIZED,
-                    'Authentication failed',
-                    401
-                );
-                return c.json({
-                    success: false,
-                    error: {
-                        code: authError.code,
-                        message: authError.message,
-                    },
-                }, authError.statusCode);
-            }
-        };
-    }
-
-    // ============================================
-    // Utility Methods
-    // ============================================
-
-    /**
-     * Clear token cache
-     * 清除令牌缓存
-     */
-    clearCache(): void {
-        this.tokenCache.clear();
-    }
-
-    /**
-     * Get cache statistics
-     * 获取缓存统计
-     */
-    getCacheStats(): { size: number; entries: number } {
-        return {
-            size: this.tokenCache.size,
-            entries: this.tokenCache.size,
-        };
-    }
-}
-
-// ============================================
-// Legacy Compatibility
-// ============================================
-
-/** @deprecated Use ServerAuthError instead */
-export interface AuthError extends Error {
-    code: string;
-    statusCode: number;
-}
-
-// Default export
-export default UniAuthServer;

package/src/server.test.ts

@@ -1,231 +0,0 @@
-/**
- * UniAuth Server SDK Tests
- * UniAuth 服务端 SDK 测试
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { UniAuthServer } from './index.js';
-
-describe('UniAuthServer', () => {
-    beforeEach(() => {
-        vi.stubGlobal('fetch', vi.fn());
-    });
-
-    afterEach(() => {
-        vi.unstubAllGlobals();
-        vi.resetAllMocks();
-    });
-
-    describe('Configuration', () => {
-        it('should create server with required config', () => {
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-app-key',
-                appSecret: 'test-app-secret',
-            });
-
-            expect(server).toBeDefined();
-        });
-    });
-
-    describe('verifyToken', () => {
-        it('should verify token successfully', async () => {
-            const mockPayload = {
-                sub: 'user-123',
-                phone: '+8613800138000',
-                iat: Math.floor(Date.now() / 1000),
-                exp: Math.floor(Date.now() / 1000) + 3600,
-            };
-
-            vi.mocked(fetch).mockResolvedValueOnce({
-                ok: true,
-                json: async () => ({ success: true, data: mockPayload }),
-            } as Response);
-
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            const result = await server.verifyToken('test-token');
-
-            expect(result.sub).toBe('user-123');
-            expect(result.phone).toBe('+8613800138000');
-        });
-
-        it('should throw error for invalid token', async () => {
-            vi.mocked(fetch).mockResolvedValueOnce({
-                ok: false,
-                json: async () => ({
-                    success: false,
-                    error: { code: 'INVALID_TOKEN', message: 'Token is invalid' },
-                }),
-            } as Response);
-
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            await expect(server.verifyToken('invalid-token')).rejects.toThrow('Token is invalid');
-        });
-
-        it('should cache verified tokens', async () => {
-            const mockPayload = {
-                sub: 'user-123',
-                phone: '+8613800138000',
-                iat: Math.floor(Date.now() / 1000),
-                exp: Math.floor(Date.now() / 1000) + 3600,
-            };
-
-            vi.mocked(fetch).mockResolvedValueOnce({
-                ok: true,
-                json: async () => ({ success: true, data: mockPayload }),
-            } as Response);
-
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            // First call - should make HTTP request
-            await server.verifyToken('cached-token');
-
-            // Second call - should use cache
-            await server.verifyToken('cached-token');
-
-            // fetch should only be called once due to caching
-            expect(fetch).toHaveBeenCalledTimes(1);
-        });
-    });
-
-    describe('getUser', () => {
-        it('should get user info successfully', async () => {
-            const mockUser = {
-                id: 'user-123',
-                phone: '+8613800138000',
-                nickname: 'Test User',
-                avatar_url: null,
-                phone_verified: true,
-            };
-
-            vi.mocked(fetch).mockResolvedValueOnce({
-                ok: true,
-                json: async () => ({ success: true, data: mockUser }),
-            } as Response);
-
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            const result = await server.getUser('user-123');
-
-            expect(result.id).toBe('user-123');
-            expect(result.nickname).toBe('Test User');
-        });
-
-        it('should throw error when user not found', async () => {
-            vi.mocked(fetch).mockResolvedValueOnce({
-                ok: false,
-                status: 404,
-                json: async () => ({
-                    success: false,
-                    error: { code: 'USER_NOT_FOUND', message: 'User not found' },
-                }),
-            } as Response);
-
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            await expect(server.getUser('unknown-user')).rejects.toThrow('User not found');
-        });
-    });
-
-    describe('clearCache', () => {
-        it('should clear the token cache', async () => {
-            const mockPayload = {
-                sub: 'user-123',
-                phone: '+8613800138000',
-                iat: Math.floor(Date.now() / 1000),
-                exp: Math.floor(Date.now() / 1000) + 3600,
-            };
-
-            vi.mocked(fetch).mockResolvedValue({
-                ok: true,
-                json: async () => ({ success: true, data: mockPayload }),
-            } as Response);
-
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            // First call
-            await server.verifyToken('test-token');
-            expect(fetch).toHaveBeenCalledTimes(1);
-
-            // Clear cache
-            server.clearCache();
-
-            // Second call - should make new HTTP request
-            await server.verifyToken('test-token');
-            expect(fetch).toHaveBeenCalledTimes(2);
-        });
-    });
-
-    describe('middleware', () => {
-        it('should create middleware function', () => {
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            const middleware = server.middleware();
-
-            expect(typeof middleware).toBe('function');
-        });
-
-        it('should reject requests without authorization header', async () => {
-            const server = new UniAuthServer({
-                baseUrl: 'https://auth.example.com',
-                appKey: 'test-key',
-                appSecret: 'test-secret',
-            });
-
-            const middleware = server.middleware();
-
-            const mockReq = {
-                headers: {},
-            };
-
-            const mockRes = {
-                status: vi.fn().mockReturnThis(),
-                json: vi.fn(),
-            };
-
-            const mockNext = vi.fn();
-
-            await middleware(mockReq as any, mockRes as any, mockNext);
-
-            expect(mockRes.status).toHaveBeenCalledWith(401);
-            expect(mockRes.json).toHaveBeenCalledWith({
-                success: false,
-                error: {
-                    code: 'UNAUTHORIZED',
-                    message: expect.stringContaining('Authorization header'),
-                },
-            });
-            expect(mockNext).not.toHaveBeenCalled();
-        });
-    });
-});

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-    "extends": "../../tsconfig.json",
-    "compilerOptions": {
-        "outDir": "./dist",
-        "rootDir": "./src"
-    },
-    "include": [
-        "src/**/*"
-    ],
-    "exclude": [
-        "node_modules",
-        "dist",
-        "tests"
-    ]
-}