MoShiro/docs/security/access.md

访问控制与入网信任链

这份文档讲谁能做什么（账户、能力、API key）和谁能让节点入网（passkey 到节点的信任根）。它是 security.md 的展开：security.md 讲缺口和威胁，这里讲现在怎么做。以已实现的为主，没做的在最后一节列出。

概要：登录和授权分开。登录证明「你是谁」，授权只看能力；改变信任（操作员集合）只认 passkey 的签名，并且这个签名由节点自己验证，Backend 只搬运，伪造不了。

1. 总览

 两个根，各管一摊
   根 A：CI（代码）  发布公钥写在安装脚本、宿主机更新器的本机配置和 Backend 里
        └─ CI 签名的发布清单 → 镜像 digest → 节点跑的二进制；安装脚本的 SHA-256 也记在清单里，并公布在发布页
        假设：CI（Woodpecker、Gitea、镜像仓库、发布密钥）可信；CI 被攻破等于能给所有节点签恶意更新
   根 B：你的 passkey（运维）
        └─ 操作员集合（passkey 签，版本递增；创世指纹在安装时固定到节点）
             ├─ 操作员的 passkey 公钥
             ├─ 服务器密钥：Backend 的身份密钥（节点据此认服务器，链路用应用层加密）
             └─ 域名（rp、origins）

 添加节点：创建加入码不需要 passkey、不需要触碰，一个码可以装任意多台。命令里只有公开的值：
   面板地址、角色、一次性码、创世指纹、属主（passkey 凭证 id）、安装脚本的哈希（命令先核对哈希再执行）
 节点注册：向面板取操作员集合链，从命令里的创世指纹验起，属主必须是集合里的凭证；任何一步不对就不注册、不交出密钥；
   通过后写 trust.json（创世指纹、链、属主），之后只认从这个创世出发的新版本
 节点和 Backend 之间：集合里登记了服务器密钥之后，节点的认证挑战要求服务器用它签名；两边各出一把临时 ECDH 密钥，
   认证签名覆盖双方的临时公钥，之后控制链路每一帧都是 AES-256-GCM（每个方向一把密钥、严格递增的计数器）。
   所以 TLS 在 Cloudflare 或被冒充的证书那里终止，中间人没有服务器密钥，既冒充不了服务器，也读不了、改不了这条链路
 密码登录和 passkey 登录的会话拿同样的能力，授权只看能力；passkey 只用在节点自己会验证的事上（现在是操作员集合的签名，以后是 extension 会话和加密数据）。
 Backend 自己拦自己没有意义，所以没有提权窗口

没有采用「成员证明」（每个节点一条 Grant、Ticket、Binding 的入网链）：被攻破的 Backend 往名册里塞节点，拿不到比 Backend 已经有的更多的东西（监测数据本来就是明文给 Backend 的；敏感的 extension 靠节点属主，不靠名册），成本却是每个节点一次触碰和一套证明格式。操作员集合和创世固定已经在，以后要叠加不用重装节点。

发布密钥可以换：见 deployment.md 的「换发布密钥」；回滚由清单的 seq 防住（更新器只收比已安装更大的）。面板信任哪些发布密钥（官方的，加上可选的自有公钥）在管理端「系统 → 信任 → 可信资产来源」。

2. 名词

名词	含义
账户	一个人，有用户名和密码，可以注册 passkey
能力（capability）	一项具体权限，如 fleet.write。端点声明自己需要哪项能力
会话	登录得到的状态，拿到全部能力（见第 3 节）
操作员集合	节点固定的、带版本的 passkey 公钥列表，加上服务器密钥和域名，由操作员 passkey 签名
API key	一串随机令牌，只带创建时勾选的能力；明文只在创建时显示一次
属主（controllers）	一个节点绑定的一组 passkey：只有它们能授权这个节点上的 extension（web ssh 等）。管理员没有这份权力，见第 9 节

3. 能力

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

