@f2a/network 0.1.2 → 0.2.0

package/docs/security-design.md

@@ -1,247 +0,0 @@
-# F2A 安全设计文档
-
-**版本**: 0.3.1  
-**更新日期**: 2026-03-02  
-**状态**: 已实现
-
----
-
-## 概述
-
-F2A 采用多层安全机制，确保 Agent 间通信的机密性、完整性和身份真实性。
-
-## 安全架构
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      应用层 (Application)                    │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
-│  │ Messaging│  │  Skills  │  │  Files   │  │  Groups  │   │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
-├───────┼─────────────┼─────────────┼─────────────┼──────────┤
-│       │             │             │             │          │
-│  ┌────┴─────────────┴─────────────┴─────────────┴─────┐    │
-│  │              加密层 (E2E Encryption)                │    │
-│  │         X25519 密钥交换 + AES-256-GCM              │    │
-│  └────┬───────────────────────────────────────────────┘    │
-├───────┼────────────────────────────────────────────────────┤
-│       │                                                    │
-│  ┌────┴───────────────────────────────────────────────┐    │
-│  │              身份层 (Identity)                      │    │
-│  │         Ed25519 签名 + Agent ID 绑定               │    │
-│  └────┬───────────────────────────────────────────────┘    │
-├───────┼────────────────────────────────────────────────────┤
-│       │                                                    │
-│  ┌────┴───────────────────────────────────────────────┐    │
-│  │              传输层 (Transport)                     │    │
-│  │         TCP 直连 / WebRTC / UDP 发现               │    │
-│  └────────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 1. 身份验证 (Identity)
-
-### 1.1 Agent ID 与密钥绑定
-
-- Agent ID 由 Ed25519 公钥派生（格式：`f2a-xxxx-xxxx`）
-- 身份持久化保存在 `~/.f2a/identity.json`
-- 首次启动自动生成密钥对
-
-```javascript
-// 身份文件结构
-{
-  "agentId": "f2a-78c8-c55b",
-  "displayName": "CatPuru",
-  "publicKey": "-----BEGIN PUBLIC KEY-----...",
-  "privateKey": "-----BEGIN PRIVATE KEY-----...",
-  "createdAt": "2026-03-01T10:00:00.000Z"
-}
-```
-
-### 1.2 连接时的身份验证
-
-```javascript
-// 挑战-响应协议
-{
-  "type": "identity_challenge",
-  "agentId": "f2a-xxx",
-  "publicKey": "...",
-  "challenge": "随机数",
-  "timestamp": 1709000000000
-}
-
-// 签名响应
-{
-  "type": "identity_response",
-  "agentId": "f2a-xxx",
-  "signature": "Ed25519签名(challenge + timestamp)"
-}
-```
-
----
-
-## 2. 端到端加密 (E2E Encryption)
-
-### 2.1 密钥交换
-
-- 使用 X25519 进行 ECDH 密钥交换
-- 每次会话生成新的会话密钥
-- 前向保密（Forward Secrecy）
-
-### 2.2 消息加密
-
-- 算法：AES-256-GCM
-- 每个消息包含：
-  - 随机 IV (12 bytes)
-  - 认证标签 (16 bytes)
-  - 密文
-
-```javascript
-// 加密消息格式
-{
-  "type": "encrypted",
-  "iv": "base64(12字节随机数)",
-  "ciphertext": "base64(密文)",
-  "tag": "base64(16字节认证标签)"
-}
-```
-
----
-
-## 3. 安全等级配置
-
-```javascript
-const f2a = await F2A.create({
-  security: {
-    // low: 仅加密，信任局域网
-    // medium: 加密 + 白名单（默认）
-    // high: 加密 + 手动确认 + 签名验证
-    level: 'medium',
-    
-    // 白名单（medium/high 有效）
-    whitelist: ['f2a-agent-a', 'f2a-agent-b'],
-    
-    // 黑名单
-    blacklist: ['f2a-malicious'],
-    
-    // 是否需要手动确认（high 强制 true）
-    requireConfirmation: true,
-    
-    // 是否验证签名
-    verifySignatures: true,
-    
-    // 速率限制
-    rateLimit: {
-      maxRequests: 10,
-      windowMs: 60000  // 1分钟
-    }
-  }
-});
-```
-
----
-
-## 4. 防护措施
-
-### 4.1 防重放攻击
-
-- 每个消息包含唯一 ID (UUID)
-- 时间戳有效期：5 分钟
-- 已处理消息 ID 缓存（最大 5000 条，LRU 清理）
-
-```javascript
-// 消息格式
-{
-  "type": "message",
-  "id": "msg-uuid",
-  "timestamp": 1709000000000,
-  "content": "..."
-}
-```
-
-### 4.2 速率限制
-
-- 默认：10 请求/分钟
-- 超过限制自动断开连接
-- 定期清理过期记录
-
-### 4.3 消息大小限制
-
-- 最大消息大小：1MB
-- 超过限制的消息直接丢弃
-
-### 4.4 输入验证
-
-- 所有输入参数类型检查
-- 路径遍历防护（文件传输）
-- JSON 结构验证
-
----
-
-## 5. 威胁防护对照表
-
-| 威胁 | 防护措施 | 实现状态 |
-|------|----------|----------|
-| 窃听 | AES-256-GCM 加密 | ✅ 已实现 |
-| 身份伪造 | Ed25519 签名验证 | ✅ 已实现 |
-| 中间人攻击 | ECDH 密钥交换 | ✅ 已实现 |
-| 重放攻击 | 消息 ID + 时间戳 | ✅ 已实现 |
-| DoS 攻击 | 速率限制 + 消息大小限制 | ✅ 已实现 |
-| 恶意连接 | 白名单 + 黑名单 | ✅ 已实现 |
-| 未授权访问 | 手动确认机制 | ✅ 已实现 |
-
----
-
-## 6. 安全最佳实践
-
-### 6.1 生产环境建议
-
-```javascript
-const f2a = await F2A.create({
-  security: {
-    level: 'high',
-    requireConfirmation: true,
-    verifySignatures: true,
-    whitelist: [],  // 只接受已配对 Agent
-    rateLimit: {
-      maxRequests: 10,
-      windowMs: 60000
-    }
-  }
-});
-```
-
-### 6.2 敏感操作确认
-
-- 首次连接需要手动确认
-- 文件传输需要接收方确认
-- 技能调用可以配置为需要确认
-
-### 6.3 日志审计
-
-- 所有连接/断开事件记录
-- 消息发送/接收记录（DEBUG 级别）
-- 安全事件记录（WARN/ERROR 级别）
-
----
-
-## 7. 已知限制
-
-1. **UDP 发现广播**：发现消息未加密（仅包含公开信息）
-2. **WebRTC 依赖**：需要 STUN/TURN 服务器（可配置）
-3. **密钥存储**：私钥以明文存储在文件系统（依赖 OS 权限保护）
-
----
-
-## 8. 更新记录
-
-| 日期 | 版本 | 变更 |
-|------|------|------|
-| 2026-03-02 | 0.3.1 | 更新文档，添加已实现功能说明 |
-| 2026-02-28 | 0.3.0 | 初始安全设计文档 |
-
----
-
-*文档维护：F2A Team*

