feat(server): 添加可插拔认证系统 | add pluggable authentication system (#386)
* feat(server): 添加可插拔认证系统 | add pluggable authentication system - 新增 JWT 认证提供者 (createJwtAuthProvider) - 新增 Session 认证提供者 (createSessionAuthProvider) - 新增服务器认证 mixin (withAuth) - 新增房间认证 mixin (withRoomAuth) - 新增认证装饰器 (@requireAuth, @requireRole) - 新增测试工具 (MockAuthProvider) - 新增中英文文档 - 导出路径: @esengine/server/auth, @esengine/server/auth/testing * fix(server): 使用加密安全的随机数生成 session ID | use crypto-secure random for session ID
This commit is contained in:
YHH
GitHub
506
docs/src/content/docs/en/modules/network/auth.md
Normal file
506
docs/src/content/docs/en/modules/network/auth.md
Normal file
@@ -0,0 +1,506 @@
|
||||
---
|
||||
title: "Authentication"
|
||||
description: "Add authentication to your game server with JWT and Session providers"
|
||||
---
|
||||
|
||||
The `@esengine/server` package includes a pluggable authentication system that supports JWT, session-based auth, and custom providers.
|
||||
|
||||
## Installation
|
||||
|
||||
Authentication is included in the server package:
|
||||
|
||||
```bash
|
||||
npm install @esengine/server jsonwebtoken
|
||||
```
|
||||
|
||||
> Note: `jsonwebtoken` is an optional peer dependency, required only for JWT authentication.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### JWT Authentication
|
||||
|
||||
```typescript
|
||||
import { createServer } from '@esengine/server'
|
||||
import { withAuth, createJwtAuthProvider, withRoomAuth, requireAuth } from '@esengine/server/auth'
|
||||
|
||||
// Create JWT provider
|
||||
const jwtProvider = createJwtAuthProvider({
|
||||
secret: process.env.JWT_SECRET!,
|
||||
expiresIn: 3600, // 1 hour
|
||||
})
|
||||
|
||||
// Wrap server with authentication
|
||||
const server = withAuth(await createServer({ port: 3000 }), {
|
||||
provider: jwtProvider,
|
||||
extractCredentials: (req) => {
|
||||
const url = new URL(req.url ?? '', 'http://localhost')
|
||||
return url.searchParams.get('token')
|
||||
},
|
||||
})
|
||||
|
||||
// Define authenticated room
|
||||
class GameRoom extends withRoomAuth(Room, { requireAuth: true }) {
|
||||
onJoin(player) {
|
||||
console.log(`${player.user?.name} joined!`)
|
||||
}
|
||||
}
|
||||
|
||||
server.define('game', GameRoom)
|
||||
await server.start()
|
||||
```
|
||||
|
||||
## Auth Providers
|
||||
|
||||
### JWT Provider
|
||||
|
||||
Use JSON Web Tokens for stateless authentication:
|
||||
|
||||
```typescript
|
||||
import { createJwtAuthProvider } from '@esengine/server/auth'
|
||||
|
||||
const jwtProvider = createJwtAuthProvider({
|
||||
// Required: secret key
|
||||
secret: 'your-secret-key',
|
||||
|
||||
// Optional: algorithm (default: HS256)
|
||||
algorithm: 'HS256',
|
||||
|
||||
// Optional: expiration in seconds (default: 3600)
|
||||
expiresIn: 3600,
|
||||
|
||||
// Optional: issuer for validation
|
||||
issuer: 'my-game-server',
|
||||
|
||||
// Optional: audience for validation
|
||||
audience: 'my-game-client',
|
||||
|
||||
// Optional: custom user extraction
|
||||
getUser: async (payload) => {
|
||||
// Fetch user from database
|
||||
return await db.users.findById(payload.sub)
|
||||
},
|
||||
})
|
||||
|
||||
// Sign a token (for login endpoints)
|
||||
const token = jwtProvider.sign({
|
||||
sub: user.id,
|
||||
name: user.name,
|
||||
roles: ['player'],
|
||||
})
|
||||
|
||||
// Decode without verification (for debugging)
|
||||
const payload = jwtProvider.decode(token)
|
||||
```
|
||||
|
||||
### Session Provider
|
||||
|
||||
Use server-side sessions for stateful authentication:
|
||||
|
||||
```typescript
|
||||
import { createSessionAuthProvider, type ISessionStorage } from '@esengine/server/auth'
|
||||
|
||||
// Custom storage implementation
|
||||
const storage: ISessionStorage = {
|
||||
async get<T>(key: string): Promise<T | null> {
|
||||
return await redis.get(key)
|
||||
},
|
||||
async set<T>(key: string, value: T): Promise<void> {
|
||||
await redis.set(key, value)
|
||||
},
|
||||
async delete(key: string): Promise<boolean> {
|
||||
return await redis.del(key) > 0
|
||||
},
|
||||
}
|
||||
|
||||
const sessionProvider = createSessionAuthProvider({
|
||||
storage,
|
||||
sessionTTL: 86400000, // 24 hours in ms
|
||||
|
||||
// Optional: validate user on each request
|
||||
validateUser: (user) => !user.banned,
|
||||
})
|
||||
|
||||
// Create session (for login endpoints)
|
||||
const sessionId = await sessionProvider.createSession(user, {
|
||||
ipAddress: req.ip,
|
||||
userAgent: req.headers['user-agent'],
|
||||
})
|
||||
|
||||
// Revoke session (for logout)
|
||||
await sessionProvider.revoke(sessionId)
|
||||
```
|
||||
|
||||
## Server Auth Mixin
|
||||
|
||||
The `withAuth` function wraps your server to add authentication:
|
||||
|
||||
```typescript
|
||||
import { withAuth } from '@esengine/server/auth'
|
||||
|
||||
const server = withAuth(baseServer, {
|
||||
// Required: auth provider
|
||||
provider: jwtProvider,
|
||||
|
||||
// Required: extract credentials from request
|
||||
extractCredentials: (req) => {
|
||||
// From query string
|
||||
return new URL(req.url, 'http://localhost').searchParams.get('token')
|
||||
|
||||
// Or from headers
|
||||
// return req.headers['authorization']?.replace('Bearer ', '')
|
||||
},
|
||||
|
||||
// Optional: handle auth failure
|
||||
onAuthFailed: (conn, error) => {
|
||||
console.log(`Auth failed: ${error}`)
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Accessing Auth Context
|
||||
|
||||
After authentication, the auth context is available on connections:
|
||||
|
||||
```typescript
|
||||
import { getAuthContext } from '@esengine/server/auth'
|
||||
|
||||
server.onConnect = (conn) => {
|
||||
const auth = getAuthContext(conn)
|
||||
|
||||
if (auth.isAuthenticated) {
|
||||
console.log(`User ${auth.userId} connected`)
|
||||
console.log(`Roles: ${auth.roles}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Room Auth Mixin
|
||||
|
||||
The `withRoomAuth` function adds authentication checks to rooms:
|
||||
|
||||
```typescript
|
||||
import { withRoomAuth, type AuthPlayer } from '@esengine/server/auth'
|
||||
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
roles: string[]
|
||||
}
|
||||
|
||||
class GameRoom extends withRoomAuth<User>(Room, {
|
||||
// Require authentication to join
|
||||
requireAuth: true,
|
||||
|
||||
// Optional: require specific roles
|
||||
allowedRoles: ['player', 'premium'],
|
||||
|
||||
// Optional: role check mode ('any' or 'all')
|
||||
roleCheckMode: 'any',
|
||||
}) {
|
||||
// player has .auth and .user properties
|
||||
onJoin(player: AuthPlayer<User>) {
|
||||
console.log(`${player.user?.name} joined`)
|
||||
console.log(`Is premium: ${player.auth.hasRole('premium')}`)
|
||||
}
|
||||
|
||||
// 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,
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### AuthPlayer Interface
|
||||
|
||||
Players in auth rooms have additional properties:
|
||||
|
||||
```typescript
|
||||
interface AuthPlayer<TUser> extends Player {
|
||||
// Full auth context
|
||||
readonly auth: IAuthContext<TUser>
|
||||
|
||||
// User info (shortcut for auth.user)
|
||||
readonly user: TUser | null
|
||||
}
|
||||
```
|
||||
|
||||
### Room Auth Helpers
|
||||
|
||||
```typescript
|
||||
class GameRoom extends withRoomAuth<User>(Room) {
|
||||
someMethod() {
|
||||
// Get player by user ID
|
||||
const player = this.getPlayerByUserId('user-123')
|
||||
|
||||
// Get all players with a role
|
||||
const admins = this.getPlayersByRole('admin')
|
||||
|
||||
// Get player with auth info
|
||||
const authPlayer = this.getAuthPlayer(playerId)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Auth Decorators
|
||||
|
||||
### @requireAuth
|
||||
|
||||
Mark message handlers as requiring authentication:
|
||||
|
||||
```typescript
|
||||
import { requireAuth, requireRole, onMessage } from '@esengine/server/auth'
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### @requireRole
|
||||
|
||||
Require specific roles for message handlers:
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Auth Context API
|
||||
|
||||
The auth context provides various methods for checking authentication state:
|
||||
|
||||
```typescript
|
||||
interface IAuthContext<TUser> {
|
||||
// Authentication state
|
||||
readonly isAuthenticated: boolean
|
||||
readonly user: TUser | null
|
||||
readonly userId: string | null
|
||||
readonly roles: ReadonlyArray<string>
|
||||
readonly authenticatedAt: number | null
|
||||
readonly expiresAt: number | null
|
||||
|
||||
// Role checking
|
||||
hasRole(role: string): boolean
|
||||
hasAnyRole(roles: string[]): boolean
|
||||
hasAllRoles(roles: string[]): boolean
|
||||
}
|
||||
```
|
||||
|
||||
The `AuthContext` class (implementation) also provides:
|
||||
|
||||
```typescript
|
||||
class AuthContext<TUser> implements IAuthContext<TUser> {
|
||||
// Set authentication from result
|
||||
setAuthenticated(result: AuthResult<TUser>): void
|
||||
|
||||
// Clear authentication state
|
||||
clear(): void
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Use the mock auth provider for unit tests:
|
||||
|
||||
```typescript
|
||||
import { createMockAuthProvider } from '@esengine/server/auth/testing'
|
||||
|
||||
// Create mock provider with preset users
|
||||
const mockProvider = createMockAuthProvider({
|
||||
users: [
|
||||
{ id: '1', name: 'Alice', roles: ['player'] },
|
||||
{ id: '2', name: 'Bob', roles: ['admin', 'player'] },
|
||||
],
|
||||
autoCreate: true, // Create users for unknown tokens
|
||||
})
|
||||
|
||||
// Use in tests
|
||||
const server = withAuth(testServer, {
|
||||
provider: mockProvider,
|
||||
extractCredentials: (req) => req.headers['x-token'],
|
||||
})
|
||||
|
||||
// Verify with user ID as token
|
||||
const result = await mockProvider.verify('1')
|
||||
// result.user = { id: '1', name: 'Alice', roles: ['player'] }
|
||||
|
||||
// Add/remove users dynamically
|
||||
mockProvider.addUser({ id: '3', name: 'Charlie', roles: ['guest'] })
|
||||
mockProvider.removeUser('3')
|
||||
|
||||
// Revoke tokens
|
||||
await mockProvider.revoke('1')
|
||||
|
||||
// Reset to initial state
|
||||
mockProvider.clear()
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Auth errors include error codes for programmatic handling:
|
||||
|
||||
```typescript
|
||||
type AuthErrorCode =
|
||||
| 'INVALID_CREDENTIALS' // Invalid username/password
|
||||
| 'INVALID_TOKEN' // Token is malformed or invalid
|
||||
| 'EXPIRED_TOKEN' // Token has expired
|
||||
| 'USER_NOT_FOUND' // User lookup failed
|
||||
| 'ACCOUNT_DISABLED' // User account is disabled
|
||||
| 'RATE_LIMITED' // Too many requests
|
||||
| 'INSUFFICIENT_PERMISSIONS' // Insufficient permissions
|
||||
|
||||
// In your auth failure handler
|
||||
const server = withAuth(baseServer, {
|
||||
provider: jwtProvider,
|
||||
extractCredentials,
|
||||
onAuthFailed: (conn, error) => {
|
||||
switch (error.errorCode) {
|
||||
case 'EXPIRED_TOKEN':
|
||||
conn.send('AuthError', { code: 'TOKEN_EXPIRED' })
|
||||
break
|
||||
case 'INVALID_TOKEN':
|
||||
conn.send('AuthError', { code: 'INVALID_TOKEN' })
|
||||
break
|
||||
default:
|
||||
conn.close()
|
||||
}
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a complete example with JWT authentication:
|
||||
|
||||
```typescript
|
||||
// server.ts
|
||||
import { createServer } from '@esengine/server'
|
||||
import {
|
||||
withAuth,
|
||||
withRoomAuth,
|
||||
createJwtAuthProvider,
|
||||
requireAuth,
|
||||
requireRole,
|
||||
type AuthPlayer,
|
||||
} from '@esengine/server/auth'
|
||||
|
||||
// Types
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
roles: string[]
|
||||
}
|
||||
|
||||
// JWT Provider
|
||||
const jwtProvider = createJwtAuthProvider<User>({
|
||||
secret: process.env.JWT_SECRET!,
|
||||
expiresIn: 3600,
|
||||
getUser: async (payload) => ({
|
||||
id: payload.sub as string,
|
||||
name: payload.name as string,
|
||||
roles: (payload.roles as string[]) ?? [],
|
||||
}),
|
||||
})
|
||||
|
||||
// Create authenticated server
|
||||
const server = withAuth(
|
||||
await createServer({ port: 3000 }),
|
||||
{
|
||||
provider: jwtProvider,
|
||||
extractCredentials: (req) => {
|
||||
return new URL(req.url ?? '', 'http://localhost')
|
||||
.searchParams.get('token')
|
||||
},
|
||||
}
|
||||
)
|
||||
|
||||
// Game Room with auth
|
||||
class GameRoom extends withRoomAuth<User>(Room, {
|
||||
requireAuth: true,
|
||||
allowedRoles: ['player'],
|
||||
}) {
|
||||
onCreate() {
|
||||
console.log('Game room created')
|
||||
}
|
||||
|
||||
onJoin(player: AuthPlayer<User>) {
|
||||
console.log(`${player.user?.name} joined!`)
|
||||
this.broadcast('PlayerJoined', {
|
||||
id: player.id,
|
||||
name: player.user?.name,
|
||||
})
|
||||
}
|
||||
|
||||
@requireAuth()
|
||||
@onMessage('Move')
|
||||
handleMove(data: { x: number; y: number }, player: AuthPlayer<User>) {
|
||||
// Handle movement
|
||||
}
|
||||
|
||||
@requireRole('admin')
|
||||
@onMessage('Kick')
|
||||
handleKick(data: { playerId: string }, player: AuthPlayer<User>) {
|
||||
const target = this.getPlayer(data.playerId)
|
||||
if (target) {
|
||||
this.kick(target, 'Kicked by admin')
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
server.define('game', GameRoom)
|
||||
await server.start()
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Secure your secrets**: Never hardcode JWT secrets. Use environment variables.
|
||||
|
||||
2. **Set reasonable expiration**: Balance security and user experience when setting token TTL.
|
||||
|
||||
3. **Validate on critical actions**: Use `@requireAuth` on sensitive message handlers.
|
||||
|
||||
4. **Use role-based access**: Implement proper role hierarchy for admin functions.
|
||||
|
||||
5. **Handle token refresh**: Implement token refresh logic for long sessions.
|
||||
|
||||
6. **Log auth events**: Track login attempts and failures for security monitoring.
|
||||
|
||||
7. **Test auth flows**: Use `MockAuthProvider` to test authentication scenarios.
|
||||
506
docs/src/content/docs/modules/network/auth.md
Normal file
506
docs/src/content/docs/modules/network/auth.md
Normal file
@@ -0,0 +1,506 @@
|
||||
---
|
||||
title: "认证系统"
|
||||
description: "使用 JWT 和 Session 提供者为游戏服务器添加认证功能"
|
||||
---
|
||||
|
||||
`@esengine/server` 包内置了可插拔的认证系统，支持 JWT、会话认证和自定义提供者。
|
||||
|
||||
## 安装
|
||||
|
||||
认证功能已包含在 server 包中：
|
||||
|
||||
```bash
|
||||
npm install @esengine/server jsonwebtoken
|
||||
```
|
||||
|
||||
> 注意：`jsonwebtoken` 是可选的 peer dependency，仅在使用 JWT 认证时需要。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### JWT 认证
|
||||
|
||||
```typescript
|
||||
import { createServer } from '@esengine/server'
|
||||
import { withAuth, createJwtAuthProvider, withRoomAuth, requireAuth } from '@esengine/server/auth'
|
||||
|
||||
// 创建 JWT 提供者
|
||||
const jwtProvider = createJwtAuthProvider({
|
||||
secret: process.env.JWT_SECRET!,
|
||||
expiresIn: 3600, // 1 小时
|
||||
})
|
||||
|
||||
// 用认证包装服务器
|
||||
const server = withAuth(await createServer({ port: 3000 }), {
|
||||
provider: jwtProvider,
|
||||
extractCredentials: (req) => {
|
||||
const url = new URL(req.url ?? '', 'http://localhost')
|
||||
return url.searchParams.get('token')
|
||||
},
|
||||
})
|
||||
|
||||
// 定义需要认证的房间
|
||||
class GameRoom extends withRoomAuth(Room, { requireAuth: true }) {
|
||||
onJoin(player) {
|
||||
console.log(`${player.user?.name} 加入了游戏！`)
|
||||
}
|
||||
}
|
||||
|
||||
server.define('game', GameRoom)
|
||||
await server.start()
|
||||
```
|
||||
|
||||
## 认证提供者
|
||||
|
||||
### JWT 提供者
|
||||
|
||||
使用 JSON Web Tokens 实现无状态认证：
|
||||
|
||||
```typescript
|
||||
import { createJwtAuthProvider } from '@esengine/server/auth'
|
||||
|
||||
const jwtProvider = createJwtAuthProvider({
|
||||
// 必填：密钥
|
||||
secret: 'your-secret-key',
|
||||
|
||||
// 可选：算法（默认：HS256）
|
||||
algorithm: 'HS256',
|
||||
|
||||
// 可选：过期时间（秒，默认：3600）
|
||||
expiresIn: 3600,
|
||||
|
||||
// 可选：签发者（用于验证）
|
||||
issuer: 'my-game-server',
|
||||
|
||||
// 可选：受众（用于验证）
|
||||
audience: 'my-game-client',
|
||||
|
||||
// 可选：自定义用户提取
|
||||
getUser: async (payload) => {
|
||||
// 从数据库获取用户
|
||||
return await db.users.findById(payload.sub)
|
||||
},
|
||||
})
|
||||
|
||||
// 签发令牌（用于登录接口）
|
||||
const token = jwtProvider.sign({
|
||||
sub: user.id,
|
||||
name: user.name,
|
||||
roles: ['player'],
|
||||
})
|
||||
|
||||
// 解码但不验证（用于调试）
|
||||
const payload = jwtProvider.decode(token)
|
||||
```
|
||||
|
||||
### Session 提供者
|
||||
|
||||
使用服务端会话实现有状态认证：
|
||||
|
||||
```typescript
|
||||
import { createSessionAuthProvider, type ISessionStorage } from '@esengine/server/auth'
|
||||
|
||||
// 自定义存储实现
|
||||
const storage: ISessionStorage = {
|
||||
async get<T>(key: string): Promise<T | null> {
|
||||
return await redis.get(key)
|
||||
},
|
||||
async set<T>(key: string, value: T): Promise<void> {
|
||||
await redis.set(key, value)
|
||||
},
|
||||
async delete(key: string): Promise<boolean> {
|
||||
return await redis.del(key) > 0
|
||||
},
|
||||
}
|
||||
|
||||
const sessionProvider = createSessionAuthProvider({
|
||||
storage,
|
||||
sessionTTL: 86400000, // 24 小时（毫秒）
|
||||
|
||||
// 可选：每次请求时验证用户
|
||||
validateUser: (user) => !user.banned,
|
||||
})
|
||||
|
||||
// 创建会话（用于登录接口）
|
||||
const sessionId = await sessionProvider.createSession(user, {
|
||||
ipAddress: req.ip,
|
||||
userAgent: req.headers['user-agent'],
|
||||
})
|
||||
|
||||
// 撤销会话（用于登出）
|
||||
await sessionProvider.revoke(sessionId)
|
||||
```
|
||||
|
||||
## 服务器认证 Mixin
|
||||
|
||||
`withAuth` 函数用于包装服务器添加认证功能：
|
||||
|
||||
```typescript
|
||||
import { withAuth } from '@esengine/server/auth'
|
||||
|
||||
const server = withAuth(baseServer, {
|
||||
// 必填：认证提供者
|
||||
provider: jwtProvider,
|
||||
|
||||
// 必填：从请求中提取凭证
|
||||
extractCredentials: (req) => {
|
||||
// 从查询字符串获取
|
||||
return new URL(req.url, 'http://localhost').searchParams.get('token')
|
||||
|
||||
// 或从请求头获取
|
||||
// return req.headers['authorization']?.replace('Bearer ', '')
|
||||
},
|
||||
|
||||
// 可选：处理认证失败
|
||||
onAuthFailed: (conn, error) => {
|
||||
console.log(`认证失败: ${error}`)
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### 访问认证上下文
|
||||
|
||||
认证后，可以从连接获取认证上下文：
|
||||
|
||||
```typescript
|
||||
import { getAuthContext } from '@esengine/server/auth'
|
||||
|
||||
server.onConnect = (conn) => {
|
||||
const auth = getAuthContext(conn)
|
||||
|
||||
if (auth.isAuthenticated) {
|
||||
console.log(`用户 ${auth.userId} 已连接`)
|
||||
console.log(`角色: ${auth.roles}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 房间认证 Mixin
|
||||
|
||||
`withRoomAuth` 函数为房间添加认证检查：
|
||||
|
||||
```typescript
|
||||
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'],
|
||||
|
||||
// 可选：角色检查模式（'any' 或 'all'）
|
||||
roleCheckMode: 'any',
|
||||
}) {
|
||||
// player 拥有 .auth 和 .user 属性
|
||||
onJoin(player: AuthPlayer<User>) {
|
||||
console.log(`${player.user?.name} 加入了`)
|
||||
console.log(`是否高级会员: ${player.auth.hasRole('premium')}`)
|
||||
}
|
||||
|
||||
// 可选：自定义认证验证
|
||||
async onAuth(player: AuthPlayer<User>): Promise<boolean> {
|
||||
// 额外的验证逻辑
|
||||
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 ?? '访客',
|
||||
text: data.text,
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### AuthPlayer 接口
|
||||
|
||||
认证房间中的玩家拥有额外属性：
|
||||
|
||||
```typescript
|
||||
interface AuthPlayer<TUser> extends Player {
|
||||
// 完整认证上下文
|
||||
readonly auth: IAuthContext<TUser>
|
||||
|
||||
// 用户信息（auth.user 的快捷方式）
|
||||
readonly user: TUser | null
|
||||
}
|
||||
```
|
||||
|
||||
### 房间认证辅助方法
|
||||
|
||||
```typescript
|
||||
class GameRoom extends withRoomAuth<User>(Room) {
|
||||
someMethod() {
|
||||
// 通过用户 ID 获取玩家
|
||||
const player = this.getPlayerByUserId('user-123')
|
||||
|
||||
// 获取拥有特定角色的所有玩家
|
||||
const admins = this.getPlayersByRole('admin')
|
||||
|
||||
// 获取带认证信息的玩家
|
||||
const authPlayer = this.getAuthPlayer(playerId)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 认证装饰器
|
||||
|
||||
### @requireAuth
|
||||
|
||||
标记消息处理器需要认证：
|
||||
|
||||
```typescript
|
||||
import { requireAuth, requireRole, onMessage } from '@esengine/server/auth'
|
||||
|
||||
class GameRoom extends withRoomAuth(Room) {
|
||||
@requireAuth()
|
||||
@onMessage('Trade')
|
||||
handleTrade(data: TradeData, player: AuthPlayer) {
|
||||
// 只有已认证玩家才能交易
|
||||
}
|
||||
|
||||
@requireAuth({ allowGuest: true })
|
||||
@onMessage('Chat')
|
||||
handleChat(data: ChatData, player: AuthPlayer) {
|
||||
// 访客也可以聊天
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### @requireRole
|
||||
|
||||
要求特定角色才能访问消息处理器：
|
||||
|
||||
```typescript
|
||||
class AdminRoom extends withRoomAuth(Room) {
|
||||
@requireRole('admin')
|
||||
@onMessage('Ban')
|
||||
handleBan(data: BanData, player: AuthPlayer) {
|
||||
// 只有管理员才能封禁
|
||||
}
|
||||
|
||||
@requireRole(['moderator', 'admin'])
|
||||
@onMessage('Mute')
|
||||
handleMute(data: MuteData, player: AuthPlayer) {
|
||||
// 版主或管理员可以禁言
|
||||
}
|
||||
|
||||
@requireRole(['verified', 'premium'], { mode: 'all' })
|
||||
@onMessage('SpecialFeature')
|
||||
handleSpecial(data: any, player: AuthPlayer) {
|
||||
// 需要同时拥有 verified 和 premium 角色
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 认证上下文 API
|
||||
|
||||
认证上下文提供多种检查认证状态的方法：
|
||||
|
||||
```typescript
|
||||
interface IAuthContext<TUser> {
|
||||
// 认证状态
|
||||
readonly isAuthenticated: boolean
|
||||
readonly user: TUser | null
|
||||
readonly userId: string | null
|
||||
readonly roles: ReadonlyArray<string>
|
||||
readonly authenticatedAt: number | null
|
||||
readonly expiresAt: number | null
|
||||
|
||||
// 角色检查
|
||||
hasRole(role: string): boolean
|
||||
hasAnyRole(roles: string[]): boolean
|
||||
hasAllRoles(roles: string[]): boolean
|
||||
}
|
||||
```
|
||||
|
||||
`AuthContext` 类（实现类）还提供：
|
||||
|
||||
```typescript
|
||||
class AuthContext<TUser> implements IAuthContext<TUser> {
|
||||
// 从认证结果设置认证状态
|
||||
setAuthenticated(result: AuthResult<TUser>): void
|
||||
|
||||
// 清除认证状态
|
||||
clear(): void
|
||||
}
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
使用模拟认证提供者进行单元测试：
|
||||
|
||||
```typescript
|
||||
import { createMockAuthProvider } from '@esengine/server/auth/testing'
|
||||
|
||||
// 创建带预设用户的模拟提供者
|
||||
const mockProvider = createMockAuthProvider({
|
||||
users: [
|
||||
{ id: '1', name: 'Alice', roles: ['player'] },
|
||||
{ id: '2', name: 'Bob', roles: ['admin', 'player'] },
|
||||
],
|
||||
autoCreate: true, // 为未知令牌创建用户
|
||||
})
|
||||
|
||||
// 在测试中使用
|
||||
const server = withAuth(testServer, {
|
||||
provider: mockProvider,
|
||||
extractCredentials: (req) => req.headers['x-token'],
|
||||
})
|
||||
|
||||
// 使用用户 ID 作为令牌进行验证
|
||||
const result = await mockProvider.verify('1')
|
||||
// result.user = { id: '1', name: 'Alice', roles: ['player'] }
|
||||
|
||||
// 动态添加/移除用户
|
||||
mockProvider.addUser({ id: '3', name: 'Charlie', roles: ['guest'] })
|
||||
mockProvider.removeUser('3')
|
||||
|
||||
// 撤销令牌
|
||||
await mockProvider.revoke('1')
|
||||
|
||||
// 重置到初始状态
|
||||
mockProvider.clear()
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
认证错误包含错误码用于程序化处理：
|
||||
|
||||
```typescript
|
||||
type AuthErrorCode =
|
||||
| 'INVALID_CREDENTIALS' // 用户名/密码无效
|
||||
| 'INVALID_TOKEN' // 令牌格式错误或无效
|
||||
| 'EXPIRED_TOKEN' // 令牌已过期
|
||||
| 'USER_NOT_FOUND' // 用户查找失败
|
||||
| 'ACCOUNT_DISABLED' // 用户账号已禁用
|
||||
| 'RATE_LIMITED' // 请求过于频繁
|
||||
| 'INSUFFICIENT_PERMISSIONS' // 权限不足
|
||||
|
||||
// 在认证失败处理器中
|
||||
const server = withAuth(baseServer, {
|
||||
provider: jwtProvider,
|
||||
extractCredentials,
|
||||
onAuthFailed: (conn, error) => {
|
||||
switch (error.errorCode) {
|
||||
case 'EXPIRED_TOKEN':
|
||||
conn.send('AuthError', { code: 'TOKEN_EXPIRED' })
|
||||
break
|
||||
case 'INVALID_TOKEN':
|
||||
conn.send('AuthError', { code: 'INVALID_TOKEN' })
|
||||
break
|
||||
default:
|
||||
conn.close()
|
||||
}
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## 完整示例
|
||||
|
||||
以下是使用 JWT 认证的完整示例：
|
||||
|
||||
```typescript
|
||||
// server.ts
|
||||
import { createServer } from '@esengine/server'
|
||||
import {
|
||||
withAuth,
|
||||
withRoomAuth,
|
||||
createJwtAuthProvider,
|
||||
requireAuth,
|
||||
requireRole,
|
||||
type AuthPlayer,
|
||||
} from '@esengine/server/auth'
|
||||
|
||||
// 类型定义
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
roles: string[]
|
||||
}
|
||||
|
||||
// JWT 提供者
|
||||
const jwtProvider = createJwtAuthProvider<User>({
|
||||
secret: process.env.JWT_SECRET!,
|
||||
expiresIn: 3600,
|
||||
getUser: async (payload) => ({
|
||||
id: payload.sub as string,
|
||||
name: payload.name as string,
|
||||
roles: (payload.roles as string[]) ?? [],
|
||||
}),
|
||||
})
|
||||
|
||||
// 创建带认证的服务器
|
||||
const server = withAuth(
|
||||
await createServer({ port: 3000 }),
|
||||
{
|
||||
provider: jwtProvider,
|
||||
extractCredentials: (req) => {
|
||||
return new URL(req.url ?? '', 'http://localhost')
|
||||
.searchParams.get('token')
|
||||
},
|
||||
}
|
||||
)
|
||||
|
||||
// 带认证的游戏房间
|
||||
class GameRoom extends withRoomAuth<User>(Room, {
|
||||
requireAuth: true,
|
||||
allowedRoles: ['player'],
|
||||
}) {
|
||||
onCreate() {
|
||||
console.log('游戏房间已创建')
|
||||
}
|
||||
|
||||
onJoin(player: AuthPlayer<User>) {
|
||||
console.log(`${player.user?.name} 加入了！`)
|
||||
this.broadcast('PlayerJoined', {
|
||||
id: player.id,
|
||||
name: player.user?.name,
|
||||
})
|
||||
}
|
||||
|
||||
@requireAuth()
|
||||
@onMessage('Move')
|
||||
handleMove(data: { x: number; y: number }, player: AuthPlayer<User>) {
|
||||
// 处理移动
|
||||
}
|
||||
|
||||
@requireRole('admin')
|
||||
@onMessage('Kick')
|
||||
handleKick(data: { playerId: string }, player: AuthPlayer<User>) {
|
||||
const target = this.getPlayer(data.playerId)
|
||||
if (target) {
|
||||
this.kick(target, '被管理员踢出')
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
server.define('game', GameRoom)
|
||||
await server.start()
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **保护密钥安全**：永远不要硬编码 JWT 密钥，使用环境变量。
|
||||
|
||||
2. **设置合理的过期时间**：在安全性和用户体验之间平衡令牌 TTL。
|
||||
|
||||
3. **在关键操作上验证**：在敏感消息处理器上使用 `@requireAuth`。
|
||||
|
||||
4. **使用基于角色的访问控制**：为管理功能实现适当的角色层级。
|
||||
|
||||
5. **处理令牌刷新**：为长会话实现令牌刷新逻辑。
|
||||
|
||||
6. **记录认证事件**：跟踪登录尝试和失败以进行安全监控。
|
||||
|
||||
7. **测试认证流程**：使用 `MockAuthProvider` 测试认证场景。
|
||||
Reference in New Issue
Block a user