权限与安全模型

CocoCat 的安全架构分为三个层次：权限模式、沙箱、认证。

第一层: PermissionMode

定义于 cococat/core/tools/，每个工具声明所需的最低权限：

class PermissionMode(IntEnum):
    READONLY = 0          # 只读操作: 读取文件、搜索
    WORKSPACE_WRITE = 1   # 工作区写入: 编辑文件
    FULL_ACCESS = 2       # 完全访问: 执行命令、网络

权限等级：READONLY < WORKSPACE_WRITE < FULL_ACCESS

Agent 的 config.toml 中指定其权限：

[[agents]]
id = "alice"
permission_mode = "WORKSPACE_WRITE"

工具执行时，ToolRegistry.execute() 检查：

if tool.required_permission > agent.permission_mode:
    raise PermissionError(f"{tool.name} 需要更高的权限")

第二层: Sandbox

定义于 cococat/core/sandbox/：

PathValidator

校验文件操作路径是否在 workspace 范围内：

• 解析绝对路径
• 检查是否包含 .. 路径穿越
• 验证路径前缀是否在允许列表中
• 防止访问 agents/config.toml 等敏感文件

CommandValidator

过滤危险 shell 命令：

• 禁止 rm -rf /, :(){ :|:& };:, dd if= 等模式
• 禁止管道到 shell 解释器 (| bash, | sh)
• 禁止下载并执行 (curl ... | sh, wget ... -O- | sh)
• 允许列表: ls, cat, grep, python, node 等

EnvironmentSanitizer

传递给子进程的环境变量过滤：

• 移除包含 SECRET, KEY, TOKEN, PASSWORD 的变量
• 白名单保留 PATH, HOME, USER 等基础变量
• agent 运行在最小化环境变量集合中

OutputTruncator

命令输出截断：

• 默认上限 10000 字符
• 超出部分在 tool result 中以 [truncated...] 替代
• 防止 LLM 被超长输出淹没

wrap_with_namespace

Linux namespace 隔离（可选）：

def wrap_with_namespace(command):
    # 使用 unshare 创建新的 PID/IPC/Network namespace
    return ["unshare", "--pid", "--ipc", "--net", "--mount-proc"] + command

• 独立 PID 命名空间（子进程无法看到宿主机进程）
• 独立 IPC 命名空间
• 独立网络命名空间（默认无网络访问）
• --mount-proc 挂载独立 /proc
• 非 Linux 系统自动跳过

第二点五层: 并发安全

FileLock

跨平台文件锁，基于 .lock 文件：

with FileLock("path/to/file.lock", timeout=5.0):
    write_to_file(...)

• 基于 .lock 文件的锁机制
• 支持 acquire() / release() / __enter__ 上下文管理器
• 超时机制防止死锁（默认 5 秒）
• 用于 mailbox、消息总线等并发写场景
• 跨平台兼容（Windows + POSIX）

atomic_write

原子写入防止部分写入导致的数据损坏：

def atomic_write(path, content):
    tmp = path + ".tmp"
    write(tmp, content)
    os.rename(tmp, path)

流程：写临时文件 → os.rename 替换目标文件。rename 在 POSIX 系统上是原子操作，确保写入过程中崩溃不会留下损坏文件。

第三层: Auth (Web API)

定义于 cococat/auth.py：

机制	说明
JWT	登录后签发，有效期 24h，用于用户认证
API Key	用于自动化/外部系统调用，可在 Web 面板生成/吊销
bcrypt	密码加密存储
Bearer	所有 API 请求需 Authorization: Bearer <token>

路由权限

GET    /api/*          → 需要认证
POST   /api/auth/login → 公开(无需认证)
POST   /api/auth/register → 公开(需配置)
WS     /api/ws/*       → WebSocket 需要 token 参数

API Key 管理

• 每个 API Key 可设置作用域: read, write, admin
• API Key 不会过期除非手动吊销
• 创建后只显示一次，需立即保存