Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

14.0 KB
Raw Blame

title: 安全模型 description: Adelie 的访问机制如何运作:从认领新服务器到收回会话,以及底层的实现细节。

Adelie 用真实凭据在真实机器上运行 Agent,所以值得弄清楚:谁能做什么,凭什么。本页按你遇到这些场景的顺序依次讲解,最后集中说明底层机制(会话令牌、磁盘内容、网络暴露面)。

所有场景都贯穿着同一条原则:

能读到数据根目录,就等于拥有它。 数据根目录(默认为 ~/.adelie/data)存放着全部模型凭据和全部对话。在它们旁边再藏一个秘密,也拦不住本来就能读到这些内容的人,所以这套安全模型从不假装做得到。它做的反而是让这种所有权可以放心使用:有效期短、随时可收回,而且从不要求存储或发送密码。

功能一览

能力 位置
通过启动时打印的登录链接认领新服务器;此时还不存在密码,也不会显示任何密码 启动提示
用密码登录;密码以 scrypt 哈希存储,登录尝试有频率限制 Web 登录页、penguin auth login
桌面应用静默登录自己的窗口 窗口打开时的一次性令牌
凭本地所有权铸造会话,全程不需要密码 penguin auth token
通过 ssh 管理机器,网络上不传密码 机器管理页面
会话是服务端的一行记录:可逐个收回、重启后依然存在、使用期间自动续期(30 天) 所有场景
每个会话都记录自己的建立方式 会话的 via 值(见下文)
收回单个会话,或收回某个用户的全部会话 登出、管理员重置用户密码
就在这台机器上找回丢失的管理员密码 penguin server reset-admin-password

每个会话的 via 值记录它的建立方式:

  • password:手动输入的密码,或由 penguin auth token 铸造的会话
  • desktop:桌面应用自己的窗口
  • setup:新服务器上的登录链接
  • token:请求在 Bearer 头里携带本地 API token;不存储会话

认领新服务器

全新的服务器没有可用的密码:预置值生成后完成哈希便立即丢弃,没人见过明文。为了让你照样能进去,在设置密码之前,服务器每次启动都会打印一个登录链接:

+---------------------------------------------------------------------------------------+
|   This server has no admin password yet. Open this link to claim it:                  |
|                                                                                       |
|     http://localhost:7364/api/auth/claim?token=...                                    |
|                                                                                       |
|   The link lasts 30 days or until a password is set; restarting prints a fresh one.   |
+---------------------------------------------------------------------------------------+
  1. 启动服务器。
  2. 从启动输出中复制登录链接。
  3. 在浏览器中打开链接,即以内置的 admin 账户身份登录。
  4. 设置密码。

为什么可以放心打印链接

这个链接不是一次性的,因为邮件客户端可能抢在你之前抓取它,第二次打开也必须仍然有效。真正让它能放心打印到控制台的,是另外三条限制:

  • 它只在服务器尚未认领时有效,且最长 30 天。一旦设置了密码,服务器就拒绝这个链接,所以翻控制台的历史输出也进不去。
  • 链接比对用的值存在内存里,每次重启都会更换。上一次运行打印的链接不再有效;错过了提示,重启服务器就能看到新的。
  • 错误的 token 和已认领的服务器得到同一个答复,所以过期的链接连是哪种情况都区分不出来。

[!NOTE] 在容器里,这条提示输出到容器日志(docker logs)。链接中的 localhost 是服务器眼中的自己。按文档给出的回环端口映射来部署时,这也是你眼中的它,所以在运行 Docker 的那台机器上按打印的原样打开链接即可。如果容器发布到了网络上,就把 localhost 换成你实际访问所用的主机;无论哪种情况,token 都保持原样。

也可以改用 ADELIE_SEED_ADMIN_PASSWORD 直接固定密码,但只在数据根目录为空的首次启动时生效。

链接授予的会话带有 via: setup。它只有一项特殊许可:设置密码时不必输入旧密码(反正也不存在);除此之外没有任何特权,尤其拿不到任何仅限桌面应用的路由。

从桌面应用登录

