1 Fork 0

Files

T

justme 6385c1b9a3 feat: sign in with a passkey (WebAuthn, ES256, discoverable credentials) and manage your passkeys [CI]

2026-10-07 21:57:19 +08:00

35 KiB

Raw Blame History

访问控制与入网信任链

这份文档定义谁能做什么（账户、角色、能力、API key）和谁能让节点入网（passkey 到节点的签名链）。它是 security.md 第 5、6 节的展开：security.md 讲为什么（缺口和威胁），这里讲怎么做。状态：设计已定，未实现（实施顺序见第 12 节）。

一句话：登录和授权分开。登录证明「你是谁」，密码、passkey、OIDC 都可以；改变信任（加节点、吊销、改凭证）只认 passkey 的签名，并且这个签名要一路传到节点，Backend 只搬运，伪造不了。

1. 名词

名词	含义
账户	一个人。有角色、若干登录方式、若干 passkey
角色	`anonymous`、`admin`、`owner`，决定能力的上限
能力（capability）	一项具体权限，如 `fleet.write`。端点声明自己需要哪项能力
会话	登录得到的状态，只带 L1 能力
提权窗口	用 passkey 触控换来的、有时限的信任类能力（类似 sudo）
操作员集合（OpSet）	节点固定的、带版本的 passkey 公钥列表，每个带角色和限制
委托（Grant）	passkey 签名授权一把临时密钥，在范围、时间内代表它签名
API key	一串种子；`enroll` 类的 key 创建时由 passkey 签出一份委托
入网券（Ticket）	委托的密钥签的「允许一个持有 K_code 的节点入网」
属主（controllers）	一个节点绑定的一组 passkey：只有它们能授权这个节点上的 extension（web ssh 等）。管理员没有这份权力，见第 8 节

2. 角色与能力

2.1 能力表

组	能力	说明	信任类
展示	`public.read`	看隐藏线路；站点私有时看展示页
节点	`fleet.read`	看 Agent、Probe、线路、加入代码
	`fleet.write`	改名、标签、可见性、手填地址、线路开关、断开会话
	`fleet.enroll`	生成加入代码（签入网券）；可以吊销自己加的节点	是
	`fleet.revoke`	吊销或删除任意节点	是
任务	`tasks.read` · `tasks.write`	任务模板、覆盖、发起测试
数据	`data.read` · `data.write`	原始块、导出；清理
设置	`settings.read` · `settings.write`	站点设置、保留策略、重启计划
更新	`update.read` · `update.confirm`	看 Backend 更新、确认更新
	`release.publish`	CI 登记发布清单（只此一件事）
令牌	`keys.read` · `keys.manage`	列出、创建、撤销 API key
账户	`accounts.manage`	账户、passkey、操作员集合	是
运维	`audit.read` · `ops.metrics`	审计日志；`/metrics`
集成（预留）	`events.read` · `data.export`	拉取事件流和批量数据，见 5.4
	`webhooks.read` · `webhooks.manage`	外部回调订阅，见 5.4

Backend 更新确认是 L1：更新清单由 CI 的发布密钥签名，seq 防回滚，真正的门是发布密钥，不是确认这一步。
一个能力只在一个地方声明：Capability 常量（MoShiro.Protocol），端点用 .Requires(Capability.X)；Principal.Has(capability) 是唯一的判断入口，会话、API key、委托都走它。
对账测试：所有 /api/admin 端点必须声明能力，没声明测试就失败；OpenAPI 的每个操作带 x-moshiro-capability。

2.2 角色

角色	能力
`anonymous`	只有 `public.read`，且站点公开时才有。不是账户
`admin`	除 `accounts.manage` 外的全部；信任类（`fleet.enroll`、`fleet.revoke`）要提权
`owner`	全部；`accounts.manage` 每次都要当场触控

角色是上限：能力是否可用取决于角色和当前窗口。
不能越权：创建 API key 时勾选的能力必须是创建者当前拥有能力的子集；带信任类能力的 key 创建时要 passkey 签一次。
角色写在操作员集合里，节点自己执行：admin 凭证签的入网券有效；只有 owner 凭证签的操作员集合更新才有效。被攻破的 Backend 给自己造一个 admin 账户也加不进节点。

3. 登录与会话