package/install.sh

@@ -1,231 +0,0 @@
-#!/bin/bash
-#
-# F2A 一键安装脚本 (纯 P2P 版本)
-# 
-# 使用方法:
-#   curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash
-#   
-# 或指定安装目录:
-#   curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash -s -- --dir /path/to/install
-
-set -e
-
-# 颜色输出
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# 默认配置
-INSTALL_DIR="${HOME}/.openclaw/workspace/skills/f2a-network"
-REPO_URL="https://github.com/LuciusCao/F2A"
-P2P_PORT="9000"
-
-# 解析参数
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --dir)
-      INSTALL_DIR="$2"
-      shift 2
-      ;;
-    --port)
-      P2P_PORT="$2"
-      shift 2
-      ;;
-    --help)
-      echo "F2A 纯 P2P Agent 网络安装脚本"
-      echo ""
-      echo "用法:"
-      echo "  curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash"
-      echo ""
-      echo "选项:"
-      echo "  --dir PATH      指定安装目录 (默认: ~/.openclaw/workspace/skills/f2a-network)"
-      echo "  --port PORT     指定 P2P 端口 (默认: 9000)"
-      echo "  --help          显示帮助"
-      echo ""
-      echo "示例:"
-      echo "  # 默认安装"
-      echo "  curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash"
-      echo ""
-      echo "  # 指定端口"
-      echo "  curl -fsSL https://raw.githubusercontent.com/LuciusCao/F2A/main/install.sh | bash -s -- --port 9001"
-      exit 0
-      ;;
-    *)
-      echo "未知选项: $1"
-      echo "使用 --help 查看帮助"
-      exit 1
-      ;;
-  esac
-done
-
-echo -e "${BLUE}🚀 F2A 纯 P2P Agent 网络安装程序${NC}"
-echo -e "${BLUE}   无需服务器，局域网直连${NC}"
-echo ""
-
-# 检查 Node.js
-echo -e "${BLUE}📋 检查环境...${NC}"
-if ! command -v node &> /dev/null; then
-  echo -e "${RED}❌ Node.js 未安装${NC}"
-  echo ""
-  echo "请先安装 Node.js 18+:"
-  echo "  https://nodejs.org/"
-  echo ""
-  echo "或使用包管理器:"
-  echo "  macOS:    brew install node"
-  echo "  Ubuntu:   sudo apt install nodejs npm"
-  echo "  CentOS:   sudo yum install nodejs npm"
-  exit 1
-fi
-
-NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
-if [ "$NODE_VERSION" -lt 18 ]; then
-  echo -e "${RED}❌ Node.js 版本过低: $(node --version)${NC}"
-  echo "需要 Node.js 18+"
-  exit 1
-fi
-
-echo -e "${GREEN}✅ Node.js $(node --version)${NC}"
-
-# 检查 npm
-if ! command -v npm &> /dev/null; then
-  echo -e "${RED}❌ npm 未安装${NC}"
-  exit 1
-fi
-
-echo -e "${GREEN}✅ npm $(npm --version)${NC}"
-echo ""
-
-# 检查 git
-if ! command -v git &> /dev/null; then
-  echo -e "${YELLOW}⚠️  git 未安装，将使用 curl 下载${NC}"
-  USE_GIT=false
-else
-  echo -e "${GREEN}✅ git $(git --version | cut -d' ' -f3)${NC}"
-  USE_GIT=true
-fi
-echo ""
-
-# 创建安装目录
-echo -e "${BLUE}📁 创建安装目录...${NC}"
-if [ -d "${INSTALL_DIR}" ]; then
-  echo -e "${YELLOW}⚠️  目录已存在，将覆盖安装${NC}"
-  rm -rf "${INSTALL_DIR}"
-fi
-
-mkdir -p "${INSTALL_DIR}"
-cd "${INSTALL_DIR}"
-echo -e "${GREEN}✅ 目录: ${INSTALL_DIR}${NC}"
-echo ""
-
-# 下载 F2A
-echo -e "${BLUE}⬇️  下载 F2A...${NC}"
-
-if [ "$USE_GIT" = true ]; then
-  # 使用 git clone
-  git clone --depth 1 "${REPO_URL}.git" temp_clone 2>/dev/null || {
-    echo -e "${YELLOW}⚠️  git clone 失败，尝试使用 curl...${NC}"
-    USE_GIT=false
-  }
-  
-  if [ "$USE_GIT" = true ]; then
-    cp -r temp_clone/skill/* .
-    rm -rf temp_clone
-    echo -e "${GREEN}✅ 通过 git 下载成功${NC}"
-  fi
-fi
-
-if [ "$USE_GIT" = false ]; then
-  # 使用 curl 下载
-  echo -e "${BLUE}📦 使用 curl 下载...${NC}"
-  
-  # 下载最新 release
-  LATEST_URL="${REPO_URL}/archive/refs/heads/main.tar.gz"
-  
-  if curl -fsSL -o f2a.tar.gz "${LATEST_URL}"; then
-    tar -xzf f2a.tar.gz --strip-components=2 "F2A-main/skill"
-    rm -f f2a.tar.gz
-    echo -e "${GREEN}✅ 通过 curl 下载成功${NC}"
-  else
-    echo -e "${RED}❌ 下载失败${NC}"
-    echo ""
-    echo "可能原因:"
-    echo "  1. 无法连接到 GitHub"
-    echo "  2. 网络不稳定"
-    echo ""
-    echo "解决方法:"
-    echo "  1. 检查网络连接"
-    echo "  2. 手动下载: git clone ${REPO_URL}"
-    exit 1
-  fi
-fi
-
-echo ""
-
-# 安装依赖
-echo -e "${BLUE}📚 安装依赖...${NC}"
-npm install --production
-echo -e "${GREEN}✅ 依赖安装完成${NC}"
-echo ""
-
-# 创建配置文件
-mkdir -p "${INSTALL_DIR}/memory/f2a"
-cat > "${INSTALL_DIR}/memory/f2a/config.json" << EOF
-{
-  "p2pPort": ${P2P_PORT},
-  "security": {
-    "level": "medium",
-    "requireConfirmation": true
-  }
-}
-EOF
-
-# 创建启动脚本
-cat > "${INSTALL_DIR}/start.sh" << EOF
-#!/bin/bash
-cd "$(dirname "$0")"
-echo "🚀 启动 F2A 纯 P2P 网络..."
-echo "   端口: ${P2P_PORT}"
-echo ""
-node examples/serverless-example.js
-EOF
-chmod +x "${INSTALL_DIR}/start.sh"
-
-# 创建快速启动命令
-if [ -d "${HOME}/.local/bin" ]; then
-  cat > "${HOME}/.local/bin/f2a" << EOF
-#!/bin/bash
-cd "${INSTALL_DIR}"
-./start.sh
-EOF
-  chmod +x "${HOME}/.local/bin/f2a"
-  echo -e "${GREEN}✅ 已创建快捷命令: f2a${NC}"
-fi
-
-echo -e "${GREEN}🎉 F2A 安装完成！${NC}"
-echo ""
-echo "═══════════════════════════════════════"
-echo ""
-echo "📂 安装目录: ${INSTALL_DIR}"
-echo "🔌 P2P 端口: ${P2P_PORT}"
-echo ""
-echo "🚀 启动方式:"
-echo "  cd ${INSTALL_DIR}"
-echo "  ./start.sh"
-echo ""
-echo "或直接使用:"
-echo "  f2a"
-echo ""
-echo "📖 使用方法:"
-echo "  1. 启动后自动发现局域网内的其他 Agent"
-echo "  2. 新连接需要手动确认"
-echo "  3. 使用命令行交互发送消息"
-echo ""
-echo "🔐 安全特性:"
-echo "  - 端到端加密 (ECDH + AES-256-GCM)"
-echo "  - Ed25519 身份签名验证"
-echo "  - 白名单/黑名单机制"
-echo "  - 速率限制防 DoS"
-echo ""
-echo "═══════════════════════════════════════"