桌面应用的外壳拥有它内嵌的服务器进程,仅凭这一点,窗口即可进入。窗口的首次导航会兑换外壳铸造的一次性令牌,随后以 via: desktop 登录。令牌一经兑换即作废,URL 泄露也无法重放。

管理密码

密码至少 8 个字符,存储方式只有一种:scrypt 哈希(N=16384,每个密码各带一个盐值,参数与哈希存放在一起,以便日后提高计算成本)。按操作者不同,设置密码有四种方式。

修改自己的密码

如果你知道当前密码,在用户设置里使用修改密码(见修改密码)。操作会先验证当前密码。

不提供旧密码设置密码

setup 会话(见认领新服务器)和桌面应用自己的窗口都可以在不出示旧密码的情况下设置新密码。这两种会话所在的账户,密码本来就是无人见过的随机值,没有旧密码可填。会话的建立方式本身就是授权。

重置其他用户的密码

管理员在用户管理里用重置密码为其他账户设置一个新的初始密码(见重置用户密码)。用户下次登录时要先修改这个密码,名下所有会话同时收回。见收回访问权限。

找回管理员密码

开始之前

  • 能访问服务器所在的机器,且服务器已停止。本地文件系统的访问权就是授权。
  1. 运行 penguin server reset-admin-password。
  2. 启动服务器,它会打印一个新的登录链接。
  3. 打开链接并设置密码,方法同认领新服务器。

管理员账户回到未认领状态,名下所有会话全部收回。整个恢复过程不产生任何需要记下来的东西。

登录尝试限制

无论来自哪里,密码登录都按用户名限速,采用指数退避。失败五次后,每次新的尝试要先等 1 秒,逐次翻倍,最长 60 秒。不存在的用户名也按同样方式限速,因此限流本身不会暴露账户是否存在。响应耗时同样不会:不存在的用户名会拿一个占位哈希来校验,因此每次尝试都恰好做一次 scrypt 推导。

在本机自动化

脚本和 CLI 从来不需要密码,因为本地所有权本来就高于密码。

CLI 命令访问本机上的服务器时,用本地 API token 认证;服务器每次启动都会把它写入 <root>/api-token。参见 CLI 参考。

本地 API token 不能改变 Agent 的对外暴露:开启 Agent 的 API、无密钥访问、审批模式、密钥,以及整台服务器的 Agent API 开关,都需要人的登录,因为每个 Agent 的命令都带着这个 token。服务器以 403 human_required 拒绝携带 token 的这类请求,在 Session 之外,CLI 随即带着你保存的登录(如果有)把请求再发一次;下文的 penguin auth token 能为 CLI 提供这样的登录。这防止 Agent 借 harness 交给它的凭据自行对外开放,但不是边界:以数据根目录所属操作系统账号运行的进程同样能铸造会话。约束 Agent 的是沙盒。

脚本需要自己的会话时,就自己铸造一个。会话是数据根目录下 web.db 里的一行记录,所以 CLI 直接写入一行:

penguin auth token          # no password, no prompt: inserts a session row

能读写数据根目录就是全部授权,而且它不会授予任何新东西:数据根目录本来就存着这个 token 能触达的每一份凭据。服务器在不在运行都可以铸造,与运行中的服务器并存也安全。前提是服务器至少在这个根目录上启动过一次:铸造所用的账户就存放在这个根目录的 web.db 里。

铸造出的 token 默认有效期一小时,等同普通的密码会话,绝不是桌面会话。用 --ttl-seconds 指定其他有效期(最长 30 天),或用 --user-id 为 admin 以外的账户铸造。

在多用户机器上,这道限定正是关键。数据根目录属于运行服务器的操作系统账户,所以只有这个账户能铸造。其他人一律用密码登录:penguin auth login --server <url>。

通过 ssh 管理远程机器

机器管理页面通过 ssh 管理其他机器,一切操作都以 ssh 账户的身份运行。

要对一台机器的 API 执行操作,控制器通过 ssh 在那台机器上运行 penguin auth token。机器自己的 CLI 往机器自己的数据库里写入一行会话记录。经过网络的只有会话令牌,有效期一小时。