登录方式	能得到	说明
passkey	L1 会话，并且可以提权	WebAuthn，只支持 ES256，attestation 选 `none`
密码	L1 会话	保留用于首次引导和兜底；PBKDF2
OIDC	L1 会话	账户绑定 `iss + sub`，登录时按它找账户，不自动建账户。放在 passkey 之后做

密码和 OIDC 永远不能提权：节点验证不了 IdP 的断言，也不该让 IdP 或密码进入信任域。
引导：初始管理员用密码登录，注册第一个 passkey；这是唯一一次不需要提权的注册。之后新增 passkey 都要提权，并写进操作员集合（见第 7 节）。
建议每个账户至少注册两个 passkey（手机加硬件密钥）。
离线恢复密钥：创建 owner 时同时生成一把离线的 ECDSA 恢复密钥，作为 type=ecdsa、recovery=true 的 owner 凭证写进操作员集合；私钥打印或放进密码管理器，平时不用。节点强制它只能签操作员集合更新，不能签委托、入网券和吊销表，所以即使被偷走，也加不了节点；它的用处是 passkey 全部丢失时签一版新的操作员集合、重新加 passkey，节点不用重装。

3.1 passkey 登录的实现（已完成）

流程：登录页「使用 Passkey 登录」→ POST /api/admin/auth/passkey/options 取挑战 → 浏览器 navigator.credentials.get（可发现凭证，不用输用户名）→ POST /api/admin/auth/passkey/login 提交断言 → 建立会话（Cookie，或跨域前端用 return_session）。注册：已登录用户在「系统 → 用户 → 我的 Passkey」添加，POST /api/admin/auth/passkeys/options 加 POST /api/admin/auth/passkeys；每个用户最多 10 个。
校验：挑战在内存里，一次有效、5 分钟过期，并且区分注册和登录、绑定用户；rpIdHash、UP 和 UV 标志、clientDataJSON 的 type、challenge、origin、ES256 签名；签名计数器只增不减（两边都是 0 的同步型 passkey 不检查）。登录失败一律 401，不区分原因，和密码登录共用限流。
验证断言的纯函数是 Fleet.Identity.WebAuthnAssertion（只用 BCL，节点以后验证 passkey 签出的委托也用它）；注册里的 CBOR 和 attestation 解析在 Backend（WebAuthnRegistration），attestation 一律当 none，节点不带 CBOR。
依赖方（RP）：MoShiro__WebAuthnRpId（缺省取 PublicUrl 的主机，没有就取请求的主机）和 MoShiro__WebAuthnOrigins（缺省取 PublicUrl 的来源）。**passkey 绑定在这个域名上，改了会让已注册的 passkey 失效。**只有和后端同站的页面能用 passkey 登录，管理端在「添加其他后端」（跨域）时不显示这个入口。
会话记录登录方式（password 或 passkey，sessions.auth_method），只有 passkey 登录的会话以后能提权；API key 不是用户，不能注册 passkey。
测试：SoftwarePasskey 在测试里模拟认证器走完整的注册和登录，覆盖错误的挑战、来源、RP、签名、缺少 UV、挑战重放、计数器回退、只能管理自己的 passkey；管理端用 Chromium 的 WebAuthn 虚拟认证器验证过注册和登录。

4. 提权窗口（信任类能力各管各的）

窗口	覆盖	默认时长	行为
接入	`fleet.enroll`	15 分钟（5–60 可调）	窗口内连续生成代码不再弹 passkey
吊销	`fleet.revoke`	5 分钟	破坏性操作，窗口更短
凭证	`accounts.manage`、创建带信任类能力的 key	无窗口	每次都要当场触控

窗口互不覆盖：开了接入窗口不能吊销节点。
「用到才提权」：页面照常打开，点信任类操作时没有窗口才弹 passkey，通过后接着做原来的动作。
管理端顶部显示生效的窗口和剩余时间，每个窗口有「立即结束」。
接入窗口的实现：一次触控让 passkey 签一份委托（见第 7 节），授权浏览器里生成的不可导出临时密钥 D；窗口内用 D 签入网券，到期自动失效。
默认值待确认（15 分钟、5 分钟）。

5. API key

5.1 类型

类型	创建时要不要 passkey	能力
普通 key	不要	勾选的非信任类能力（只读、运维、CI 发布等），只能是创建者能力的子集
`enroll` key	要，签一次	勾选的非信任类能力 + `fleet.enroll`（可吊销自己加的节点）

