当前发布分支为 1.30.x，版本源为 shared/util.py 的 VERSION。已有部署升级前先备份并核对迁移说明。安全扫描只覆盖扫描器能识别的已知问题，测试通过不代表不存在未知漏洞。

优先使用仓库维护者已启用的 GitHub 私密漏洞报告功能（Security → Report a vulnerability）；没有可用私密渠道时，先向维护者取得私密联系方法。报告受影响版本、隔离复现、预期/实际结果及最小化脱敏证据。不要公开令牌、私人代码、完整数据库或可复用攻击细节，不要测试不属于你的系统。

CodePier 是远程控制软件，能读写文件、执行程序和接入本机工具。Hub 管理身份、项目范围及持久操作，Agent 在本机再次检查路径、写入和执行能力。安装本身不是对所有项目的无条件授权；浏览器和桌面是独立能力，桌面需要 computer scope 与本机所有者允许的应用。

新安装可明确选择完整 Shell 和目录任务；完整 Shell 使用安装用户的系统文件、网络、密钥代理和其他权限，不是项目目录沙箱。VPS/SSH 执行也可能产生目录外或远端副作用。只需要受限具名任务时不要额外开启 full。升级保留现有能力选择，不能静默扩权。

客户端 read/write/execute/computer、项目映射和本机设置分层判断。OAuth/PAT 的“全部现有及未来新增项目”只有明确选择后才生效；限定项目默认不会自动增加。修改已有项目范围不增加工具 scope、不恢复撤销、不延长有效期。权限在新操作准入及排队投递时复核，而不是只在连接建立时验证。关闭默认授权值不自动收回已有连接的范围。

Native CLI 使用自己的本机账户、权限和工具策略；CodePier 的撤销不能回滚已执行动作，也不能保证杀掉所有外部进程。网页、仓库文件、工具输出和屏幕文字都是不可信输入，不能替代用户授权。发送、支付、删除、分享等实际业务操作应核对对象并取得适当确认。

管理员密码使用 16 字节独立随机盐的 scrypt（N=16384、r=8、p=1）；凭据比较使用恒定时间比较。OAuth 授权码与回调匹配、S256 PKCE、单次消费和有效期共同约束登录。令牌、配对票据及登录 cookie 都按秘密处理，令牌哈希不使持有者成为低权限用户。面板会话和写请求还要求相应 CSRF/同源验证；不允许为解决连接问题关闭验证。

Agent 通道以配对秘密、每连接挑战和 HKDF-SHA256 派生会话密钥，使用 AES-256-GCM、方向/设备附加认证数据和严格序列检查。会话通道加密不保护浏览器到 Hub 的 HTTP、初次票据传递或外部进程自己的流量。公网必须 HTTPS；只信任真实反向代理地址，不能让任意来源伪造转发头。TLS 证书校验不可通过关闭 verify 绕过。

面板对普通文本进行转义，原生消息和截图不是可执行 HTML。静态资源的 SHA 校验用于缓存与内容一致性，不是发布者签名，也不能防御已经控制源服务器的攻击者。公开资源不包含用户凭据；认证页面、API 和错误结果不能缓存为公开长期数据。

原生附件默认采用经审查的精确来源主机；可选命名来源 openai_sediment 必须由所有者明确启用。公网单播 DNS、固定已核验 IP、TLS 与逐跳重定向检查继续适用。file_id 不是可独立验证的来源证明，不能据此信任任意 HTTPS 或整个云存储域名。来源预检只判断策略资格，不证明文件可下载；已有显式限制不会因升级被静默扩大。详见文件导入和统一文件入站。

从 1.22 起，认证分块与原生中转未设置时默认开启，显式 false 保持关闭；命名来源仍需明确启用。复用当前身份和授权，不以 upload_id 代替权限。普通文件不按扩展名放宽路径、凭据保护、大小或磁盘限制；完整摘要核验后无覆盖发布。Hub 队列可持久保存加密分块，Agent 私有暂存保留接收字节，数据库、WAL、暂存与备份都需按机密保护。响应丢失先恢复原回执；发布窗口不确定时保留证据，不能保证撤权能追溯取消已在途的最终原子发布。

普通文件工具限定到授权项目，拒绝危险相对路径、敏感文件、逃逸符号链接和不符合工具契约的请求。写入使用原 SHA/新文件预期、临时文件与替换机制，并保存可核对的回执；这不是跨文件的操作系统级原子事务。并发修改必须重新读取并核对，不覆盖为“重试”。