密码永远不经过网络。一台机器的管理员密码就留在那台机器上,因为 ssh 已经证明了密码所能证明的一切。

[!WARNING] 这种信任是双向的。任何能 ssh 到一台机器的人都能亲手读取它的数据根目录,所以铸造 token 并不会带来 ssh 之外的任何权限。正因如此,你的 ssh 密钥就是它能到达的每台机器的主凭据。请按这个级别保管。

把模型凭据同步到自己各台机器的 Project,会把这批 API key 放进每台机器自己的 Project 配置(权限 0600)。运行你的 Agent 的机器,必然持有这些 Agent 运行所用的 key。

收回访问权限

会话是服务器上的一行记录,删掉这一行,会话立刻失效。

收回对象 操作 生效时机
单个会话 penguin auth logout,或在 Web App 里登出 立即:删除对应记录
某个用户的全部会话 管理员重置这个用户的密码 立即:删除这个账户的所有记录
管理员自己的会话 penguin server reset-admin-password(服务器停止时) 下次启动时,同时打印新的首次登录链接
本地 API token 重启服务器 下次启动时,同时写入新 token
模型 API key 先在供应商处轮换,再更新 Project 配置 在供应商处生效

备份泄露时

整套设计围绕最坏情况构建:数据根目录的完整备份泄露。应对办法就是轮换其中的模型 API key,再重启服务器,仅此而已。备份里的密码只是 scrypt 哈希;会话表里也只有每个 token 的 sha256,绝没有 token 本身。

备份里唯一可用的凭据,是做备份那次服务器启动写入的本地 API token,而一次重启就会更换它。此后,从备份里复制出来的任何东西都无法向运行中的服务器出示。

工作原理

会话

每个 cookie 携带一个 32 字节的随机 token。会话就是 auth_sessions 表里以 token 的 sha256 为键的那一行,其中记录着账户、建立方式(via)和过期时间。正因为这一行就是会话本身,删掉它就等于立即收回会话,而重启不会让任何人退出登录。

浏览器会话有效期 30 天。签发或上次续期之后满一天再使用,会话就原地续期 30 天:只更新记录里的过期时间,cookie 值保持不变。因此这 30 天相当于空闲超时:经常使用的会话永不过期,也不会冒出需要追查的第二份副本。只有自身寿命能撑到续期窗口的会话才会顺延,所以铸造的一小时 token 到一小时就到期。

Cookie 设置为 HttpOnly 和 SameSite=Lax。请求确实是 https,或者受信任的代理声明如此(ADELIE_TRUST_PROXY=1)时,还会加上 Secure。默认忽略 x-forwarded-proto 头。

磁盘上存了什么

文件 内容 保留多久
web.db 密码哈希、会话哈希、应用数据 永久
<project>/.project_config.toml 模型 API key,直接内联存放,权限 0600 直到下次编辑
cli-session.json 一个有效的会话令牌,权限 0600 直到登出或过期
api-token 本地 API token,权限 0600:任何请求只要在 Bearer 头里带上它,就拥有管理员权限 直到下次服务器启动

磁盘上从不以可用形式保存会话令牌(只存 sha256)和密码。你选定的密码只以 scrypt 哈希存在;预置的密码生成后立即丢弃。

本地 API token 是有意放在磁盘上的。能读到它就证明能访问数据根目录,而这本身就是管理员权限;每次启动服务器也都会更换它。

模型 API key 是唯一无法进一步降低暴露的秘密:必须原文送达供应商,因此无法哈希。它们只存在 Project 配置里,在所有 API 响应和界面中都显示为掩码,只有在真正发起请求的那一刻才以明文读取。

网络暴露面

服务器默认绑定 127.0.0.1。要对外暴露(HOST=0.0.0.0),那是部署层面的决定,必须放在 TLS 终结之后,并由代理设置 x-forwarded-proto。

API 只在规范的应用主机名下应答,这样用户生成的预览内容与应用的 cookie 就处于不同的浏览器源(origin)。

跨站请求伪造要面对两层相互独立的防线:SameSite=Lax 的 cookie,以及 Content-Type 检查:凡是 HTML 表单能产生的 Content-Type,对应的写请求一律拒绝。