现有令牌迁移（破坏性）：read → 全部 *.read；admin → 全部非信任类能力；release → release.publish。迁移后，旧的 admin 令牌不能再生成加入代码，需要换成 enroll key。
每把 key 可设：有效期、可选的 IP 白名单（CIDR，待确认）、enroll 类的数量上限和单券 TTL 上限；预留：资源范围、速率和数据配额（见 5.4）。

5.2 `enroll` key 怎么工作

 创建（浏览器 + passkey 一次触控）
   浏览器生成种子 S，只显示一次（形如 mok_…）
   认证值  = HKDF(S, "auth")   → Backend 只存哈希，用来识别这把 key
   签名密钥 = HKDF(S, "sign")   → 公钥 P 写进委托；私钥只有拿着 S 的人算得出
   passkey 对委托签名：{P, scope=enroll, not_after, max_ticket_ttl, 数量上限, 签发凭证 id}
   Backend 存委托和认证值哈希，不存 S

 使用（和普通令牌一样的 HTTP 调用）
   POST /api/admin/join-tokens   Authorization: Bearer mok_S
   Backend 用请求带来的 S 现算签名密钥，签出入网券和 K_code，返回一行安装命令；用完即忘

数据库被偷走拿不到任何签名密钥。被攻破的 Backend 最多在 key 被使用的那一刻拿到 S，权力受这把 key 的有效期和单券 TTL 限制，key 过期或被撤销就没用了。
数量上限由 Backend 执行，节点强制不了；节点只强制时间（见第 7.3 节）。
CI 和测试：夹具自己生成 key 种子，把公钥写进测试的操作员集合，不需要真 passkey。

5.3 创建界面

名称、有效期、可选 IP 白名单；enroll 类多出「最多加几个节点」「单券有效期」。
能力用分组复选框：全局全选（带半选状态）、组内全选、反选、搜索；预设按钮一键套用：只读、运维、接入、CI 发布、全部；超出创建者能力的项灰色不可选，需要 passkey 的项带标记（⚿），勾选后创建时提示。
创建后只显示一次 key，同时列出它拥有的能力和过期时间。
列表：API key、加入代码、节点、审计日志都支持多选和全选做批量操作（撤销、吊销、删除、筛选）。API key 列表显示能力数、最后使用时间、过期时间。

5.4 预留：外部 webhook 回调与数据拉取

后面要让外部系统能订阅事件、触发回调、拉数据。接口和权限现在先留，实现放后面；全部发生在 Backend 里，节点零开销。

能力（已列入能力表，标预留）：
- events.read：拉取事件流，游标分页（GET /api/admin/events?after=<cursor>），适合外部系统轮询。
- data.export：按线路和时间范围批量拉数据，有限速和配额；data.read 仍然是交互式查询。
- webhooks.read · webhooks.manage：创建、修改、删除外部回调订阅，以及手动触发一次测试回调（POST /api/admin/webhooks/{id}/test）。能力在目录里先存在，旧 key 以后可以直接带上它们，不需要再迁移。
key 上预留的字段：
- resource_filter {agent_ids?, labels?}：限制这把 key 能看到哪些节点、线路；事件和 webhook 同样受它限制。
- rate_limit（每分钟请求数）和 quota（每天拉取的行数或字节数）：超出返回 429 带 Retry-After，计入审计。
webhook 的形状：订阅 {id, url, events[], secret, 创建者(key 或账户), enabled}。事件：节点上线或下线、线路告警阈值、安全事件（节点准入、吊销、key 创建、提权）等。投递是 POST JSON，头带 X-MoShiro-Signature: sha256=<HMAC(secret, 时间戳 ‖ body)>、时间戳和投递 id；至少一次投递、指数退避重试、接收方按投递 id 幂等。
订阅受创建者能力约束：只能订阅创建者自己读得到的事件，不能借 webhook 越权。
SSRF 约束（TODO 里已有）：URL 解析后检查地址，只放行公网地址；不跟随重定向到内网；连接和响应有超时和大小上限；secret 只在创建时显示一次。
这些都属于 L1：改的是 Backend 的集成配置，不改变节点信任；但每次增删订阅和改 URL 都进审计日志。

6. 归属与审计