• 一个能力只在一个地方声明：Capability 常量（MoShiro.Backend.Application），端点用 .Requires(Capability.X)；Principal.Has(capability) 是唯一的判断入口，会话和 API key 都走它。写蕴含读（fleet.write 带 fleet.read）。
• 对账测试：所有 /api/admin 端点必须声明能力，没声明测试就失败；OpenAPI 的每个操作带 x-moshiro-capability。
• 信任类是界面上特别标出的（吊销、账户管理），授权和其他能力一样靠 API key 或会话。passkey 签名保护的是操作员集合，由节点自己验证。
• 不能越权：创建 API key 时勾选的能力必须是创建者当前拥有能力的子集。
• Backend 更新确认：更新清单由 CI 的发布密钥签名（面板登记时验签），seq 防重放；确认只是让 Backend 有序退出并备份数据库，拉哪个镜像由 Quadlet 单元里写死的仓库和标签决定，面板决定不了。

4. 登录与会话

登录方式	说明
密码	PBKDF2；认领向导创建第一个管理员时设置
passkey	WebAuthn，只支持 ES256，attestation 一律当 none；可以登录，也能给操作员集合签名（节点验证）

• 两种方式的会话拿同样的能力。passkey 只用在节点自己会验证的事上，见第 5 节。
• 认领向导（没有默认账户）：面板里还没有任何用户时，打开 /admin/ 进向导——用后端日志里的认领码（或 MoShiro__ClaimCode）创建第一个管理员（用户名和密码自己填），注册第一个 passkey，再用它给操作员集合签名建立信任根。谁先打开页面谁就能当管理员，所以要认领码；创建完码作废、入口关闭（POST /api/admin/auth/setup 之后返回 409）。后两步是引导不是门槛，可以稍后补；不注册 passkey、不建立信任根，就添加不了 Agent，只能进面板做基础管理，这是架构如此。之后新增的 passkey 不会自动成为操作员：要由现有操作员在信任页看清「新增了哪些」再签新版本，节点才认。
• 建议每个账户至少注册两个 passkey（手机加硬件密钥）。

4.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，节点验证操作员集合也用它）；注册里的 CBOR 和 attestation 解析在 Backend（WebAuthnRegistration），节点不带 CBOR。
• 依赖方（RP）：MoShiro__WebAuthnRpId（缺省取 PublicUrl 的主机，没有就取请求的主机）和 MoShiro__WebAuthnOrigins（缺省取 PublicUrl 的来源）。passkey 绑定在这个域名上，改了会让已注册的 passkey 失效。只有和后端同站的页面能用 passkey 登录，管理端在「添加其他后端」（跨域）时不显示这个入口。
• 会话记录登录方式（password 或 passkey），只用于审计和显示；API key 不是用户，不能注册 passkey。
• 测试：SoftwarePasskey 在测试里模拟认证器走完整的注册和登录，覆盖错误的挑战、来源、RP、签名、缺少 UV、挑战重放、计数器回退、只能管理自己的 passkey。

5. passkey 用在哪里（没有提权窗口）

原则：passkey 只用在节点或密钥持有者自己验证、解密的场合。Backend 自己做的拦截在 Backend 被攻破时一起失效，所以不用 passkey 拦操作。

事	谁验证	要 passkey
建立、更新操作员集合（信任根）	节点验链	是（现在唯一做了的）
extension 会话（web ssh 等）	节点验 passkey 签名的临时密钥	是（还没做）
读加密存储的数据	私钥持有者	是（还没做）
吊销或删除节点、账号、API key、加入码、设置	只有 Backend	否，只看能力

• 这些「只有 Backend」的事靠能力限权：API key 只带需要的能力。密码泄露的后果是这些能力被滥用，改不了信任根，也用不了以后的 extension。
• 唯一的风险是往账号里塞一把 passkey 再等人签名：信任页的提案会列出新增和移除的凭证，签名之前要看一眼是不是自己加的；签了才算授权。

6. API key

• 创建时勾选能力，只能是创建者当前拥有能力的子集；可设有效期。明文只在创建时显示一次，列表显示能力数、最后使用时间、过期时间。预设：只读、运维、接入（enroll）、全部。
• 创建界面的能力用分组复选框：全选（带半选状态）、组内全选、反选、搜索；预设按钮一键套用。
• 列表（API key、加入代码、节点、审计日志）都支持多选和全选做批量操作。

6.1 enroll key：自动化添加节点

它就是一把带 fleet.enroll 的普通 API key，用 POST /api/admin/join-tokens 创建加入码，响应里直接给出安装命令（带创世指纹、属主和脚本哈希，没有任何私钥）。创建码不是信任动作，所以不需要 passkey；CI 和脚本照常工作。信任在两处：命令里的创世指纹和属主由面板生成，节点注册时固定；以后改属主和集合要操作员 passkey 签名。

