@linyjs/plugin-docs 0.0.13

package/docs/best-practices/security.md

@@ -0,0 +1,620 @@
+# 安全性
+
+本指南提供 linyjs 插件开发中的安全最佳实践。
+
+## 为什么需要关注安全？
+
+- 🔒 **保护用户数据** - 防止敏感信息泄露
+- 🛡️ **防止恶意攻击** - 抵御常见网络安全威胁
+- ⚖️ **保持合规性** - 满足隐私保护和数据安全法规
+- 🤝 **建立用户信任** - 安全可靠的应用获得用户信赖
+
+## 输入验证和清理
+
+### 服务端输入验证
+
+```typescript
+// 严格的输入验证
+handler: async (params, ctx) => {
+  const { email, password, age } = params.body;
+
+  // 邮箱格式验证
+  if (!isValidEmail(email)) {
+    return {
+      status: 400,
+      data: { error: 'Invalid email format', field: 'email' }
+    };
+  }
+
+  // 密码强度验证
+  if (!isStrongPassword(password)) {
+    return {
+      status: 400,
+      data: { error: 'Password too weak', field: 'password' }
+    };
+  }
+
+  // 数值范围验证
+  if (!Number.isInteger(age) || age < 0 || age > 150) {
+    return {
+      status: 400,
+      data: { error: 'Invalid age', field: 'age' }
+    };
+  }
+
+  return { success: true };
+};
+
+// 验证函数
+function isValidEmail(email: string): boolean {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email);
+}
+
+function isStrongPassword(password: string): boolean {
+  // 至少8个字符，包含大写、小写、数字和特殊字符
+  const strongPasswordRegex = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/;
+  return strongPasswordRegex.test(password);
+}
+```
+
+### 使用验证库
+
+```typescript
+import * as Joi from 'joi';
+
+// 定义验证模式
+const userSchema = Joi.object({
+  email: Joi.string().email().required(),
+  password: Joi.string().min(8).pattern(new RegExp('^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)')).required(),
+  age: Joi.number().integer().min(0).max(150).required(),
+  role: Joi.string().valid('user', 'admin', 'moderator').optional()
+});
+
+// 在处理器中使用验证
+handler: async (params, ctx) => {
+  const { error, value } = userSchema.validate(params.body);
+
+  if (error) {
+    return {
+      status: 400,
+      data: {
+        error: 'Validation failed',
+        details: error.details.map(detail => ({
+          field: detail.path.join('.'),
+          message: detail.message
+        }))
+      }
+    };
+  }
+
+  // 验证通过，处理业务逻辑
+  return await createUser(value);
+};
+```
+
+## SQL注入和NoSQL注入防护
+
+### MongoDB注入防护
+
+```typescript
+// ✅ 推荐：使用 MongoDB 驱动程序的内置防护
+class SafeUserService {
+  constructor(private mongodb: IMongoDBService) {}
+
+  async findUserByEmail(email: string) {
+    const db = this.mongodb.getDb();
+    const collection = db.collection('users');
+
+    // MongoDB 驱动程序会自动转义参数
+    return collection.findOne({ email: email });
+  }
+
+  async searchUsers(query: string) {
+    const db = this.mongodb.getDb();
+    const collection = db.collection('users');
+
+    // 使用安全的正则表达式查询
+    return collection.find({
+      $or: [
+        { name: { $regex: escapeRegex(query), $options: 'i' } },
+        { email: { $regex: escapeRegex(query), $options: 'i' } }
+      ]
+    }).toArray();
+  }
+}
+
+// 转义正则表达式特殊字符
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ❌ 避免：字符串拼接查询
+const unsafeQuery = `db.users.find({name: "${userInput}"})`; // 危险！
+```
+
+### 参数化查询
+
+```typescript
+// 如果使用原生 SQL，始终使用参数化查询
+async function safeDatabaseQuery(userId: string) {
+  // ✅ 推荐：参数化查询
+  const result = await db.query(
+    'SELECT * FROM users WHERE id = $1',
+    [userId]
+  );
+
+  return result.rows;
+}
+
+// ❌ 避免：字符串拼接
+const unsafeQuery = `SELECT * FROM users WHERE id = ${userId}`; // 危险！
+```
+
+## XSS防护
+
+### 服务端输出编码
+
+```typescript
+// HTML编码函数
+function escapeHtml(text: string): string {
+  const div = document.createElement('div');
+  div.textContent = text;
+  return div.innerHTML;
+}
+
+// 或者使用专业的编码库
+import { encode } from 'html-entities';
+
+function safeOutput(data: any): string {
+  return encode(JSON.stringify(data));
+}
+
+// 在响应中设置安全头
+handler: async (params, ctx) => {
+  ctx.response.setHeader('X-XSS-Protection', '1; mode=block');
+  ctx.response.setHeader('X-Content-Type-Options', 'nosniff');
+  ctx.response.setHeader('X-Frame-Options', 'DENY');
+
+  return { data: safeOutput(data) };
+};
+```
+
+### 客户端XSS防护
+
+```typescript
+// 安全的HTML输出
+function SafeDisplay({ content }: { content: string }) {
+  // ✅ 推荐：转义HTML
+  const escaped = escapeHtml(content);
+  return <div dangerouslySetInnerHTML={{ __html: escaped }} />;
+}
+
+// 或者更安全的文本节点
+function SaferDisplay({ content }: { content: string }) {
+  return <div>{content}</div>; // React会自动转义
+}
+
+// 安全的链接处理
+function SafeLink({ url, text }: { url: string; text: string }) {
+  // 验证URL协议
+  if (!url.startsWith('https://') && !url.startsWith('http://')) {
+    return <span>{text}</span>; // 无效协议显示为文本
+  }
+
+  return (
+    <a
+      href={url}
+      rel="noopener noreferrer"
+      target="_blank"
+    >
+      {text}
+    </a>
+  );
+}
+```
+
+## CSRF防护
+
+### 生成和验证CSRF令牌
+
+```typescript
+// CSRF令牌生成服务
+class CsrfService {
+  private tokens = new Map<string, { token: string; expires: number }>();
+
+  generateToken(sessionId: string): string {
+    const token = crypto.randomBytes(32).toString('hex');
+    const expires = Date.now() + 30 * 60 * 1000; // 30分钟有效期
+
+    this.tokens.set(sessionId, { token, expires });
+    return token;
+  }
+
+  validateToken(sessionId: string, token: string): boolean {
+    const stored = this.tokens.get(sessionId);
+
+    if (!stored || Date.now() > stored.expires) {
+      this.tokens.delete(sessionId);
+      return false;
+    }
+
+    const isValid = stored.token === token;
+    if (isValid) {
+      // 使用后删除令牌（一次性）
+      this.tokens.delete(sessionId);
+    }
+
+    return isValid;
+  }
+}
+
+// CSRF防护中间件
+class CsrfMiddleware implements IMiddlewareService {
+  constructor(private csrfService: CsrfService) {}
+
+  async process(payload: any, ctx: any, next: () => Promise<any>) {
+    const sessionId = ctx.session?.id;
+    const method = ctx.request?.method;
+
+    // 只对修改请求进行CSRF检查
+    if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
+      const csrfToken = ctx.request?.headers['x-csrf-token'] ||
+                       ctx.request?.body?._csrf;
+
+      if (!csrfToken || !this.csrfService.validateToken(sessionId, csrfToken)) {
+        return {
+          status: 403,
+          data: { error: 'Invalid CSRF token' }
+        };
+      }
+    }
+
+    return await next();
+  }
+}
+```
+
+## 身份验证和授权
+
+### JWT安全处理
+
+```typescript
+// 安全的JWT操作
+class AuthService {
+  private readonly JWT_SECRET = process.env.JWT_SECRET!;
+  private readonly JWT_EXPIRES_IN = '24h';
+
+  generateToken(user: any): string {
+    return jwt.sign(
+      {
+        userId: user.id,
+        email: user.email,
+        role: user.role
+      },
+      this.JWT_SECRET,
+      {
+        expiresIn: this.JWT_EXPIRES_IN,
+        issuer: 'linyjs-plugin'
+      }
+    );
+  }
+
+  verifyToken(token: string): any {
+    try {
+      return jwt.verify(token, this.JWT_SECRET);
+    } catch (error) {
+      throw new Error('Invalid token');
+    }
+  }
+
+  // 刷新令牌
+  generateRefreshToken(userId: string): string {
+    return jwt.sign(
+      { userId },
+      this.JWT_SECRET + '_refresh',
+      { expiresIn: '7d' }
+    );
+  }
+}
+
+// 认证中间件
+class AuthMiddleware implements IMiddlewareService {
+  async process(payload: any, ctx: any, next: () => Promise<any>) {
+    const authHeader = ctx.request?.headers.authorization;
+
+    if (!authHeader?.startsWith('Bearer ')) {
+      return {
+        status: 401,
+        data: { error: 'Missing authorization header' }
+      };
+    }
+
+    const token = authHeader.substring(7);
+    const authService = new AuthService();
+
+    try {
+      const decoded = authService.verifyToken(token);
+      ctx.user = decoded; // 将用户信息附加到上下文
+      return await next();
+    } catch (error) {
+      return {
+        status: 401,
+        data: { error: 'Invalid token' }
+      };
+    }
+  }
+}
+```
+
+### 权限检查
+
+```typescript
+// 权限中间件
+class PermissionMiddleware implements IMiddlewareService {
+  constructor(private requiredRole?: string) {}
+
+  async process(payload: any, ctx: any, next: () => Promise<any>) {
+    const user = ctx.user;
+
+    if (!user) {
+      return {
+        status: 401,
+        data: { error: 'Authentication required' }
+      };
+    }
+
+    // 角色检查
+    if (this.requiredRole && user.role !== this.requiredRole) {
+      return {
+        status: 403,
+        data: { error: 'Insufficient permissions' }
+      };
+    }
+
+    // 所有权检查
+    if (payload.userId && user.userId !== payload.userId && user.role !== 'admin') {
+      return {
+        status: 403,
+        data: { error: 'Cannot access other user\'s data' }
+      };
+    }
+
+    return await next();
+  }
+}
+
+// 使用权限中间件
+{
+  middlewares: [
+    'auth',
+    { serviceTag: 'permission', requiredRole: 'admin' }
+  ],
+  handler: async () => {
+    // 只有管理员可以访问
+  }
+}
+```
+
+## 数据安全
+
+### 敏感数据加密
+
+```typescript
+// 数据加密服务
+class EncryptionService {
+  private readonly ENCRYPTION_KEY = process.env.ENCRYPTION_KEY!;
+
+  encrypt(text: string): string {
+    const cipher = crypto.createCipher('aes-256-cbc', this.ENCRYPTION_KEY);
+    let encrypted = cipher.update(text, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    return encrypted;
+  }
+
+  decrypt(encryptedText: string): string {
+    const decipher = crypto.createDecipher('aes-256-cbc', this.ENCRYPTION_KEY);
+    let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+  }
+}
+
+// 安全的密码哈希
+import * as bcrypt from 'bcrypt';
+
+class PasswordService {
+  private readonly SALT_ROUNDS = 12;
+
+  async hashPassword(password: string): Promise<string> {
+    return await bcrypt.hash(password, this.SALT_ROUNDS);
+  }
+
+  async verifyPassword(password: string, hash: string): Promise<boolean> {
+    return await bcrypt.compare(password, hash);
+  }
+}
+```
+
+### 安全的数据传输
+
+```typescript
+// 强制HTTPS
+handler: async (params, ctx) => {
+  if (ctx.request?.protocol !== 'https') {
+    return {
+      status: 403,
+      data: { error: 'HTTPS required' }
+    };
+  }
+
+  // 设置安全头
+  ctx.response.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+  ctx.response.setHeader('Content-Security-Policy', "default-src 'self'");
+
+  return { data: 'secure response' };
+};
+```
+
+## 日志记录和监控
+
+### 安全日志记录
+
+```typescript
+// 安全日志服务
+class SecurityLogger {
+  constructor(private logger: ILogger) {}
+
+  logSecurityEvent(event: string, details: any) {
+    // 脱敏处理敏感信息
+    const sanitizedDetails = this.sanitizeData(details);
+
+    this.logger.warn('Security Event', {
+      event,
+      ...sanitizedDetails,
+      timestamp: new Date().toISOString(),
+      ip: this.getClientIp(),
+      userAgent: this.getUserAgent()
+    });
+  }
+
+  private sanitizeData(data: any): any {
+    const sanitized = { ...data };
+
+    // 移除或遮盖敏感字段
+    const sensitiveFields = ['password', 'token', 'creditCard', 'ssn'];
+    for (const field of sensitiveFields) {
+      if (sanitized[field]) {
+        sanitized[field] = '[REDACTED]';
+      }
+    }
+
+    return sanitized;
+  }
+
+  private getClientIp(): string {
+    // 获取客户端IP，考虑代理
+    return 'client-ip';
+  }
+
+  private getUserAgent(): string {
+    // 获取用户代理
+    return 'user-agent';
+  }
+}
+
+// 记录安全事件
+class LoginAttemptsService {
+  private attempts = new Map<string, number>();
+  private readonly MAX_ATTEMPTS = 5;
+  private readonly LOCKOUT_DURATION = 15 * 60 * 1000; // 15分钟
+
+  async checkLoginAttempts(ip: string): Promise<boolean> {
+    const attempts = this.attempts.get(ip) || 0;
+    return attempts < this.MAX_ATTEMPTS;
+  }
+
+  recordFailedAttempt(ip: string) {
+    const attempts = (this.attempts.get(ip) || 0) + 1;
+    this.attempts.set(ip, attempts);
+
+    // 锁定IP
+    if (attempts >= this.MAX_ATTEMPTS) {
+      setTimeout(() => {
+        this.attempts.delete(ip);
+      }, this.LOCKOUT_DURATION);
+
+      // 记录安全事件
+      const securityLogger = new SecurityLogger(logger);
+      securityLogger.logSecurityEvent('ACCOUNT_LOCKOUT', { ip, attempts });
+    }
+  }
+}
+```
+
+## 安全配置
+
+### 安全HTTP头
+
+```typescript
+// 安全头中间件
+class SecurityHeadersMiddleware implements IMiddlewareService {
+  async process(payload: any, ctx: any, next: () => Promise<any>) {
+    // 设置安全HTTP头
+    ctx.response.setHeader('X-Content-Type-Options', 'nosniff');
+    ctx.response.setHeader('X-Frame-Options', 'DENY');
+    ctx.response.setHeader('X-XSS-Protection', '1; mode=block');
+    ctx.response.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+    ctx.response.setHeader('Permissions-Policy', 'geolocation=(), microphone=()');
+
+    // Content Security Policy
+    ctx.response.setHeader(
+      'Content-Security-Policy',
+      [
+        "default-src 'self'",
+        "script-src 'self' 'unsafe-inline'",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data: https:",
+        "connect-src 'self'",
+        "font-src 'self'"
+      ].join('; ')
+    );
+
+    return await next();
+  }
+}
+```
+
+### 依赖安全
+
+```json
+{
+  "scripts": {
+    "audit": "npm audit",
+    "audit:fix": "npm audit fix",
+    "audit:ci": "npm audit --audit-level=high"
+  }
+}
+```
+
+## 安全清单
+
+### 开发和测试
+
+- ✅ 启用依赖审计`npm audit`
+- ✅ 使用安全linting规则
+- ✅ 实施代码审查流程
+- ✅ 定期安全扫描
+
+### 构建和部署
+
+- ✅ 最小化生产依赖
+- ✅ 移除调试代码
+- ✅ 环境变量管理密钥
+- ✅ 启用安全传输
+
+### 运行时
+
+- ✅ 输入验证和清理
+- ✅ 安全的错误处理
+- ✅ 适当的身份验证和授权
+- ✅ 安全的会话管理
+- ✅ 日志脱敏
+- ✅ 监控和警报
+
+## 完整示例
+
+查看安全实践:
+
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/) - 完整的用户认证实现
+- 📁 [Analytics Plugin 示例](../../examples/analytics-plugin/) - 数据安全处理
+
+## 相关文档
+
+- 📝 [命名规范](./naming-conventions.md)
+- ⚠️ [错误处理](./error-handling.md)
+- ⚡ [性能优化](./performance.md)
+
+---
+
+**上一篇**: [性能优化](./performance.md) | **下一篇**: [FAQ](../faq.md)