账户表：id、名字、角色、登录方式、passkey；加入代码记 created_by，节点记 added_by；管理页的 Agent、Probe 详情显示「由 xxx 于 xxx 添加」。
审计日志 (时间, 账户, 凭证 id, 动作, 对象, 详情)：创建或撤销 key、加入代码、吊销、删除、手填地址、确认更新、提权、因能力不足被拒绝的请求。保留 365 天（同事件表）。
可验证的一层：委托里写进签名它的 passkey 凭证 id，入网券和节点绑定带着它，节点在 hello 里报告「由哪个凭证准入」。「谁加的」不只是 Backend 的一面之词。

7. 入网信任链

7.1 文档

 ① 操作员集合 OpSet {version, creds:[{id, type=webauthn|ecdsa, 公钥, 角色, 账户, recovery?, max_ticket_ttl, 作用域}]}
    签名人：owner 的 passkey；创世版本由安装时固定的第一个 owner 公钥自证
 ② 委托 Grant {grant_id, 委托公钥 D 或 P, 作用域, 额度, not_before, not_after, 签发凭证 id}
    签名人：passkey（WebAuthn 断言，challenge = SHA256(Grant)）
 ③ 入网券 Ticket {ticket_id, K_code 公钥, 角色, controllers, issued_at, expires_at, grant_id}
    签名人：委托私钥。生成加入代码时签，用户那时不用在场
 ④ 节点绑定 Binding {node_id, 角色, 节点密钥公钥, 对等面公钥, ticket_id}   （controllers 随 Ticket 一起被签名，节点绑定引用它）
    签名人：K_code 私钥。它就在安装命令里，节点注册时用一次
 ⑤ 吊销表 RL {version, issued_at, 被吊销的节点公钥指纹[]}
    签名人：passkey 当场签；`enroll` 委托的密钥只能签针对「自己加的节点」的条目（节点校验条目指向的 Binding 属于这份委托）

安装命令里的代码就是 K_code 的种子；Backend 的一次性加入令牌由它派生，所以命令仍然是一行。
所有签名带用途前缀（域隔离），规范化编码；格式不协商、不降级。

7.2 节点验证（本地，Backend 不参与信任）

节点固定创世 owner 公钥。链随期望状态下发（Agent 的 peers、Probe 的 probe_agents 里每个成员带着自己的链），节点在状态同步时验，每个成员验一次、结果进成员表；对等握手（敲门加现有的对端认证）完全不变，没有额外字节和运算。Agent 接纳 Probe、Probe 接纳 Agent，各自验同一条链：

OpSet：从创世公钥起，每个版本由 owner 凭证签、版本递增；节点持久化见过的最大版本。
Grant：签发凭证在 OpSet 里且角色够；WebAuthn 断言有效（rpIdHash、UP/UV 标志、clientData.type = webauthn.get、challenge = SHA256(Grant)、ES256 验签）；当前时间在有效期内。
Ticket：由 Grant 的委托公钥签；issued_at 落在 Grant 窗口内；expires_at − issued_at ≤ max_ticket_ttl（来自 OpSet 里签发凭证的限制）；节点当前时间 ≤ expires_at。
Binding：由 Ticket 的 K_code 签；节点密钥和对等面公钥与这个成员条目里的一致；角色匹配（Probe 只能是 probe）。握手时对端证明自己持有这把对等面密钥，用的是现有的认证。
RL：指纹不在最新吊销表里（持久化见过的最大版本）。

通过后记进本地成员表（持久化，离线也认），同时进入敲门的名册（KnockGate 的 peers）；没通过的成员条目直接丢弃并计数，不回详细原因。Probe 只拨公网地址（拒绝私网、回环、链路本地），解决「被攻破的 Backend 让 Probe 探测客户内网」。

7.3 能强制什么，不能强制什么

节点能强制：谁是成员（链）、时间（Grant 窗口、Ticket 过期、单券 TTL 上限）、角色、吊销。
节点强制不了：数量上限（它不知道别的节点）。由签名人执行（浏览器或 Backend 的 key 路径）。

8. 节点属主与 extension 授权（预留）

