@f2a/network 0.1.2

package/docs/security-design.md

@@ -0,0 +1,247 @@
+# 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

@@ -0,0 +1,231 @@
+#!/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 "═══════════════════════════════════════"

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@f2a/network",
+  "version": "0.1.2",
+  "description": "Friend-to-Agent P2P networking protocol for OpenClaw Agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "f2a": "./dist/cli/index.js"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "build:all": "npm run build && npm run build --workspaces",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:unit": "vitest run --exclude='tests/integration/**'",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "RUN_INTEGRATION_TESTS=true vitest run tests/integration",
+    "test:docker": "docker compose -f tests/docker/docker-compose.test.yml up --abort-on-container-exit",
+    "test:docker:10": "NODE_COUNT=10 docker compose -f tests/docker/docker-compose.test.yml up --scale node=10 --abort-on-container-exit",
+    "test:all": "npm run test:unit && npm run test:docker",
+    "test:ci": "npm run test:unit && npm run test:docker",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "p2p",
+    "libp2p",
+    "agent",
+    "openclaw",
+    "networking"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LuciusCao/F2A.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@chainsafe/libp2p-noise": "^15.1.2",
+    "@libp2p/crypto": "^4.0.0",
+    "@libp2p/interface": "^1.0.0",
+    "@libp2p/kad-dht": "^16.1.4",
+    "@libp2p/peer-id": "^4.0.0",
+    "@libp2p/tcp": "^9.0.0",
+    "@multiformats/multiaddr": "^12.0.0",
+    "@noble/curves": "^2.0.1",
+    "eventemitter3": "^5.0.0",
+    "libp2p": "^1.0.0",
+    "uint8arrays": "^5.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.0.0"
+  }
+}