@esengine/server 1.1.4 → 1.2.0

package/dist/auth/index.d.ts

@@ -0,0 +1,711 @@
+import { I as IAuthContext, A as AuthResult, a as IAuthProvider, b as AuthServerConfig, c as AuthGameServer, d as AuthRoomConfig, R as RequireAuthOptions, e as RequireRoleOptions } from '../types-BmO5ykKp.js';
+export { i as AuthApiContext, h as AuthConnection, g as AuthConnectionData, f as AuthErrorCode, j as AuthMsgContext, C as ConnectionRequest } from '../types-BmO5ykKp.js';
+import { G as GameServer, a as ServerConnection } from '../index-DgaJIm6-.js';
+import { R as Room, P as Player } from '../Room-BnKpl5Sj.js';
+import '@esengine/rpc';
+
+/**
+ * @zh 认证上下文实现
+ * @en Authentication context implementation
+ */
+
+/**
+ * @zh 用户信息提取器
+ * @en User info extractor
+ */
+interface UserInfoExtractor<TUser> {
+    /**
+     * @zh 提取用户 ID
+     * @en Extract user ID
+     */
+    getId(user: TUser): string;
+    /**
+     * @zh 提取用户角色
+     * @en Extract user roles
+     */
+    getRoles(user: TUser): string[];
+}
+/**
+ * @zh 默认用户信息提取器
+ * @en Default user info extractor
+ */
+declare const defaultUserExtractor: UserInfoExtractor<unknown>;
+/**
+ * @zh 认证上下文
+ * @en Authentication context
+ *
+ * @zh 存储连接的认证状态
+ * @en Stores authentication state for a connection
+ */
+declare class AuthContext<TUser = unknown> implements IAuthContext<TUser> {
+    private _isAuthenticated;
+    private _user;
+    private _userId;
+    private _roles;
+    private _authenticatedAt;
+    private _expiresAt;
+    private _extractor;
+    constructor(extractor?: UserInfoExtractor<TUser>);
+    /**
+     * @zh 是否已认证
+     * @en Whether authenticated
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * @zh 用户信息
+     * @en User information
+     */
+    get user(): TUser | null;
+    /**
+     * @zh 用户 ID
+     * @en User ID
+     */
+    get userId(): string | null;
+    /**
+     * @zh 用户角色
+     * @en User roles
+     */
+    get roles(): ReadonlyArray<string>;
+    /**
+     * @zh 认证时间
+     * @en Authentication timestamp
+     */
+    get authenticatedAt(): number | null;
+    /**
+     * @zh 令牌过期时间
+     * @en Token expiration time
+     */
+    get expiresAt(): number | null;
+    /**
+     * @zh 检查是否有指定角色
+     * @en Check if has specified role
+     */
+    hasRole(role: string): boolean;
+    /**
+     * @zh 检查是否有任一指定角色
+     * @en Check if has any of specified roles
+     */
+    hasAnyRole(roles: string[]): boolean;
+    /**
+     * @zh 检查是否有所有指定角色
+     * @en Check if has all specified roles
+     */
+    hasAllRoles(roles: string[]): boolean;
+    /**
+     * @zh 设置认证结果
+     * @en Set authentication result
+     */
+    setAuthenticated(result: AuthResult<TUser>): void;
+    /**
+     * @zh 清除认证状态
+     * @en Clear authentication state
+     */
+    clear(): void;
+}
+/**
+ * @zh 创建访客认证上下文
+ * @en Create guest auth context
+ */
+declare function createGuestContext<TUser = unknown>(): IAuthContext<TUser>;
+/**
+ * @zh 从认证结果创建认证上下文
+ * @en Create auth context from auth result
+ */
+declare function createAuthContext<TUser = unknown>(result: AuthResult<TUser>, extractor?: UserInfoExtractor<TUser>): AuthContext<TUser>;
+
+/**
+ * @zh JWT 认证提供者
+ * @en JWT authentication provider
+ */
+
+/**
+ * @zh JWT 载荷
+ * @en JWT payload
+ */
+interface JwtPayload {
+    /**
+     * @zh 主题（用户 ID）
+     * @en Subject (user ID)
+     */
+    sub?: string;
+    /**
+     * @zh 签发时间
+     * @en Issued at
+     */
+    iat?: number;
+    /**
+     * @zh 过期时间
+     * @en Expiration time
+     */
+    exp?: number;
+    /**
+     * @zh 自定义字段
+     * @en Custom fields
+     */
+    [key: string]: unknown;
+}
+/**
+ * @zh JWT 认证配置
+ * @en JWT authentication configuration
+ */
+interface JwtAuthConfig<TUser = unknown> {
+    /**
+     * @zh 密钥
+     * @en Secret key
+     */
+    secret: string;
+    /**
+     * @zh 算法
+     * @en Algorithm
+     * @defaultValue 'HS256'
+     */
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+    /**
+     * @zh 令牌过期时间（秒）
+     * @en Token expiration in seconds
+     * @defaultValue 3600
+     */
+    expiresIn?: number;
+    /**
+     * @zh 从载荷获取用户信息
+     * @en Get user from payload
+     */
+    getUser?: (payload: JwtPayload) => TUser | Promise<TUser | null> | null;
+    /**
+     * @zh 签发者
+     * @en Issuer
+     */
+    issuer?: string;
+    /**
+     * @zh 受众
+     * @en Audience
+     */
+    audience?: string;
+}
+/**
+ * @zh JWT 认证提供者
+ * @en JWT authentication provider
+ *
+ * @zh 使用 jsonwebtoken 库实现 JWT 认证
+ * @en Uses jsonwebtoken library for JWT authentication
+ *
+ * @example
+ * ```typescript
+ * const jwtProvider = createJwtAuthProvider({
+ *     secret: 'your-secret-key',
+ *     expiresIn: 3600,
+ *     getUser: async (payload) => {
+ *         return await db.users.findById(payload.sub);
+ *     }
+ * });
+ * ```
+ */
+declare class JwtAuthProvider<TUser = unknown> implements IAuthProvider<TUser, string> {
+    readonly name = "jwt";
+    private _config;
+    constructor(config: JwtAuthConfig<TUser>);
+    /**
+     * @zh 验证令牌
+     * @en Verify token
+     */
+    verify(token: string): Promise<AuthResult<TUser>>;
+    /**
+     * @zh 刷新令牌
+     * @en Refresh token
+     */
+    refresh(token: string): Promise<AuthResult<TUser>>;
+    /**
+     * @zh 生成令牌
+     * @en Generate token
+     */
+    sign(payload: Record<string, unknown>): string;
+    /**
+     * @zh 解码令牌（不验证）
+     * @en Decode token (without verification)
+     */
+    decode(token: string): JwtPayload | null;
+}
+/**
+ * @zh 创建 JWT 认证提供者
+ * @en Create JWT authentication provider
+ *
+ * @example
+ * ```typescript
+ * import { createJwtAuthProvider } from '@esengine/server/auth';
+ *
+ * const jwtProvider = createJwtAuthProvider({
+ *     secret: process.env.JWT_SECRET!,
+ *     expiresIn: 3600,
+ *     getUser: async (payload) => {
+ *         return { id: payload.sub, name: payload.name };
+ *     }
+ * });
+ * ```
+ */
+declare function createJwtAuthProvider<TUser = unknown>(config: JwtAuthConfig<TUser>): JwtAuthProvider<TUser>;
+
+/**
+ * @zh Session 认证提供者
+ * @en Session authentication provider
+ */
+
+/**
+ * @zh Session 存储接口（兼容 ITransactionStorage）
+ * @en Session storage interface (compatible with ITransactionStorage)
+ */
+interface ISessionStorage {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+/**
+ * @zh Session 数据
+ * @en Session data
+ */
+interface SessionData<TUser = unknown> {
+    /**
+     * @zh 用户信息
+     * @en User information
+     */
+    user: TUser;
+    /**
+     * @zh 创建时间
+     * @en Created at
+     */
+    createdAt: number;
+    /**
+     * @zh 最后活跃时间
+     * @en Last active at
+     */
+    lastActiveAt: number;
+    /**
+     * @zh 自定义数据
+     * @en Custom data
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * @zh Session 认证配置
+ * @en Session authentication configuration
+ */
+interface SessionAuthConfig<TUser = unknown> {
+    /**
+     * @zh Session 存储
+     * @en Session storage
+     */
+    storage: ISessionStorage;
+    /**
+     * @zh Session 过期时间（毫秒）
+     * @en Session expiration in milliseconds
+     * @defaultValue 86400000 (24h)
+     */
+    sessionTTL?: number;
+    /**
+     * @zh Session 键前缀
+     * @en Session key prefix
+     * @defaultValue 'session:'
+     */
+    prefix?: string;
+    /**
+     * @zh 验证用户（可选额外验证）
+     * @en Validate user (optional extra validation)
+     */
+    validateUser?: (user: TUser) => boolean | Promise<boolean>;
+    /**
+     * @zh 是否自动续期
+     * @en Auto renew session
+     * @defaultValue true
+     */
+    autoRenew?: boolean;
+}
+/**
+ * @zh Session 认证提供者
+ * @en Session authentication provider
+ *
+ * @zh 基于存储的会话认证，支持 Redis、MongoDB 等后端
+ * @en Storage-based session authentication, supports Redis, MongoDB, etc.
+ *
+ * @example
+ * ```typescript
+ * import { createSessionAuthProvider } from '@esengine/server/auth';
+ * import { createRedisStorage } from '@esengine/transaction';
+ *
+ * const sessionProvider = createSessionAuthProvider({
+ *     storage: createRedisStorage({ factory: () => new Redis() }),
+ *     sessionTTL: 86400000, // 24 hours
+ * });
+ * ```
+ */
+declare class SessionAuthProvider<TUser = unknown> implements IAuthProvider<TUser, string> {
+    readonly name = "session";
+    private _config;
+    constructor(config: SessionAuthConfig<TUser>);
+    /**
+     * @zh 获取存储键
+     * @en Get storage key
+     */
+    private _getKey;
+    /**
+     * @zh 验证 Session
+     * @en Verify session
+     */
+    verify(sessionId: string): Promise<AuthResult<TUser>>;
+    /**
+     * @zh 刷新 Session
+     * @en Refresh session
+     */
+    refresh(sessionId: string): Promise<AuthResult<TUser>>;
+    /**
+     * @zh 撤销 Session
+     * @en Revoke session
+     */
+    revoke(sessionId: string): Promise<boolean>;
+    /**
+     * @zh 创建 Session
+     * @en Create session
+     */
+    createSession(user: TUser, data?: Record<string, unknown>): Promise<string>;
+    /**
+     * @zh 获取 Session 数据
+     * @en Get session data
+     */
+    getSession(sessionId: string): Promise<SessionData<TUser> | null>;
+    /**
+     * @zh 更新 Session 数据
+     * @en Update session data
+     */
+    updateSession(sessionId: string, data: Record<string, unknown>): Promise<boolean>;
+    /**
+     * @zh 生成 Session ID（使用加密安全的随机数）
+     * @en Generate session ID (using cryptographically secure random)
+     */
+    private _generateSessionId;
+}
+/**
+ * @zh 创建 Session 认证提供者
+ * @en Create session authentication provider
+ *
+ * @example
+ * ```typescript
+ * import { createSessionAuthProvider } from '@esengine/server/auth';
+ * import { MemoryStorage } from '@esengine/transaction';
+ *
+ * const sessionProvider = createSessionAuthProvider({
+ *     storage: new MemoryStorage(),
+ *     sessionTTL: 3600000, // 1 hour
+ * });
+ *
+ * // Create a session
+ * const sessionId = await sessionProvider.createSession({ id: '1', name: 'Alice' });
+ *
+ * // Verify session
+ * const result = await sessionProvider.verify(sessionId);
+ * ```
+ */
+declare function createSessionAuthProvider<TUser = unknown>(config: SessionAuthConfig<TUser>): SessionAuthProvider<TUser>;
+
+/**
+ * @zh 服务器认证 Mixin
+ * @en Server authentication mixin
+ */
+
+/**
+ * @zh 获取连接的认证上下文
+ * @en Get auth context for connection
+ */
+declare function getAuthContext<TUser = unknown>(conn: ServerConnection): IAuthContext<TUser> | null;
+/**
+ * @zh 设置连接的认证上下文
+ * @en Set auth context for connection
+ */
+declare function setAuthContext<TUser = unknown>(conn: ServerConnection, context: IAuthContext<TUser>): void;
+/**
+ * @zh 包装服务器添加认证功能
+ * @en Wrap server with authentication functionality
+ *
+ * @zh 使用 mixin 模式为服务器添加认证能力，不修改原始服务器
+ * @en Uses mixin pattern to add authentication to server without modifying original
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@esengine/server';
+ * import { withAuth, createJwtAuthProvider } from '@esengine/server/auth';
+ *
+ * const jwtProvider = createJwtAuthProvider({
+ *     secret: 'your-secret-key',
+ *     expiresIn: 3600,
+ * });
+ *
+ * const server = withAuth(await createServer({ port: 3000 }), {
+ *     provider: jwtProvider,
+ *     extractCredentials: (req) => {
+ *         const url = new URL(req.url, 'http://localhost');
+ *         return url.searchParams.get('token');
+ *     },
+ *     onAuthSuccess: (conn, user) => {
+ *         console.log(`User ${user.name} authenticated`);
+ *     },
+ *     onAuthFailure: (conn, error) => {
+ *         console.log(`Auth failed: ${error.error}`);
+ *     }
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+declare function withAuth<TUser = unknown>(server: GameServer, config: AuthServerConfig<TUser>): AuthGameServer<TUser>;
+/**
+ * @zh 创建认证中间件
+ * @en Create authentication middleware
+ *
+ * @zh 用于在 API 处理器中检查认证状态
+ * @en Used to check authentication status in API handlers
+ */
+declare function requireAuthentication<TUser = unknown>(conn: ServerConnection, options?: {
+    errorMessage?: string;
+}): IAuthContext<TUser>;
+/**
+ * @zh 创建角色检查中间件
+ * @en Create role check middleware
+ */
+declare function requireRole$1<TUser = unknown>(conn: ServerConnection, roles: string | string[], options?: {
+    mode?: 'any' | 'all';
+    errorMessage?: string;
+}): IAuthContext<TUser>;
+
+/**
+ * @zh 房间认证 Mixin
+ * @en Room authentication mixin
+ */
+
+/**
+ * @zh 带认证的玩家
+ * @en Player with authentication
+ */
+interface AuthPlayer<TUser = unknown, TData = Record<string, unknown>> extends Player<TData> {
+    /**
+     * @zh 认证上下文
+     * @en Authentication context
+     */
+    readonly auth: IAuthContext<TUser>;
+    /**
+     * @zh 用户信息（快捷访问）
+     * @en User info (shortcut)
+     */
+    readonly user: TUser | null;
+}
+/**
+ * @zh 带认证的房间接口
+ * @en Room with authentication interface
+ */
+interface IAuthRoom<TUser = unknown> {
+    /**
+     * @zh 认证钩子（在 onJoin 之前调用）
+     * @en Auth hook (called before onJoin)
+     */
+    onAuth?(player: AuthPlayer<TUser>): boolean | Promise<boolean>;
+    /**
+     * @zh 获取带认证信息的玩家
+     * @en Get player with auth info
+     */
+    getAuthPlayer(id: string): AuthPlayer<TUser> | undefined;
+    /**
+     * @zh 获取所有带认证信息的玩家
+     * @en Get all players with auth info
+     */
+    getAuthPlayers(): AuthPlayer<TUser>[];
+    /**
+     * @zh 按角色获取玩家
+     * @en Get players by role
+     */
+    getPlayersByRole(role: string): AuthPlayer<TUser>[];
+    /**
+     * @zh 按用户 ID 获取玩家
+     * @en Get player by user ID
+     */
+    getPlayerByUserId(userId: string): AuthPlayer<TUser> | undefined;
+}
+/**
+ * @zh 认证房间构造器类型
+ * @en Auth room constructor type
+ */
+type AuthRoomClass<TUser = unknown> = new (...args: any[]) => Room & IAuthRoom<TUser>;
+/**
+ * @zh 包装房间类添加认证功能
+ * @en Wrap room class with authentication functionality
+ *
+ * @zh 使用 mixin 模式为房间添加认证检查，在玩家加入前验证认证状态
+ * @en Uses mixin pattern to add auth checks to room, validates auth before player joins
+ *
+ * @example
+ * ```typescript
+ * import { Room, onMessage } from '@esengine/server';
+ * import { withRoomAuth, type AuthPlayer } from '@esengine/server/auth';
+ *
+ * interface User {
+ *     id: string;
+ *     name: string;
+ *     roles: string[];
+ * }
+ *
+ * class GameRoom extends withRoomAuth<User>(Room, {
+ *     requireAuth: true,
+ *     allowedRoles: ['player', 'premium'],
+ * }) {
+ *     onJoin(player: AuthPlayer<User>) {
+ *         console.log(`${player.user?.name} joined the game`);
+ *         this.broadcast('PlayerJoined', {
+ *             id: player.id,
+ *             name: player.user?.name
+ *         });
+ *     }
+ *
+ *     // Optional: custom auth validation
+ *     async onAuth(player: AuthPlayer<User>): Promise<boolean> {
+ *         // Additional validation logic
+ *         if (player.auth.hasRole('banned')) {
+ *             return false;
+ *         }
+ *         return true;
+ *     }
+ *
+ *     @onMessage('Chat')
+ *     handleChat(data: { text: string }, player: AuthPlayer<User>) {
+ *         this.broadcast('Chat', {
+ *             from: player.user?.name ?? 'Guest',
+ *             text: data.text
+ *         });
+ *     }
+ * }
+ * ```
+ */
+declare function withRoomAuth<TUser = unknown, TBase extends new (...args: any[]) => Room = new (...args: any[]) => Room>(Base: TBase, config?: AuthRoomConfig): TBase & (new (...args: any[]) => IAuthRoom<TUser>);
+/**
+ * @zh 抽象认证房间基类
+ * @en Abstract auth room base class
+ *
+ * @zh 如果不想使用 mixin，可以直接继承此类
+ * @en If you don't want to use mixin, you can extend this class directly
+ *
+ * @example
+ * ```typescript
+ * import { AuthRoomBase } from '@esengine/server/auth';
+ *
+ * class GameRoom extends AuthRoomBase<User> {
+ *     protected readonly authConfig = {
+ *         requireAuth: true,
+ *         allowedRoles: ['player']
+ *     };
+ *
+ *     onJoin(player: AuthPlayer<User>) {
+ *         // player has .auth and .user properties
+ *     }
+ * }
+ * ```
+ */
+declare abstract class AuthRoomBase<TUser = unknown, TState = any, TPlayerData = Record<string, unknown>> implements IAuthRoom<TUser> {
+    /**
+     * @zh 认证配置（子类可覆盖）
+     * @en Auth config (can be overridden by subclass)
+     */
+    protected readonly authConfig: AuthRoomConfig;
+    /**
+     * @zh 认证钩子
+     * @en Auth hook
+     */
+    onAuth?(player: AuthPlayer<TUser>): boolean | Promise<boolean>;
+    getAuthPlayer(id: string): AuthPlayer<TUser> | undefined;
+    getAuthPlayers(): AuthPlayer<TUser>[];
+    getPlayersByRole(role: string): AuthPlayer<TUser>[];
+    getPlayerByUserId(userId: string): AuthPlayer<TUser> | undefined;
+}
+
+/**
+ * @zh requireAuth 装饰器
+ * @en requireAuth decorator
+ */
+
+/**
+ * @zh 认证元数据键
+ * @en Auth metadata key
+ */
+declare const AUTH_METADATA_KEY: unique symbol;
+/**
+ * @zh 认证元数据
+ * @en Auth metadata
+ */
+interface AuthMetadata {
+    requireAuth: boolean;
+    options?: RequireAuthOptions;
+    roles?: string[];
+    roleMode?: 'any' | 'all';
+}
+/**
+ * @zh 获取方法的认证元数据
+ * @en Get auth metadata for method
+ */
+declare function getAuthMetadata(target: any, propertyKey: string): AuthMetadata | undefined;
+/**
+ * @zh 要求认证装饰器
+ * @en Require authentication decorator
+ *
+ * @zh 标记方法需要认证才能访问，用于消息处理器
+ * @en Marks method as requiring authentication, used for message handlers
+ *
+ * @example
+ * ```typescript
+ * class GameRoom extends withRoomAuth(Room) {
+ *     @requireAuth()
+ *     @onMessage('Trade')
+ *     handleTrade(data: TradeData, player: AuthPlayer) {
+ *         // Only authenticated players can trade
+ *     }
+ *
+ *     @requireAuth({ allowGuest: true })
+ *     @onMessage('Chat')
+ *     handleChat(data: ChatData, player: AuthPlayer) {
+ *         // Guests can also chat
+ *     }
+ * }
+ * ```
+ */
+declare function requireAuth(options?: RequireAuthOptions): MethodDecorator;
+
+/**
+ * @zh requireRole 装饰器
+ * @en requireRole decorator
+ */
+
+/**
+ * @zh 要求角色装饰器
+ * @en Require role decorator
+ *
+ * @zh 标记方法需要特定角色才能访问
+ * @en Marks method as requiring specific role(s)
+ *
+ * @example
+ * ```typescript
+ * class AdminRoom extends withRoomAuth(Room) {
+ *     @requireRole('admin')
+ *     @onMessage('Ban')
+ *     handleBan(data: BanData, player: AuthPlayer) {
+ *         // Only admins can ban
+ *     }
+ *
+ *     @requireRole(['moderator', 'admin'])
+ *     @onMessage('Mute')
+ *     handleMute(data: MuteData, player: AuthPlayer) {
+ *         // Moderators or admins can mute
+ *     }
+ *
+ *     @requireRole(['verified', 'premium'], { mode: 'all' })
+ *     @onMessage('SpecialFeature')
+ *     handleSpecial(data: any, player: AuthPlayer) {
+ *         // Requires both verified AND premium roles
+ *     }
+ * }
+ * ```
+ */
+declare function requireRole(roles: string | string[], options?: RequireRoleOptions): MethodDecorator;
+
+export { AUTH_METADATA_KEY, AuthContext, AuthGameServer, type AuthMetadata, type AuthPlayer, AuthResult, AuthRoomBase, type AuthRoomClass, AuthRoomConfig, AuthServerConfig, IAuthContext, IAuthProvider, type IAuthRoom, type ISessionStorage, type JwtAuthConfig, JwtAuthProvider, type JwtPayload, RequireAuthOptions, RequireRoleOptions, type SessionAuthConfig, SessionAuthProvider, type SessionData, type UserInfoExtractor, createAuthContext, createGuestContext, createJwtAuthProvider, createSessionAuthProvider, defaultUserExtractor, getAuthContext, getAuthMetadata, requireAuth, requireAuthentication, requireRole, requireRole$1 as requireRoleCheck, setAuthContext, withAuth, withRoomAuth };