后面会做 extension（web ssh、文件、抓包，见 security.md 第 11 节）。这类能力连管理员都不信任：管理员能删，不能读，也不能用。所以入网链现在就要给每个节点留出「属主」这个概念，即使 extension 还没做，字段也先固定下来，之后不用重装节点。

 属主 controllers = 一组 passkey 凭证 [{credential_id, sign_pubkey(ES256), enc_pubkey?}]
   默认：添加者（签入网券的那个账户）的全部 passkey
   添加节点时可以从已有的 passkey 里选（含全选）：允许为该节点绑定一组 passkey，而不是只绑一个人的一把
   写在哪：入网券里（由添加者的委托签名），节点绑定引用它；节点本地持久化，随成员表一起保存

 extension 的授权（每次调用）
   操作员签名的一次性能力令牌 {节点 ID, extension, 命令哈希, not_before, not_after, nonce}
   签名必须是属主里某把 passkey 的 WebAuthn 断言（challenge = 令牌哈希），节点用自己存的属主公钥验
   —— 不是「操作员集合里任意 admin/owner 的 passkey」，而是「这个节点的属主」

 谁能做什么
   属主            启用或使用 extension；增删属主（需要现有属主中的一把签名的 ControllerUpdate）
   admin / owner   只能删除节点或卸载 extension（吊销表，照常当场 passkey）；读不到、用不了
   Backend         只搬运。交互式会话的内容端到端加密（浏览器 ↔ extension），Backend 看不到明文

要点：

删除和使用分开：吊销表没有「使用」的含义；账户角色（owner、admin）不赋予任何 extension 权力。owner 想用某个节点的 web ssh，也得是那个节点的属主。
改属主不经过 Backend 的账户系统：ControllerUpdate {node_id, version, controllers} 由现有属主的 passkey 签名，节点持久化见过的最大版本；账户被删除、角色被改都改不了某个节点的属主。
属主是 passkey 凭证，不是账户：账户只是 Backend 里给人看的标签；节点只认公钥。一个人丢了全部属主 passkey，这个节点上的 extension 就没人能用了，要用就得重装节点（和第 3 节的恢复一致），所以添加时建议绑两把以上。
属主字段在**步骤 4（入网链）**就写进 Ticket；extension 本身、ControllerUpdate 和能力令牌放在阶段六。

8.1 添加节点时选属主（接口现在就留）

API：POST /api/admin/join-tokens 和 enroll key 的签发请求都带可选的 controllers: [credential_id…]；缺省 = 签发账户的全部 passkey。校验：每个 id 必须是已注册的 passkey（任何账户的都可以，比如把同事的一把加进来），数量不超过上限。
界面：「添加 Agent / Probe」对话框里一个「属主 passkey」多选列表，按账户分组，带全选、组内全选和反选；默认勾选自己的全部；至少选一把；提示「只有这些 passkey 能授权这个节点上的 web ssh 等敏感能力，管理员也不能」。
节点详情页显示属主（凭证 id 和所属账户），以及「由谁绑定」；改属主走 ControllerUpdate，需要现有属主签名，管理员做不了。
没有 extension 的现阶段，这组字段只是被签名、被节点持久化，不起别的作用。

8.2 数据用属主的私钥解密：Backend 解不开，也改不了

目标：交互式会话（web ssh、终端）、以及以后 extension 产生的数据（文件、抓包），只有属主 passkey 对应的私钥能解开。Backend 被篡改或被攻破，拿到的只有密文，且改动密文会被发现。

 浏览器（属主）                         Backend（只搬运）                  节点上的 extension
   ① 生成会话临时 ECDH 密钥 e
   ② passkey 对「e 的公钥 ‖ 节点 ID ‖ 命令哈希 ‖ nonce ‖ not_after」做 WebAuthn 断言（能力令牌）
   ──────────── 能力令牌 + e 公钥 ───────▶ 转发 ─────────────────────────▶ ③ 验：断言来自本节点属主
                                                                              + 令牌新鲜、nonce 未用
   ◀── 节点的会话公钥（节点身份密钥签名）── 转发 ◀────────────────────────── ④ 节点生成临时密钥 n，签名后返回
   ⑤ 双方 ECDH(e, n) → HKDF（绑定两边公钥、令牌哈希、用途标签）→ 会话密钥
   ⑥ 之后双向都是 AEAD 密文（ChaCha20-Poly1305 或 AES-GCM，BCL 自带），每帧带序号，
      序号进 AAD，重放、乱序、丢帧、篡改都会解密失败