6.2 CI 登记发布清单不需要令牌

CI 把签名清单 POST 给 POST /api/release/offer，面板用发布公钥验签，没有令牌，所以清库、重装、还没有 passkey 时照常工作，也没有长期令牌可偷。旧清单重放由 seq 递增挡住。

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

后面要让外部系统能订阅事件、触发回调、拉数据。接口和权限先留（data.export、webhooks.* 标预留），实现放后面；全部发生在 Backend 里，节点零开销。订阅只能订阅创建者自己读得到的事件；投递是带 HMAC 签名的 POST，至少一次、指数退避；目标 URL 要做 SSRF 限制（只放行公网地址，不跟随重定向到内网，有超时和大小上限）。这些都属于 Backend 的集成配置，不改变节点信任，但每次增删订阅都进审计。

7. 归属与审计

• 加入代码记 created_by，节点记 added_by；管理页的 Agent 详情显示「由 xxx 于 xxx 添加」。
• 审计日志（GET /api/admin/audit）：所有非 GET 的管理操作和登录自动记录（时间、账户、登录方式、动作、对象、详情）。写不进去只记日志，不让已完成的操作报错。保留 365 天，只追加。

8. 入网信任链的实现要点

• 语句是 key=value 文本，第一行是带版本的标题，签名覆盖整段文本；WebAuthn 的挑战是语句的 SHA-256。库在 Fleet.Identity 的 OperatorTrust（操作员集合的编码、解析、链验证）和 SecureChannel（服务器证明和链路加密），都是只用 BCL 的纯函数，节点和 Backend 共用。
• 创世：第一次建立信任根时，把账号下所有 passkey 和这个面板的服务器密钥登记成一个操作员集合，passkey 对它签名；创世语句的 SHA-256 就是命令里的 MOSHIRO_GENESIS。之后加删 passkey 或换服务器密钥要签新版本（上一版里的凭证签），页面会提示；签名更新不会让节点重装。
• 操作员集合版本随期望状态（trust_chain）下发，节点从固定的创世验起，版本比现有的新才采用并保存。
• 节点注册：fleet-enroll --genesis … --controllers …：先 POST /api/agent/v1/enroll/trust 取链，验过（创世指纹、签名、属主在集合里）才把密钥交出去；之后写 trust.json。没有命令里的指纹（--genesis）就不固定，节点按旧方式工作。
• 服务器身份和安全链路：ChallengeParams 带服务器的临时公钥和签名（server_eph、server_sig），AuthParams 带节点的临时公钥（node_eph），节点签名的用途是 auth2，覆盖双方的临时公钥；通过后两边用 HKDF 派生每个方向一把 AES-256-GCM 密钥，每帧 计数器(8) ‖ 密文 ‖ 标签(16)，计数器严格递增，明文帧、改动、重放、乱序一律断开。集合里没有服务器密钥的节点（旧节点）保持明文，不会被降级成放行。
• 服务器密钥存在 Backend 的设置里（server.identity_key）：它防的是面板被冒充，不是面板被攻破；面板被攻破时它也泄露，那时要由 passkey 签一个换掉它的新集合版本。集合里没有这个面板的服务器密钥的版本，Backend 不收（否则固定了它的节点就认不出这个面板了）。
• 弱点：创世指纹放在安装命令里，命令本身要从可信渠道拿到（管理端复制）。缓解见第 10 节（静态签名脚本、按 digest 拉镜像），并在信任页展示指纹供核对。

9. 节点属主与 extension 授权

extension（web ssh、文件、抓包，见 security.md）现在都不实现，Agent 一样。这类能力连管理员都不信任：管理员能删，不能读，也不能用。所以入网时就给每个节点固定「属主」，之后不用重装节点。

已经实现的部分