这些检查不能把拥有本机写权限的其他程序变成不可信隔离租户。硬链接、其他进程的路径竞争、完整 Shell 或外部工具仍属于 OS 用户信任边界。输出大小限制和敏感字段脱敏不能保证所有自定义任务输出都不含秘密。用户应避免在环境、argv、日志、审计摘要或截图中放入凭据。

浏览器扩展绑定受管宿主、独立档案和显式授权站点；不能把项目目录权限误当网站登录权限。桌面工具绑定应用、短时会话和一次性观察编号。 原生阻断与模型/CLI 分离，缺省策略允许仍需已有 computer scope 与本机项目/应用白名单；明确关闭不会被升级覆盖。probe=true 初始化 provider 同样要求 computer scope，只有 probe=false 是不启动 provider 的只读状态。图像/文字按逻辑有效期处理，但不承诺擦除 SQLite 空闲页、WAL、备份、原生工具历史或已经发送给客户端的数据。不要修改操作系统隐私数据库、自动批准系统权限或重新打包第三方私有程序。

客户端收到 pending/queued 只表示持久请求已经存在，不表示成功。Agent journal 和 Hub 回执用同一操作编号防止重复执行；响应丢失先查原 operation_id 或原幂等键。超时、取消传输、掉线和主机重启都可能留下未知结果，不能用新键自动重新发送破坏性动作。

SQLite 事务、worker 取消排空和提交后事件通知保护本服务的一致性，不构成跨主库、Agent journal、原生会话库和第三方服务的分布式事务。不同版本间不兼容的新调用会拒绝；已经投递的操作仍保留恢复入口。原生会话历史与主库备份是不同的数据集。

Hub 加密保存设备秘密、持久请求及 VPS 连接秘密。旧格式是 master.key 的 Fernet，新格式含版本/密钥标识并由 master.keys.json 选择；日志不能输出密钥、明文或完整密文。POSIX 受管密钥/备份采用所有者读写权限；Windows 还需由部署者核对账户和目录 ACL，不能把 chmod 当作 ACL 审计。

备份至少保存主数据库及其匹配的 master.key、master.keys.json；完整灾备还包括独立原生库、Agent 配对配置、journal 和部署配置。丢失匹配密钥不能仅靠数据库恢复。停止相关写入或使用受支持的 SQLite 备份方式，不复制一个仍变化的裸数据库后忽略 WAL。备份本身按机密加密存储并演练恢复，不进入源码包或测试 artifact。

以下是管理员明确安排的离线维护，不是网页自动升级动作。先记录运行用户、解释器、数据目录和启动方式，停止对应 Hub，并确认服务管理器不会自动重启；不要对生产卷直接运行未经验证的源码。

# 在已经停止服务、验证备份且使用正确安装环境后：
python -m hub --data-dir /实际数据目录 rekey
# 同一次轮换中断后，保留记录与所有密钥并恢复：
python -m hub --data-dir /实际数据目录 rekey --resume

工具取得 Hub 实例锁与独立密钥维护锁，校验数据后生成新的轮换编号。在 .rekey/<编号> 保留数据库、旧密钥和进度；先发布可同时读取新旧数据的 keyring，在一个数据库事务中重加密指定列，最后切换兼容密钥和完成标记。中断可按同一编号继续，未核对的备份或进度不能被自动接受。原加密请求的幂等身份和操作编号保留。

轮换完成后，在隔离副本验证解密、设备连接、旧回执查询和必要业务，再按原方式启动服务。旧软件不理解版本化密文时，不能只降级程序而保留新库；回滚必须使用匹配的维护前数据库与密钥，且不能覆盖维护后已产生的新业务数据。工具不自动删除备份。密钥轮换也不能消除已泄露旧密钥对历史备份的解密能力；应另行撤销受影响令牌、设备或外部凭据并按保留政策处理副本。

非特权容器、只读根文件系统和最小系统能力有助于缩小影响，不替代应用授权。运行依赖从包含传递依赖与哈希的锁文件安装，拒绝默默改用未锁定版本；Docker 使用固定多架构镜像摘要。升级不会自动安装所有可选桌面能力或修改个人 CLI 凭据。

CI 只使用隔离合成配置和临时目录，不能放入生产密钥、启动付费模型、修改系统隐私权限或注销实际服务。公开源码包有独立文件白名单、内容清单和相对链接检查；.gitignore 不是保密审计。测试证据归档不等于生产备份，必须先脱敏再决定是否分享。

真实 Windows/Linux 桌面、目标设备服务、实际账号接入、容器数据卷迁移和重启后启动都需独立验收。报告必须区分代码存在、模拟/协议测试、本机测试、远端 CI 和实际部署，不能把历史证据改成当前通过。更多排查见 FAQ，验证入口见 开发文档。