终端输出等从节点流向属主的数据，只能被拿着会话私钥 e 的浏览器解开；Backend 没有 e，也没有节点的 n，算不出会话密钥。
临时密钥带来前向保密：长期的 passkey 只用来签名授权，不参与解密，所以以后 passkey 泄露也解不开历史会话。
Backend 篡改密文、重放、乱序：AEAD 校验失败，会话立即断开并计数。Backend 仍然能做的：拒绝服务、延迟、丢包，以及看到元数据（谁连哪台节点、什么时候、流量大小）。
**静态数据（以后的抓包文件、会话录像）**需要事后解密，不能只靠临时密钥：属主记录里的 enc_pubkey（P-256 ECDH 公钥）就是为此预留的，数据用它封装（ECIES：临时密钥 + HKDF + AEAD）。私钥有两种来源，按设备能力选：
1. WebAuthn PRF 扩展：由 passkey 派生私钥种子（浏览器用 prf 取 32 字节，经 HKDF 得到 P-256 私钥）；私钥不落盘，每次要解密时再触控一次。设备不支持 PRF 就退到下一种。
2. 浏览器里的不可导出密钥：添加属主时在这台浏览器生成，只能在这台浏览器用，丢了就解不开。属主记录里没有 enc_pubkey 的节点只支持实时会话，不能存加密的静态数据。
加密发生在属主这一侧的浏览器和节点上的 extension 之间，不经过 Backend 的任何账户、角色、会话机制，所以改 Backend 的数据库或代码也无从下手。

9. 流程

流程	步骤
引导	初始 owner 密码登录 → 注册第一个 passkey → 一行安装命令带创世公钥 → 节点首次注册时固定（和加入代码同一信任通道）
加节点（人）	接入窗口内点「添加」→ 浏览器用 D 签入网券 → 生成命令（含 K_code 种子）→ 用户一行安装 → 节点用 K_code 签 Binding → Backend 存好并随 `peers`、`probe_agents` 下发。人不在场也行（券在有效期内）；过期就重新生成
加节点（自动化）	`enroll` key 调 `POST /api/admin/join-tokens` → Backend 用种子现算签名密钥签券 → 其余同上
吊销	吊销窗口内当场 passkey 签 RL → 全部节点持久化最大版本 → 被吊销的节点连不进来，旧表复活不了它。`enroll` key 可以吊销自己加的节点
增删 passkey、换角色	owner 当场触控签新 OpSet 版本 → 节点自己同步，不用重装
恢复	passkey 全丢：用离线恢复密钥签新的操作员集合，重新加 passkey（节点不用重装）。恢复密钥也丢了才重装节点并换创世公钥（部署脚本 `--operator-key`）
弱信任（开发、实验室、升级过渡）	节点安装时显式选择不固定操作员，行为回到「信任 Backend」；管理页标「弱信任」。这是显式降级，不会静默发生

10. 存储

Backend：accounts、credentials（passkey 公钥、计数器）、sessions、api_keys（认证值哈希、能力、委托、IP 白名单、有效期、最后使用）、grants、tickets、opsets、revocations、audit_log；join_tokens、agents、probes 加归属列和 Binding。
节点本地（ConfigStore）：创世公钥、见过的最大 OpSet 和 RL 版本、成员表（含准入凭证 id）。

11. 落点（不新增项目）

机制	落点
WebAuthn 断言、OpSet、Grant、Ticket、Binding、RL 的编码和验签（纯函数，只用 BCL 的 ECDSA）	`Fleet.Identity`
`trust` 状态类型（OpSet + RL）、成员条目带链、同步时验证、成员表持久化	`Fleet.Link` 的 `StateHandler`（对等握手不变）
能力常量、`Principal.Has`、端点 `.Requires`、对账测试	`MoShiro.Protocol`、`Backend.Api`
账户、passkey 注册与登录、会话分级、提权窗口、审计、API key	`Backend.Application`、`Storage.Sqlite`、`Backend.Api`
管理端：passkey 登录与注册、提权状态条、API key 创建界面（预设、全选）、审计页	`web/admin`
安装命令带创世公钥和 `K_code`；`fleet-enroll` 签 Binding	`packaging/install`、`Fleet.Enrollment.Client`

12. 实施顺序（每步可独立验证和推送）