• 属主 controllers 是一组 passkey 凭证 id，必须是操作员集合里的凭证。由安装命令带来，节点注册时写进 trust.json，Backend 之后改不了。
• 每个 Agent 都必须有属主，至少一把。这由节点自己强制：节点启动时检查本地固定的属主，没有（或者属主的 passkey 已经不在操作员集合里）就不运行（共用 Fleet.Hosting 里的 OwnerGuard；配置 fleet.require_owner，MOSHIRO_ALLOW_NO_OWNER=1 放行）。面板被攻破也改不了。
• 添加节点时选属主：POST /api/admin/join-tokens 的 controllers: [credential_id…]，不给就是操作员集合里的全部凭证；给了就必须非空且都在集合里。还没有信任根或一把属主都没有时，面板提前拒绝创建加入码（400，字段 controllers），这只是尽早失败，真正的强制在节点；MoShiro__RequireOwner=false 可以关掉这个提前检查（只给没有信任根的老部署）。界面里是必选的「属主（passkey）」多选列表，只是选，不用触碰。
• 安装端也强制：install.sh、install.ps1、容器入口缺了 MOSHIRO_GENESIS 或 MOSHIRO_CONTROLLERS 就不装；fleet-enroll --genesis 不带 --controllers 也拒绝。
• 逆推出绑定关系：节点握手时把本地固定的属主（passkey 凭证 id）报给面板（hello 的 owners），面板顺着凭证 id 反查出它绑定在哪个账户的哪把 passkey 上，显示在「系统 → 版本」的「属主」列（对不上任何已注册 passkey 的显示「未知凭证」）。上报只是自述，真正的授权由节点自己校验 passkey 签名。

预留的设计（还没做）

• 谁来强制：节点本地。web ssh 这类会话要不要加密、要不要验证，由 Agent 自己要求。让 Backend 决定，被攻破的 Backend 一句「这次不用加密」就绕过去了。节点本地强制：没有操作员的现场证明不启动会话；会话密钥只和证明里的那把密钥协商，不和 Backend 转来的公钥协商；加密字段缺失就拒绝，不降级；能开哪些 extension、哪些 passkey 能授权，只看本节点属主。
• 证明的方向是反的：节点先出题（nonce 加它的临时公钥，用节点身份密钥签名），属主的浏览器把 nonce 和自己的临时公钥放进 passkey 断言的挑战里；节点验断言来自本节点属主、要求用户验证、nonce 是自己刚出的且没用过。Backend 仍然管谁有资格发起请求、审计、限流、转发密文。
• 交互式会话（终端、ssh）用现场签名的临时 ECDH 密钥协商，passkey 只签名授权，不参与解密，所以不支持 PRF 的 passkey 也能用，还有前向保密；之后双向是带序号的 AEAD。静态数据（抓包文件、会话录像）需要事后解密，才用属主记录里的接收者公钥加密（来自 WebAuthn PRF 或浏览器里不可导出的密钥）。
• 删除和使用分开：admin 能删节点、卸载 extension，读不到也用不了。改属主要现有属主的 passkey 签名（ControllerUpdate），账户被删、角色被改都改不了某个节点的属主。属主是 passkey 凭证，不是账户；一个人丢了全部属主 passkey，这个节点上的 extension 就没人能用了，所以添加时建议绑两把以上。
• 数据边界：监测数据（延迟、丢包、吞吐、事件、主机资源汇总）是明文，Backend 要做分析和展示；extension 会话和原始 payload 端到端加密，Backend 只存转发密文。读取权由私钥决定。

10. 安装的供应链

一行安装要执行 Backend 吐出的脚本、拉仓库里的镜像。Backend 或仓库被攻破，就能在新节点上执行任意命令。收束办法，优先级最高的是第一跳的哈希核对：

① 脚本是静态产物，哈希固定

• 不在服务端做字符串替换。CI 构建时算出 install.sh、install.ps1 的 SHA-256，写进发布清单（发布密钥签名），同时公布在 Gitea 发布页——这条渠道独立于 Backend，这是哈希核对有意义的前提：哈希若和脚本从同一处来，攻击者两个一起换就行。
• 参数（代码、面板地址）通过命令行环境变量传入，代码因此不出现在 URL 和反向代理日志里。
• 管理端给的命令把「下载、核对、执行」合成一行，哈希核对不通过就不执行：

f=$(mktemp) && curl -fsSL https://panel/install -o "$f" && echo "<sha256>  $f" | sha256sum -c - && MOSHIRO_SERVER=… MOSHIRO_ROLE=… MOSHIRO_CODE=… sh "$f"

