federation

Overview ¶

directory.go — 联邦节点名录透传（2026-10-14 邀请信箱配套；2026-10-22 由 直传包搬入）。

名录端点无鉴权（零敏感，公开信息），registry URL 由宿主从管理端 SystemConfig 注入（已过 SSRF 校验）。直传未启用/二进制缺失不挡名录查询—— 名录可见性只取决于 registry 可达。

归属：名录是对端站点列表，属联邦域，不属直传域——本文件不依赖 p2pc 运行时。

命名（2026-10-22 L3）：PeerDirectory = 联邦节点名录，**无条件**构造 （可见性只取决于 registry 可达，与联邦运行时是否启用无关；见 invite.go 文件头的三类服务命名约定）。

Package federation 实现 PigeonBox 的 P2P 联邦面（跨实例口令路由 + 邀请交接）。

三个角色与构造条件（2026-10-22 命名统一） ¶

本包导出三个服务，**构造条件不同**，这是设计使然、不是遗漏：

Node          本机节点运行时：节点身份（ed25519）、注册中心心跳、分享公告。
              仅在 federation.enabled 时构造；配置不合法时 bootstrap 降级
              为非联邦模式（单站功能不受影响）。
PeerDirectory 在线名录：列出联邦内可发现的对端。**无条件构造**——联邦关闭时
              名录仍要能读出「为什么不可用」，且注册中心地址来自配置而非运行态。
InviteMailbox  邀请信箱：待收邀请的出箱/留痕。**无条件构造**——收件箱在联邦
              关闭时也必须可用（邀请可以先到、联邦后开）。

与设备直传的关系 ¶

2026-10-22 Wave B' 起，Box 侧**不再编排设备直传**（原 p2px 域已整包删除）， 直传本体归独立应用 PigeonBeam。本包只保留联邦面（口令路由 + 邀请信封交接）。

Package federation 将本站点接入 PigeonBox P2P 联邦（github.com/pigeonbox/p2p）。

职责（M2，设计文档 docs/specs/2026-10-04-p2p-registry-service-design.md §5）：

• 节点注册/心跳：Ed25519 签名租约，断线自动重注册 + 全量补公告（自愈）；
• 口令联邦路由：share 生命周期钩子公告/撤销 SHA-256(code)→本节点；
• 解析代理：GET /api/v1/federation/resolve 转查 registry（浏览器免跨域）。

信任模型：本包只做"发现"，取件方直连源节点、源节点本地校验口令——零跨节点信任。 签名负载格式与 p2p 仓 README 契约逐字节一致（见 client.go 常量注释）。 依赖方向：本包不 import 生态任何兄弟模块（叶子约束，core CI dep guard）。

本包三类服务按**构造条件**分家（2026-10-22 L3 命名收口，读者一眼可辨）：

Service        联邦运行时（注册/心跳/公告/解析）——**仅联邦启用时**构造
               （NewService 在 !cfg.Enabled 时报错，由装配层降级为非联邦模式）。
InviteMailbox  联邦邀请收件箱——**无条件**构造：跨实例交接的凭证与状态机，
               与联邦运行时无关（联邦关闭时公开收件端点仍可用）。
PeerDirectory  联邦节点名录——**无条件**构造：可见性只取决于 registry 可达。

后两者的实例由装配层（bootstrap/wiring.go）构造，直传编排层只消费 （setter 注入）——删掉直传编排层时联邦能力不受影响（Wave B'）。

invite.go — 联邦信封管理（跨实例推送邀请；2026-10-22 由直传包搬入）。

语义：邀请 = 口令 bearer（与手工交接同信任级——口令本身即授权，通道只是 递送）；收件箱内存态（cap 20 / TTL 10 分钟 = p2pc 配对窗口，进程重启丢弃 可接受，口令同样已失效）；出站推送目标 URL 走 SSRF 守卫（与 registry_url 同策略，私网目标需 security.ssrf.allow_private_networks）。

归属：信封是跨实例交接的凭证与状态机，属联邦域，不属直传域——本文件不 依赖 p2pc 运行时（无 spawn / 子进程 / 任务环），Wave B 删直传包时 本包原样留存。

命名（2026-10-22 L3）：本包三类服务按"构造条件"分家，读者一眼可辨——

• Service：联邦运行时（注册/心跳/公告），**仅联邦启用时**构造；
• InviteMailbox：联邦邀请收件箱，**无条件**构造（联邦关闭时仍可用， 它是跨实例交接的凭证与状态机，与联邦运行时无关）；
• PeerDirectory：联邦节点名录，**无条件**构造（可见性只取决于 registry 可达，不取决于联邦是否启用）。