能力模型与守卫：Capability、Principal.Has、端点声明、对账测试、API key 创建界面（预设、全选、能力子集校验）。不改节点。已实现（破坏性：旧令牌作废，数据库迁移 v11 重建 api_tokens）。登录会话在步骤 2 之前拥有全部能力（包括信任类），信任类的 passkey 要求从步骤 2 起强制。IP 白名单推迟：本部署经 Cloudflare、frp 和 Caddy，后端看到的来源地址是代理，需要先有「可信代理」配置，才做得对。events.read 对应现有的 GET /api/admin/events，不是预留。
账户、passkey、会话分级、审计：WebAuthn 注册与登录、提权窗口（接入、吊销、凭证三类）、审计日志、归属列和详情页显示。passkey 登录已实现（见第 3.1 节）；提权窗口、审计日志、归属列还没做。
操作员集合与创世公钥固定：fleet-enroll 和安装命令改造、弱信任开关、离线恢复密钥的创建与导出。
入网链：Grant、Ticket（含属主 controllers）、Binding 的签发和节点验证（验证一次、缓存结果）；成员条目随期望状态下发、节点在状态同步时验证；Probe 只拨公网地址；enroll key；节点信任状态上报和管理页显示（第 14 节）。添加节点的界面可以选属主（默认添加者的全部 passkey）。
吊销表与操作员集合更新；自动化夹具（测试里的软件 ECDSA 凭证）；安装脚本的供应链（第 15 节：静态签名脚本、按 digest 拉镜像）。

13. 局限

数量上限只能由签名人执行，节点只强制时间；窗口过期后设备被攻破的人，最多还能多签有效期内的入网券（受节点时钟约束）。
节点的时钟被攻破或严重偏差会影响 Ticket 过期判断。
WebAuthn 只验 ES256 和 attestation = none，不验设备证明。
passkey 和恢复密钥都丢失才需要重装节点；某个节点的属主 passkey 全部丢失，这个节点上的 extension 就没人能授权。
enroll key 是持有者凭证：谁拿到种子 S，谁就能在它的范围和有效期内加节点，必须按密码对待。

14. 节点信任状态上报

Backend 被篡改时，你需要一个不经过 Backend 账户系统的信号。节点把自己的信任状态报给面板，面板显示对比：

节点在 hello、状态变化时和每 5 分钟（不进每次心跳）上报：创世公钥指纹（前 8 字节）、见过的操作员集合版本和吊销表版本、成员数、是否弱信任、各原因的拒绝计数。每次不到 100 字节。
面板的节点列表显示一个信任状态：正常、版本落后（节点的操作员集合或吊销表版本低于面板持有的）、弱信任、时钟偏差过大（超过入网券 TTL 的一半，或超过 60 秒；面板用 hello 的 NowUtcMs 算）、拒绝计数上升、超过 10 分钟没有上报。
这些是节点经认证的链路上报的，被攻破的 Backend 伪造不了，但可以压住不显示——所以「长时间没有上报」本身也是红色，面板同时显示 Backend 自己持有的版本和节点上报的版本，对不上就是信号。
被攻破的节点可以说谎，但它说不了别的节点的状态。

15. 安装脚本的供应链

一行安装要执行 Backend 吐出的脚本、拉仓库里的镜像。Backend 或仓库被攻破，就能在新节点上执行任意命令。收束办法：

脚本是静态产物：不在服务端做字符串替换（替换会破坏签名）。CI 用发布密钥给 install.sh、install.ps1 签名，随 Backend 一起发布；参数（代码、面板地址）通过命令行参数传入，代码也因此不再出现在 URL 和反向代理的访问日志里：curl -fsSL https://panel/install | sh -s -- '<code>'。
镜像按 digest 拉取：脚本向面板取已签名的清单（和更新用的是同一份，发布密钥签名、seq 防回滚），用脚本里内置的发布公钥验签，再按清单里的 digest 拉镜像。Backend 改不了 digest，最多让节点装到一个旧的合法版本。
角色（Agent 还是 Probe）、镜像仓库地址仍由代码决定，但镜像身份由签名清单决定。
剩下的第一跳信任（脚本本身）：想要严格的人可以先下载脚本，对照 Gitea 发布页公布的 SHA-256 再执行；管理端同时给出「先下载再核对」的写法。Windows 版同理，另外可以加 Authenticode 签名。
放在阶段五（Backend 应用层身份固定）一起做。

16. 效率（运行时开销与日常摩擦）

目标机器是 1 核 1 GB 的小鸡，甚至路由器。原则：重活留在 Backend 和浏览器，节点只做最小的验证；节点不增加线程、定时器、依赖，数据路径上不增加任何东西。

节点的预算（实现时当成验收标准）