macOS 用 shasum -a 256 -c，Windows 用 Get-FileHash 比较，不通过就 throw。命令里的 <sha256> 由 Backend 填入，信任页同时标出它与 CI 签名的发布清单是否一致；严格的人对照 Gitea 发布页一次即可（脚本是静态的，哈希在一个版本内不变）。

② 镜像按 digest 拉取

• 脚本向面板取已签名的清单（和更新用的是同一份，发布密钥签名、seq 防回滚），用脚本里内置的发布公钥验签，再按清单里的 digest 拉镜像（repo@sha256:…）。Backend 改不了 digest，最多让节点装到一个旧的合法版本。
• 下载压缩包安装的人，用 Release 里签名的 SHA256SUMS 核对（见 deployment.md）。

③ 容器安装：Podman 系用 Quadlet（默认），Docker 用 compose

• 管理端的容器安装是：建目录，把参数写进本地 .env（面板地址、一次性码、创世指纹、属主，都是公开的值），下载面板提供的静态 compose 文件、核对 SHA-256，compose up -d。compose 文件是静态的（和安装脚本一样嵌在 Backend 里，也作为 Release 资产发布），镜像是 :latest 或 .env 里固定的版本，镜像地址由 CI 渠道决定，不由面板决定，面板被攻破也改不了；Backend 第一次部署时没有面板，就从 Release 资产下载。
• 代价：客户端不再验发布签名，更新（compose pull && compose up -d）靠 TLS 加「注册表可信」这个假设；想要更严，在 .env 里把 MOSHIRO_VERSION 固定到 digest，或者用宿主机更新器（清单有发布签名，不健康自动回滚）。详见 deployment.md。

④ 其余

• 角色（Agent 还是 拨号方）、镜像仓库地址仍由代码决定，但镜像身份由签名清单决定。
• macOS 的 Developer ID 签名和公证、Windows 的 Authenticode 需要证书，目前没有做。

11. 运行中的二进制不做校验

曾经做过「节点二进制绑定」：节点握手时自报正在运行的二进制的 SHA-256，Backend 在第一次握手时绑定，之后对不上就标红或拒绝。已经移除。

原因：哈希和清单都是节点自己报的。一个被换进来、故意撒谎的二进制可以照抄原来的哈希和清单，Backend 分辨不出——上报者就是被怀疑的对象。这一层只能抓到「文件被换了、但程序本身没撒谎」的情形，却让人误以为有保障，还要求运维宿主机更新器、状态卷和每个节点的清单。得不偿失。

「这个资产是我们的」靠安装时的来源证明，那里的哈希来自另一个信道，伪造不了：

• 安装脚本（SHA-256 记在签名的清单里，并公布在发布页），按清单里的 digest 拉镜像（repo@sha256:…）；
• 下载压缩包的人用签名的 SHA256SUMS 核对（验签用 packaging/update/release-key.pub.pem）；
• 节点的更新由宿主机更新器用本机公钥验签，只认本机配置的镜像仓库。

要让运行中的二进制真的无法伪造，必须有容器之外的东西背书：宿主机更新器持有一把节点进程读不到的密钥，对「当前运行的镜像 digest + Backend 的挑战」签名，由节点转发；容器里的进程被换掉也伪造不了，除非攻破宿主机。这一步没有做（一键容器安装的节点也没有宿主机更新器）。

12. 还没有的与局限

• 还没有：吊销表；任务和配置内容的操作员签名；节点向别人证明自己运行的就是官方二进制（见第 11 节）；extension 本身、属主的 ControllerUpdate、接收者的实际加密（属主只是被固定在节点本地，没有行为）；API key 的 IP 白名单（本部署经 Cloudflare、frp 和 Caddy，后端看到的来源地址是代理，需要先有「可信代理」配置才做得对）；OIDC 登录。
• WebAuthn 只验 ES256 和 attestation = none，不验设备证明。
• 某个节点的属主 passkey 全部丢失，这个节点上的 extension 就没人能授权，需要重装节点并换属主。
• 删除一把操作员 passkey 只是让它不能再签新版本；服务器密钥换新要靠签一个新集合版本，忘了签会让固定了集合的节点认不出面板（fail closed）。
• enroll key 是持有者凭证，谁拿到令牌，谁就能在它的有效期内创建加入码，必须按密码对待。