@f2a/network 0.1.2 → 0.2.0

package/src/utils/middleware.ts

@@ -1,229 +0,0 @@
-/**
- * F2A 中间件系统
- * 支持消息拦截、过滤和转换
- */
-
-import { F2AMessage, AgentInfo } from '../types/index.js';
-import { Logger } from './logger.js';
-
-export interface MiddlewareContext {
-  /** 消息 */
-  message: F2AMessage;
-  /** 发送方 Peer ID */
-  peerId: string;
-  /** 发送方 Agent 信息 */
-  agentInfo?: AgentInfo;
-  /** 中间件元数据 */
-  metadata: Map<string, unknown>;
-}
-
-export type MiddlewareResult = 
-  | { action: 'continue'; context: MiddlewareContext }
-  | { action: 'drop'; reason: string }
-  | { action: 'modify'; context: MiddlewareContext };
-
-export interface Middleware {
-  /** 中间件名称 */
-  name: string;
-  /** 执行优先级（数字越小优先级越高） */
-  priority?: number;
-  /** 
-   * 中间件类型
-   * - 'essential': 核心中间件，异常时中断链
-   * - 'optional': 可选中间件，异常时继续处理
-   */
-  type?: 'essential' | 'optional';
-  /** 处理函数 */
-  process(context: MiddlewareContext): Promise<MiddlewareResult> | MiddlewareResult;
-}
-
-/**
- * 中间件管理器
- */
-export class MiddlewareManager {
-  private middlewares: Middleware[] = [];
-  private logger: Logger;
-
-  constructor() {
-    this.logger = new Logger({ component: 'MiddlewareManager' });
-  }
-
-  /**
-   * 注册中间件
-   */
-  use(middleware: Middleware): void {
-    this.middlewares.push(middleware);
-    // 按优先级排序
-    this.middlewares.sort((a, b) => (a.priority || 0) - (b.priority || 0));
-    this.logger.info('Registered middleware', { name: middleware.name });
-  }
-
-  /**
-   * 移除中间件
-   */
-  remove(name: string): boolean {
-    const index = this.middlewares.findIndex(m => m.name === name);
-    if (index !== -1) {
-      this.middlewares.splice(index, 1);
-      this.logger.info('Removed middleware', { name });
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * 执行中间件链
-   */
-  async execute(context: MiddlewareContext): Promise<MiddlewareResult> {
-    let currentContext = context;
-
-    for (const middleware of this.middlewares) {
-      try {
-        const result = await middleware.process(currentContext);
-
-        if (result.action === 'drop') {
-          this.logger.info('Message dropped by middleware', {
-            middleware: middleware.name,
-            reason: result.reason
-          });
-          return result;
-        }
-
-        if (result.action === 'modify') {
-          currentContext = result.context;
-        }
-      } catch (error) {
-        this.logger.error('Middleware error', {
-          middleware: middleware.name,
-          error,
-          type: middleware.type || 'optional'
-        });
-        
-        // 根据中间件类型决定是否中断链
-        // essential: 核心中间件，异常时中断链，返回 drop
-        // optional: 可选中间件，异常时继续处理（原有行为）
-        const middlewareType = middleware.type || 'optional';
-        
-        if (middlewareType === 'essential') {
-          this.logger.warn('Essential middleware failed, aborting chain', {
-            middleware: middleware.name
-          });
-          return {
-            action: 'drop',
-            reason: `Essential middleware ${middleware.name} failed: ${error instanceof Error ? error.message : String(error)}`
-          };
-        }
-        
-        // optional 中间件出错时继续处理，不阻塞消息
-        this.logger.info('Optional middleware failed, continuing chain', {
-          middleware: middleware.name
-        });
-      }
-    }
-
-    return { action: 'continue', context: currentContext };
-  }
-
-  /**
-   * 获取已注册的中间件列表
-   */
-  list(): string[] {
-    return this.middlewares.map(m => m.name);
-  }
-
-  /**
-   * 清空所有中间件
-   */
-  clear(): void {
-    this.middlewares = [];
-    this.logger.info('Cleared all middlewares');
-  }
-}
-
-// ============================================================================
-// 内置中间件
-// ============================================================================
-
-/**
- * 消息大小限制中间件
- */
-export function createMessageSizeLimitMiddleware(maxSize: number): Middleware {
-  return {
-    name: 'MessageSizeLimit',
-    priority: 100, // 高优先级，尽早检查
-    process(context: MiddlewareContext): MiddlewareResult {
-      const messageSize = JSON.stringify(context.message).length;
-      if (messageSize > maxSize) {
-        return {
-          action: 'drop',
-          reason: `Message size ${messageSize} exceeds limit ${maxSize}`
-        };
-      }
-      return { action: 'continue', context };
-    }
-  };
-}
-
-/**
- * 消息类型过滤中间件
- */
-export function createMessageTypeFilterMiddleware(
-  allowedTypes: string[]
-): Middleware {
-  return {
-    name: 'MessageTypeFilter',
-    priority: 90,
-    process(context: MiddlewareContext): MiddlewareResult {
-      if (!allowedTypes.includes(context.message.type)) {
-        return {
-          action: 'drop',
-          reason: `Message type ${context.message.type} not allowed`
-        };
-      }
-      return { action: 'continue', context };
-    }
-  };
-}
-
-/**
- * 消息日志中间件
- */
-export function createMessageLoggingMiddleware(
-  logger?: Logger
-): Middleware {
-  const log = logger || new Logger({ component: 'MessageLogger' });
-  return {
-    name: 'MessageLogger',
-    priority: 50, // 中等优先级
-    process(context: MiddlewareContext): MiddlewareResult {
-      log.debug('Processing message', {
-        type: context.message.type,
-        from: context.peerId.slice(0, 16),
-        id: context.message.id
-      });
-      return { action: 'continue', context };
-    }
-  };
-}
-
-/**
- * 消息转换中间件示例
- */
-export function createMessageTransformMiddleware(
-  transform: (msg: F2AMessage) => F2AMessage
-): Middleware {
-  return {
-    name: 'MessageTransform',
-    priority: 10, // 低优先级，最后执行
-    process(context: MiddlewareContext): MiddlewareResult {
-      const transformedMessage = transform(context.message);
-      return {
-        action: 'modify',
-        context: {
-          ...context,
-          message: transformedMessage
-        }
-      };
-    }
-  };
-}

package/src/utils/rate-limiter.ts

@@ -1,207 +0,0 @@
-/**
- * 速率限制中间件
- * 基于 Token Bucket 算法实现，支持突发流量
- */
-
-import { Logger } from './logger.js';
-
-export interface RateLimitConfig {
-  /** 最大请求数 */
-  maxRequests: number;
-  /** 时间窗口（毫秒） */
-  windowMs: number;
-  /** 是否跳过成功请求 */
-  skipSuccessfulRequests?: boolean;
-  /** 突发容量倍数（默认 1.5，允许短暂的请求爆发） */
-  burstMultiplier?: number;
-}
-
-export interface RateLimitEntry {
-  tokens: number;
-  lastRefill: number;
-}
-
-/**
- * 速率限制器
- * 实现 Disposable 接口，确保资源正确释放
- */
-export class RateLimiter implements Disposable {
-  private config: Required<RateLimitConfig>;
-  private burstCapacity: number;
-  private store: Map<string, RateLimitEntry> = new Map();
-  private logger: Logger;
-  private cleanupTimer?: NodeJS.Timeout;
-  private disposed: boolean = false;
-
-  constructor(config: RateLimitConfig) {
-    this.config = {
-      skipSuccessfulRequests: false,
-      burstMultiplier: 1.5,
-      ...config
-    };
-    // 计算突发容量
-    this.burstCapacity = Math.floor(this.config.maxRequests * this.config.burstMultiplier);
-    this.logger = new Logger({ component: 'RateLimiter' });
-    // 自动启动清理定时器
-    this.cleanupTimer = setInterval(() => this.cleanup(), config.windowMs);
-    
-    // 注册析构回调，确保即使 stop() 未调用也能清理资源
-    if (typeof Symbol.dispose !== 'undefined') {
-      // 支持 using 语法的自动清理
-    }
-  }
-
-  /**
-   * 实现 Disposable 接口
-   * 确保资源被正确释放
-   */
-  [Symbol.dispose](): void {
-    this.stop();
-  }
-
-  /**
-   * 检查是否已释放
-   */
-  isDisposed(): boolean {
-    return this.disposed;
-  }
-
-  /**
-   * 停止速率限制器，清理资源
-   * 幂等操作，可多次调用
-   */
-  stop(): void {
-    if (this.disposed) {
-      return; // 幂等：已释放则跳过
-    }
-    
-    this.disposed = true;
-    
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = undefined;
-    }
-    this.store.clear();
-    this.logger.info('Rate limiter stopped');
-  }
-
-  /**
-   * 检查是否允许请求
-   * @param key 标识符（如 IP 地址、Peer ID）
-   * @returns 是否允许请求
-   */
-  allowRequest(key: string): boolean {
-    const now = Date.now();
-    const entry = this.store.get(key);
-
-    if (!entry) {
-      // 首次请求，初始化令牌桶
-      // 初始令牌数为 maxRequests - 1（本次请求消耗 1 个）
-      this.store.set(key, {
-        tokens: this.config.maxRequests - 1,
-        lastRefill: now
-      });
-      return true;
-    }
-
-    // 计算需要补充的令牌数
-    const timePassed = now - entry.lastRefill;
-    const tokensToAdd = Math.floor(
-      (timePassed / this.config.windowMs) * this.config.maxRequests
-    );
-
-    if (tokensToAdd > 0) {
-      // 令牌补充后不能超过突发容量
-      entry.tokens = Math.min(
-        this.burstCapacity,
-        entry.tokens + tokensToAdd
-      );
-      entry.lastRefill = now;
-    }
-
-    // 检查是否有可用令牌
-    if (entry.tokens > 0) {
-      entry.tokens--;
-      return true;
-    }
-
-    this.logger.warn('Rate limit exceeded', { 
-      key, 
-      remaining: entry.tokens,
-      maxRequests: this.config.maxRequests,
-      burstCapacity: this.burstCapacity
-    });
-    return false;
-  }
-
-  /**
-   * 获取剩余令牌数
-   */
-  getRemainingTokens(key: string): number {
-    const entry = this.store.get(key);
-    if (!entry) return this.config.maxRequests;
-
-    const now = Date.now();
-    const timePassed = now - entry.lastRefill;
-    const tokensToAdd = Math.floor(
-      (timePassed / this.config.windowMs) * this.config.maxRequests
-    );
-
-    return Math.min(this.burstCapacity, entry.tokens + tokensToAdd);
-  }
-
-  /**
-   * 重置限制
-   */
-  reset(key?: string): void {
-    if (key) {
-      this.store.delete(key);
-    } else {
-      this.store.clear();
-    }
-  }
-
-  /**
-   * 清理过期的条目
-   */
-  cleanup(): void {
-    const now = Date.now();
-    const maxAge = this.config.windowMs * 2;
-
-    for (const [key, entry] of this.store) {
-      if (now - entry.lastRefill > maxAge) {
-        this.store.delete(key);
-      }
-    }
-  }
-}
-
-/**
- * 创建速率限制中间件（用于 HTTP 服务器）
- */
-export function createRateLimitMiddleware(config: RateLimitConfig) {
-  const limiter = new RateLimiter(config);
-
-  const middleware = (req: any, res: any, next: () => void) => {
-    const key = req.socket?.remoteAddress || 'unknown';
-
-    if (!limiter.allowRequest(key)) {
-      res.writeHead(429, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        success: false,
-        error: 'Too many requests',
-        code: 'RATE_LIMIT_EXCEEDED'
-      }));
-      return;
-    }
-
-    next();
-  };
-
-  // 提供 stop 方法清理资源
-  middleware.stop = () => {
-    limiter.stop();
-  };
-
-  return middleware;
-}

