@55387.ai/uniauth-server 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# @55387.ai/uniauth-server
+
+UniAuth 后端 SDK，用于在 Node.js 后端服务中验证用户令牌。
+
+## 安装
+
+```bash
+npm install @55387.ai/uniauth-server
+# or
+pnpm add @55387.ai/uniauth-server
+```
+
+## 快速开始
+
+```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',
+});
+
+// 验证令牌
+const payload = await auth.verifyToken(accessToken);
+console.log('User ID:', payload.sub);
+```
+
+## Express 中间件
+
+```typescript
+import express from 'express';
+import { UniAuthServer } from '@uniauth/server-sdk';
+
+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 中间件
+
+```typescript
+import { Hono } from 'hono';
+import { UniAuthServer } from '@uniauth/server-sdk';
+
+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 });
+});
+```
+
+## OAuth2 Token Introspection (RFC 7662)
+
+```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 无效或已过期');
+}
+```
+
+## API 参考
+
+### 初始化选项
+
+```typescript
+interface UniAuthServerConfig {
+  baseUrl: string;        // UniAuth 服务地址
+  clientId: string;       // OAuth2 客户端 ID
+  clientSecret: string;   // OAuth2 客户端密钥
+  jwtPublicKey?: string;  // JWT 公钥（用于本地验证）
+}
+```
+
+### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `verifyToken(token)` | 验证访问令牌 |
+| `introspectToken(token)` | RFC 7662 令牌内省 |
+| `isTokenActive(token)` | 检查令牌是否有效 |
+| `getUser(userId)` | 获取用户信息 |
+| `middleware()` | Express/Connect 中间件 |
+| `honoMiddleware()` | Hono 中间件 |
+| `clearCache()` | 清除令牌缓存 |
+
+### 类型
+
+```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;
+}
+```
+
+## 错误处理
+
+```typescript
+import { ServerAuthError, ServerErrorCode } from '@55387.ai/uniauth-server';
+
+try {
+  await auth.verifyToken(token);
+} catch (error) {
+  if (error instanceof ServerAuthError) {
+    switch (error.code) {
+      case ServerErrorCode.INVALID_TOKEN:
+        // 令牌无效
+        break;
+      case ServerErrorCode.TOKEN_EXPIRED:
+        // 令牌已过期
+        break;
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,378 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ServerAuthError: () => ServerAuthError,
+  ServerErrorCode: () => ServerErrorCode,
+  UniAuthServer: () => UniAuthServer,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var jose = __toESM(require("jose"), 1);
+var 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"
+};
+var ServerAuthError = class _ServerAuthError extends Error {
+  code;
+  statusCode;
+  constructor(code, message, statusCode = 401) {
+    super(message);
+    this.name = "ServerAuthError";
+    this.code = code;
+    this.statusCode = statusCode;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ServerAuthError);
+    }
+  }
+};
+var UniAuthServer = class {
+  config;
+  tokenCache = /* @__PURE__ */ new Map();
+  constructor(config) {
+    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) {
+    const cached = this.tokenCache.get(token);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.payload;
+    }
+    try {
+      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();
+        throw new ServerAuthError(
+          errorResponse.error?.code || ServerErrorCode.INVALID_TOKEN,
+          errorResponse.error?.message || "Invalid token",
+          401
+        );
+      }
+      const data = await response.json();
+      const payload = data.data;
+      const cacheExpiry = Math.min(payload.exp * 1e3, Date.now() + 60 * 1e3);
+      this.tokenCache.set(token, { payload, expiresAt: cacheExpiry });
+      return payload;
+    } catch (error) {
+      if (error instanceof ServerAuthError) {
+        throw error;
+      }
+      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 公钥本地验证令牌
+   */
+  async verifyTokenLocally(token) {
+    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,
+        iss: payload.iss,
+        aud: payload.aud,
+        iat: payload.iat,
+        exp: payload.exp,
+        scope: payload.scope,
+        azp: payload.azp,
+        phone: payload.phone,
+        email: payload.email
+      };
+    } 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, tokenTypeHint) {
+    try {
+      const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString("base64");
+      const body = { 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();
+      return result;
+    } catch (error) {
+      return { active: false };
+    }
+  }
+  /**
+   * Check if a token is active
+   * 检查令牌是否有效
+   * 
+   * @param token - The token to check
+   * @returns true if token is active
+   */
+  async isTokenActive(token) {
+    const result = await this.introspectToken(token);
+    return result.active;
+  }
+  // ============================================
+  // User Management
+  // ============================================
+  /**
+   * Get user info by ID
+   * 根据 ID 获取用户信息
+   */
+  async getUser(userId) {
+    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();
+      throw new ServerAuthError(
+        errorResponse.error?.code || ServerErrorCode.USER_NOT_FOUND,
+        errorResponse.error?.message || "User not found",
+        response.status
+      );
+    }
+    const data = await response.json();
+    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, res, next) => {
+      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 / \u9700\u8981\u6388\u6743\u5934"
+          }
+        });
+        return;
+      }
+      const token = authHeader.substring(7);
+      try {
+        const payload = await this.verifyToken(token);
+        req.authPayload = payload;
+        try {
+          req.user = await this.getUser(payload.sub);
+        } catch {
+        }
+        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() {
+    return async (c, next) => {
+      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 / \u9700\u8981\u6388\u6743\u5934"
+          }
+        }, 401);
+      }
+      const token = authHeader.substring(7);
+      try {
+        const payload = await this.verifyToken(token);
+        c.set("authPayload", payload);
+        try {
+          const user = await this.getUser(payload.sub);
+          c.set("user", user);
+        } catch {
+        }
+        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() {
+    this.tokenCache.clear();
+  }
+  /**
+   * Get cache statistics
+   * 获取缓存统计
+   */
+  getCacheStats() {
+    return {
+      size: this.tokenCache.size,
+      entries: this.tokenCache.size
+    };
+  }
+};
+var index_default = UniAuthServer;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ServerAuthError,
+  ServerErrorCode,
+  UniAuthServer
+});