@55387.ai/uniauth-server 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,260 @@
+/**
+ * UniAuth Server SDK
+ * 统一认证后端 SDK
+ *
+ * Usage:
+ * ```typescript
+ * import { UniAuthServer } from '@uniauth/server-sdk';
+ *
+ * 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());
+ * ```
+ */
+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;
+}
+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;
+}
+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;
+}
+interface VerifyResult {
+    valid: boolean;
+    payload?: TokenPayload;
+    error?: string;
+}
+/**
+ * RFC 7662 Token Introspection Response
+ * 令牌内省响应
+ */
+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 错误码
+ */
+declare const ServerErrorCode: {
+    readonly INVALID_TOKEN: "INVALID_TOKEN";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
+    readonly USER_NOT_FOUND: "USER_NOT_FOUND";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly NO_PUBLIC_KEY: "NO_PUBLIC_KEY";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ServerErrorCodeType = typeof ServerErrorCode[keyof typeof ServerErrorCode];
+/**
+ * Custom error class for server SDK
+ * 服务端 SDK 自定义错误类
+ */
+declare class ServerAuthError extends Error {
+    code: ServerErrorCodeType | string;
+    statusCode: number;
+    constructor(code: ServerErrorCodeType | string, message: string, statusCode?: number);
+}
+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;
+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
+ */
+declare class UniAuthServer {
+    private config;
+    private tokenCache;
+    constructor(config: UniAuthServerConfig);
+    /**
+     * Verify access token
+     * 验证访问令牌
+     *
+     * @param token - JWT access token
+     * @returns Token payload if valid
+     * @throws ServerAuthError if token is invalid
+     */
+    verifyToken(token: string): Promise<TokenPayload>;
+    /**
+     * Verify token locally using JWT public key
+     * 使用 JWT 公钥本地验证令牌
+     */
+    private verifyTokenLocally;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    introspectToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<IntrospectionResult>;
+    /**
+     * Check if a token is active
+     * 检查令牌是否有效
+     *
+     * @param token - The token to check
+     * @returns true if token is active
+     */
+    isTokenActive(token: string): Promise<boolean>;
+    /**
+     * Get user info by ID
+     * 根据 ID 获取用户信息
+     */
+    getUser(userId: string): Promise<UserInfo>;
+    /**
+     * 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(): (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => Promise<void>;
+    /**
+     * 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;
+    /**
+     * Clear token cache
+     * 清除令牌缓存
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     * 获取缓存统计
+     */
+    getCacheStats(): {
+        size: number;
+        entries: number;
+    };
+}
+/** @deprecated Use ServerAuthError instead */
+interface AuthError extends Error {
+    code: string;
+    statusCode: number;
+}
+
+export { type AuthError, type IntrospectionResult, ServerAuthError, ServerErrorCode, type ServerErrorCodeType, type TokenPayload, UniAuthServer, type UniAuthServerConfig, type UserInfo, type VerifyResult, UniAuthServer as default };

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+/**
+ * UniAuth Server SDK
+ * 统一认证后端 SDK
+ *
+ * Usage:
+ * ```typescript
+ * import { UniAuthServer } from '@uniauth/server-sdk';
+ *
+ * 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());
+ * ```
+ */
+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;
+}
+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;
+}
+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;
+}
+interface VerifyResult {
+    valid: boolean;
+    payload?: TokenPayload;
+    error?: string;
+}
+/**
+ * RFC 7662 Token Introspection Response
+ * 令牌内省响应
+ */
+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 错误码
+ */
+declare const ServerErrorCode: {
+    readonly INVALID_TOKEN: "INVALID_TOKEN";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
+    readonly USER_NOT_FOUND: "USER_NOT_FOUND";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly NO_PUBLIC_KEY: "NO_PUBLIC_KEY";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ServerErrorCodeType = typeof ServerErrorCode[keyof typeof ServerErrorCode];
+/**
+ * Custom error class for server SDK
+ * 服务端 SDK 自定义错误类
+ */
+declare class ServerAuthError extends Error {
+    code: ServerErrorCodeType | string;
+    statusCode: number;
+    constructor(code: ServerErrorCodeType | string, message: string, statusCode?: number);
+}
+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;
+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
+ */
+declare class UniAuthServer {
+    private config;
+    private tokenCache;
+    constructor(config: UniAuthServerConfig);
+    /**
+     * Verify access token
+     * 验证访问令牌
+     *
+     * @param token - JWT access token
+     * @returns Token payload if valid
+     * @throws ServerAuthError if token is invalid
+     */
+    verifyToken(token: string): Promise<TokenPayload>;
+    /**
+     * Verify token locally using JWT public key
+     * 使用 JWT 公钥本地验证令牌
+     */
+    private verifyTokenLocally;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    introspectToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<IntrospectionResult>;
+    /**
+     * Check if a token is active
+     * 检查令牌是否有效
+     *
+     * @param token - The token to check
+     * @returns true if token is active
+     */
+    isTokenActive(token: string): Promise<boolean>;
+    /**
+     * Get user info by ID
+     * 根据 ID 获取用户信息
+     */
+    getUser(userId: string): Promise<UserInfo>;
+    /**
+     * 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(): (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => Promise<void>;
+    /**
+     * 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;
+    /**
+     * Clear token cache
+     * 清除令牌缓存
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     * 获取缓存统计
+     */
+    getCacheStats(): {
+        size: number;
+        entries: number;
+    };
+}
+/** @deprecated Use ServerAuthError instead */
+interface AuthError extends Error {
+    code: string;
+    statusCode: number;
+}
+
+export { type AuthError, type IntrospectionResult, ServerAuthError, ServerErrorCode, type ServerErrorCodeType, type TokenPayload, UniAuthServer, type UniAuthServerConfig, type UserInfo, type VerifyResult, UniAuthServer as default };