package/src/utils/signature.ts

@@ -1,136 +0,0 @@
-/**
- * 请求签名验证工具
- * 使用 HMAC-SHA256 验证消息来源真实性
- */
-
-import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
-import { Logger } from './logger.js';
-
-export interface SignatureConfig {
-  /** 签名密钥 */
-  secretKey: string;
-  /** 时间戳容忍度（毫秒，默认 5 分钟） */
-  timestampTolerance?: number;
-}
-
-export interface SignedMessage {
-  /** 消息体 */
-  payload: string;
-  /** 时间戳 */
-  timestamp: number;
-  /** 签名 */
-  signature: string;
-  /** 随机 nonce */
-  nonce: string;
-}
-
-/**
- * 请求签名验证器
- */
-export class RequestSigner {
-  private secretKey: string;
-  private timestampTolerance: number;
-  private logger: Logger;
-
-  constructor(config: SignatureConfig) {
-    this.secretKey = config.secretKey;
-    this.timestampTolerance = config.timestampTolerance || 5 * 60 * 1000; // 5 分钟
-    this.logger = new Logger({ component: 'RequestSigner' });
-  }
-
-  /**
-   * 生成签名
-   * @param payload - 消息体（JSON 字符串）
-   * @returns 签名后的消息
-   */
-  sign(payload: string): SignedMessage {
-    const timestamp = Date.now();
-    const nonce = randomBytes(16).toString('hex');
-    const signature = this.generateSignature(payload, timestamp, nonce);
-
-    return {
-      payload,
-      timestamp,
-      signature,
-      nonce
-    };
-  }
-
-  /**
-   * 验证签名
-   * @param message - 签名后的消息
-   * @returns 验证结果
-   */
-  verify(message: SignedMessage): { valid: boolean; error?: string } {
-    // 1. 检查时间戳
-    const now = Date.now();
-    const timeDiff = Math.abs(now - message.timestamp);
-    if (timeDiff > this.timestampTolerance) {
-      this.logger.warn('Signature timestamp expired', {
-        timestamp: message.timestamp,
-        diff: timeDiff
-      });
-      return { valid: false, error: 'Timestamp expired' };
-    }
-
-    // 2. 验证签名
-    const expectedSignature = this.generateSignature(
-      message.payload,
-      message.timestamp,
-      message.nonce
-    );
-
-    if (!this.constantTimeCompare(message.signature, expectedSignature)) {
-      this.logger.warn('Invalid signature');
-      return { valid: false, error: 'Invalid signature' };
-    }
-
-    return { valid: true };
-  }
-
-  /**
-   * 生成 HMAC-SHA256 签名
-   */
-  private generateSignature(payload: string, timestamp: number, nonce: string): string {
-    const data = `${payload}:${timestamp}:${nonce}`;
-    return createHmac('sha256', this.secretKey).update(data).digest('hex');
-  }
-
-  /**
-   * 常量时间比较（防止时序攻击）
-   */
-  private constantTimeCompare(a: string, b: string): boolean {
-    if (a.length !== b.length) return false;
-    const bufA = Buffer.from(a);
-    const bufB = Buffer.from(b);
-    return timingSafeEqual(bufA, bufB);
-  }
-}
-
-/**
- * 从环境变量加载签名密钥
- */
-export function loadSignatureConfig(): SignatureConfig | null {
-  const secretKey = process.env.F2A_SIGNATURE_KEY;
-  if (!secretKey) {
-    // 生产环境强制警告，开发环境仅提示
-    const isProduction = process.env.NODE_ENV === 'production';
-    const logger = new Logger({ component: 'SignatureConfig' });
-    
-    if (isProduction) {
-      logger.error('F2A_SIGNATURE_KEY is not set! Signature verification is DISABLED. This is a security risk in production.');
-    } else {
-      logger.warn('F2A_SIGNATURE_KEY is not set. Signature verification is disabled. Set this environment variable for secure message verification.');
-    }
-    return null;
-  }
-
-  const tolerance = process.env.F2A_SIGNATURE_TOLERANCE
-    ? parseInt(process.env.F2A_SIGNATURE_TOLERANCE, 10)
-    : undefined;
-
-  return {
-    secretKey,
-    timestampTolerance: tolerance
-  };
-}