项	预算	怎么做到
数据路径	零增量：UDP 数据面、测量、对等握手、敲门都不变	链随期望状态下发，在状态同步时验，不在握手里验（见 7.2）
常驻内存	增量 ≤ 1 MB	成员表上限 256 条（每条几百字节）、操作员集合上限 64 个凭证；不缓存原始链，只存验过的结果和哈希
二进制	增量 ≤ 150 KB	只用 BCL 的 ECDSA、HKDF、SHA-256；WebAuthn 只验断言（固定结构的 `authenticatorData`、对 `clientDataJSON` 只比三个字段），不带通用 CBOR 解析；注册和 attestation 解析只在 Backend 和浏览器里
CPU	每个成员一次完整验证（约 4–6 次 ECDSA 验签），小核心（Cortex-A53、MIPS 级）上 ≤ 100 毫秒；不重复验	只在状态同步时做；文档版本或成员链哈希没变就跳过；操作员集合或吊销表版本变化时，只重验受影响的成员
线程和定时器	不新增	信任状态上报搭现有心跳计数（每 N 次心跳带一次，约 5 分钟）；验证在已有的状态处理里串行完成
流量	链约 2 KB，只在成员首次出现或变化时随期望状态下发；上报每次 < 100 字节	同步时带成员标识（哈希），未变化的不重发
输入上限	单条链 ≤ 8 KB、成员 ≤ 256、凭证 ≤ 64、单次同步最多验 N 个成员	超限在做任何密码学运算之前拒绝；Backend 也只下发它自己预先验过的链（挡掉垃圾，节点仍然独立验证）

把预算变成测试

Fleet.Tests：链验证耗时断言（CI 机器上每个成员 ≤ 20 毫秒）、输入上限的拒绝测试、同一份状态重复同步不重复验证（计数断言）。
现有 ArchitectureTests 继续禁止节点引用新包；加一条检查：节点项目不引用 WebAuthn/CBOR 之类的库。
CI 记录节点二进制大小和启动后的常驻内存，增量超出预算就失败。

Backend 侧

WebAuthn 验证只发生在登录、提权、创建 key；API 请求认证是一次哈希查表，主体缓存 30 秒并在撤销时主动失效。
enroll key 签一张券是一次 HKDF 加一次 ECDSA 签名（不到 1 毫秒）。
审计日志的写入并进 SQLite 单写入者的批量提交，不拖慢摄取路径。
webhook 投递、数据拉取都在 Backend 里完成（见 5.4），对节点零开销。

日常摩擦

进页面不要求 passkey，信任类操作发生时才提权；窗口内连续操作不再弹。
批量操作一次触控：批量吊销是一张吊销表一次签名，批量添加是窗口内连续签券；列表都支持全选。
自动化走 enroll key，不需要人在场；其余自动化走普通 key。
离线恢复密钥（见第 3 节）避免因为 passkey 丢失而重装节点。

17. 待确认

窗口默认值：接入 15 分钟、吊销 5 分钟、凭证类不设窗口。
API key 的 IP 白名单要不要做（倾向做，放在第 1 步）。
迁移后，现有 admin 令牌不能生成加入代码，需要触控创建 enroll key 来替换。
owner 与 admin 之外要不要加只读的认证角色（目前用 read 能力的 API key 满足）。
属主的默认值：添加者的全部 passkey，还是只有签这次入网券的那一把；添加时最多允许绑定几把。
ControllerUpdate 要几把属主签名（一把还是多数）。
静态数据的私钥来源：优先 WebAuthn PRF，不支持时是否接受「浏览器里的不可导出密钥」（只在这台浏览器能用）。
会话 AEAD 选 ChaCha20-Poly1305 还是 AES-GCM（两者 BCL 都有；小机器没有 AES 硬件指令时前者更快）。
信任状态上报的阈值：时钟偏差红线（入网券 TTL 的一半与 60 秒取小）、「长时间没有上报」是 10 分钟，是否合适。
安装脚本的哈希在哪里公布（Gitea 发布页之外还要不要放 DNS TXT 或另一个独立渠道）。
节点预算的数字（常驻内存 ≤ 1 MB、二进制 ≤ 150 KB、每个成员验证 ≤ 100 毫秒、成员上限 256）是否合适；超出预算时优先砍什么（比如先去掉操作员集合的 64 个凭证上限换成更小的）。
webhook 和数据拉取的配额默认值（每分钟请求数、每天行数）和事件清单。

35 KiB Raw Blame History Unescape Escape