# 安全说明

Linco Bridge connector 运行在用户本机，负责连接远端 IM 和本地 Agent。安全边界的核心原则是：凭证留在本机，`/get` 文件读取遵循连接器进程的操作系统权限，危险操作需要明确策略。

## 本机凭证

配置默认保存在用户目录下的 `.rontian-connect/config.json`。不要公开该文件，不要提交真实 `appId`、`appSecret`、`LINCO_TOKEN` 或带 token 的本地测试页 URL。

本地测试页 URL 带访问 token，只用于开发和自测。不要转发给不可信用户。首次带 token 访问成功后，连接器会在浏览器中保存仅限本机测试页使用的访问 cookie，便于刷新页面或重新打开同源页面；清理浏览器站点数据后需要重新使用 `rontian-connect start` 输出的完整地址打开。

## 远端 WebSocket

远端桥接默认要求 `wss://`。仅在本地调试时使用 `ws://`，并显式配置 `allowInsecureWs`。

日志中展示远端地址时应隐藏密钥参数。新增日志时不要打印 `appSecret`、`token`、完整认证 URL 或附件 base64。

## 审批模式

| 模式 | 行为 |
| --- | --- |
| `manual` | 权限请求和危险操作由用户手动确认。 |
| `auto` | 自动确认权限请求和危险操作，但保留默认权限边界。 |
| `yolo` | 尝试使用 Agent 原生跳过权限/沙箱模式。仅适合可信环境。 |

如果用户切换到 `yolo`，Claude/Codex 进程可能会重启，以便使用新的原生权限参数恢复同一会话。

## 附件和文件读取

入站附件会保存到本机。默认限制包括单次附件数量、单文件大小和总大小，高风险可执行/脚本扩展名默认拦截。

`/get <路径>` 可以返回连接器 Node.js 进程有权读取的任意本机普通文件。相对路径仍按当前会话目录语义解析，绝对路径不受工作区或项目范围限制；软链接会解析到真实目标后读取。

`/get` 不拦截隐藏文件、空文件、危险扩展名或超过 `maxOutgoingAttachmentBytes` 的文件。操作系统文件权限、WebSocket 负载上限和远端传输上限仍然有效。由于有效会话可以读取 `.env`、`.git/config`、`.ssh/*` 等敏感内容，只应在可信机器和可信账号环境中启用连接器。

Agent 回复中的文件引用应是 Markdown 链接，目标为绝对路径。远端 IM 点击引用后再通过 `/get` 按需拉取文件。

## 内部元数据

`_lincoMeta`、`type: "meta"` 等字段只用于桥接层路由。它们不应展示给用户，不应写入 Agent prompt，也不应被远端前端拼进用户正文。

## 自更新

`/update` 会安装 npm 上的指定版本并重启后台服务。源码 checkout 默认不允许自更新，除非显式设置允许开关。新增更新逻辑时应继续避免 shell 拼接未校验版本号。

## 贡献者注意

新增功能时请优先添加以下测试：

| 场景 | 建议测试 |
| --- | --- |
| 新消息类型 | 协议转换和 `turn_end` 收尾。 |
| 新斜杠命令 | `slash_command_result` 结构、错误分支和 busy 状态。 |
| 文件处理 | 入站附件的危险扩展名和大小限制；`/get` 的普通文件、不可读文件及最终读取失败。 |
| 凭证处理 | 日志 redaction 和 URL redaction。 |
| 权限操作 | manual/auto/yolo 三种模式下的行为。 |