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 联邦（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 可达，不取决于联邦是否启用）。