federation

ActivityPub 联邦协议

此技能帮助理解 ActivityPub 协议规范以及联邦机制的运作方式。

**关于支持的功能和兼容性：**请参阅 FEDERATION.md，了解已实现的 FEP、支持的标准以及联邦兼容性详情。

**关于实现细节：**请参阅 AGENTS.md，了解转换器、处理程序和 PHP 代码模式。

核心概念

三大构成要素

1. Actor - 系统中的用户／账户

   • 每个 Actor 都有唯一的 URI
   • 必需属性：inbox、outbox
   • 可选属性：followers、following、liked

2. 活动 - Actor 执行的操作

   • Create、Update、Delete、Follow、Like、Announce、Undo
   • 包装对象，以描述其共享方式

3. 对象 - 被操作的内容

   • Note、Article、Image、Video 等
   • 可以嵌入，也可以通过 URI 引用

Actor 结构

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/@alice",
  "inbox": "https://example.com/@alice/inbox",
  "outbox": "https://example.com/@alice/outbox",
  "followers": "https://example.com/@alice/followers",
  "following": "https://example.com/@alice/following",
  "preferredUsername": "alice",
  "name": "Alice Example",
  "summary": "Bio text here"
}

集合

标准集合

收件箱 - 接收传入的活动

• 根据活动 ID 去重
• 根据权限进行筛选
• 处理活动产生的副作用

发件箱 - 发布 Actor 的活动

• 记录 Actor 发布内容的公开记录
• 根据查看者权限进行筛选
• 用于显示个人资料中的活动

关注者 - 关注此 Actor 的 Actor

• 在 Follow 活动被接受后更新
• 用于确定投递对象

正在关注 - 此 Actor 关注的 Actor

• 跟踪订阅关系
• 用于构建时间线

公开寻址

特殊集合：https://www.w3.org/ns/activitystreams#Public

• 使内容可公开访问
• 不要投递到此 URI——它是一个标记，而非真实的收件箱
• 在 to、cc、bto、bcc 字段中用于设置可见性

活动类型

Create

包装新发布的内容：

{
  "type": "Create",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Note",
    "content": "Hello, Fediverse!"
  }
}

Follow

发起订阅：

{
  "type": "Follow",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob"
}

• 接收方应回复 Accept 或 Reject
• 只有在收到 Accept 后才将其加入关注者列表

Like

表示赞赏：

{
  "type": "Like",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

Announce

转发／提升内容：

{
  "type": "Announce",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

Update

修改现有内容：

• 提供的属性会替换现有属性
• null 值会移除字段
• 必须包含原始对象 ID

Delete

移除内容：

• 可以替换为 Tombstone，以确保引用完整性
• 应级联删除相关活动

Undo

撤销之前的活动：

{
  "type": "Undo",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Follow",
    "id": "https://example.com/@alice/follow/123"
  }
}

服务间联邦

活动投递流程

1. 解析接收方

   • 检查 to、bto、cc、bcc、audience 字段
   • 解引用集合以查找单个 Actor
   • 对接收方列表去重
   • 排除活动自身的 Actor

2. 发现收件箱

   • 获取 Actor 个人资料
   • 提取 inbox 属性
   • 如有 sharedInbox，则使用它以提高效率

3. 通过 HTTP POST 投递

   • Content-Type：application/ld+json; profile="https://www.w3.org/ns/activitystreams"
   • 使用 HTTP Signatures 进行身份验证
   • 妥善处理投递失败

收件箱转发

**幽灵回复问题：**当 Alice 回复 Bob 的帖子，而 Carol 关注该帖子时，如果 Carol 不关注 Alice，她可能看不到这条回复。

**解决方案：**收件箱转发

• 收到寻址到本地集合的活动时
• 如果活动引用了本地对象
• 将活动转发给集合成员
• 确保对话参与者能看到回复

共享收件箱优化

对于同一服务上有许多接收方的公开帖子：

• 使用 sharedInbox 端点，而非逐个使用收件箱
• 减少 HTTP 请求数量
• 由服务在内部进行分发

寻址和可见性

To／CC 字段

• to - 主要接收方（在界面中公开）
• cc - 次要接收方（抄送／提及）
• bto - 隐藏的主要接收方（投递时隐藏）
• bcc - 隐藏的次要接收方（投递时隐藏）

**重要：**投递前移除 bto 和 bcc，以保护隐私

可见性模式

公开帖子：

{
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/@alice/followers"]
}

仅关注者可见：

{
  "to": ["https://example.com/@alice/followers"]
}

私信：

{
  "to": ["https://other.example/@bob"],
  "cc": []
}

内容验证

安全注意事项

1. 验证来源

   • 不要未经验证就相信声称的来源
   • 检查 HTTP 签名
   • 验证相关对象是否由对应的 actor 所有

2. 防止欺骗

   • Mallory 可能声称 Alice 发布了某些内容
   • 在处理副作用之前，始终先进行验证

3. 速率限制

   • 限制递归解引用
   • 防范拒绝服务攻击
   • 实施垃圾信息过滤

4. 内容净化

   • 在浏览器中渲染前清理 HTML
   • 验证媒体类型
   • 检查恶意载荷

协议扩展

支持的标准

完整的已实现标准和 FEP 列表请参见 FEDERATION.md，其中包括：

• WebFinger - Actor 发现。
• HTTP Signatures - 请求身份验证。
• NodeInfo - 服务元数据。
• 各类 FEP（Fediverse 增强提案）。

FEP（Fediverse 增强提案）

FEP 为 ActivityPub 增添了更多功能。常见的 FEP 类别包括：

• 长文支持。
• 引用帖子。
• 活动意图。
• 关注者同步。
• Actor 元数据扩展。

此插件支持的 FEP： 已实现的 FEP 权威列表请参见 FEDERATION.md。

OAuth 2.0 客户端到服务端

启用 ActivityPub API 选项后，第三方客户端可通过 activitypub/1.0/oauth/ 使用 OAuth 2.0 进行身份验证。该插件支持 RFC 7591 动态注册、RFC 7636 PKCE（仅限 S256，默认要求公共客户端使用）以及 CIMD 草案（URL 格式的 client_id，必须使用 HTTPS）。

RFC 8252 — 环回重定向 URI

原生应用会在本地打开的环回端口上接收 OAuth 回调。根据 RFC 8252 §7.3 / §8.3，接受 http://127.0.0.1:{port}/{path} 和 http://[::1]:{port}/{path} 格式的重定向 URI，且端口灵活（请求时可使用任意端口）。为兼容起见，也接受 localhost，尽管 §8.3 将其标记为“NOT RECOMMENDED”。

环回地址许可仅适用于重定向 URI 匹配。保留但非环回的地址——0.0.0.0、链路本地地址 169.254.0.0/16、RFC1918 私有地址范围（10/8、172.16/12、192.168/16）等——不会被视为环回地址，也绝不会绕过 wp_safe_remote_get()。CIMD 元数据 URL 必须使用 https://，并且在发起任何抓取之前，都会解析元数据主机并验证其是否属于私有/保留地址范围——即使在开发安装环境中，也不支持环回 CIMD 源。

实现细节： 请参见 includes/oauth/class-client.php（尤其是类文档块和 is_loopback()）以及 FEDERATION.md 中的 OAuth 部分。

实现说明

WordPress 插件特定内容

此插件实现了：

• Actor 类型：用户、博客、应用程序
• 转换器：将 WordPress 内容转换为 ActivityPub 对象
• 处理程序：处理传入活动

实现细节请参见：

• AGENTS.md，了解代码结构
• 集成指南，了解扩展方式

测试联邦

# Test actor endpoint
curl -H "Accept: application/activity+json" \
  https://site.com/@username

# Test WebFinger
curl https://site.com/.well-known/webfinger?resource=acct:[email protected]

# Test NodeInfo
curl https://site.com/.well-known/nodeinfo

常见问题

未收到活动

• 检查收件箱 URL 是否可访问
• 验证 HTTP 签名校验
• 确保 content-type 标头正确
• 检查是否存在防火墙/安全拦截

回复未进行联邦分发

• 验证是否已启用收件箱转发
• 检查寻址中是否包含相关 actor
• 确保已正确设置 inReplyTo

关注者同步问题

• 检查是否已针对 Follow 活动发送 Accept 活动
• 验证关注者集合是否更新
• 确保在可用时使用共享收件箱

Resources

• ActivityPub Spec
• ActivityStreams Vocabulary
• RFC 8252 — OAuth 2.0 for Native Apps
• RFC 7591 — OAuth 2.0 Dynamic Client Registration
• RFC 7636 — PKCE
• draft-ietf-oauth-client-id-metadata-document
• Project FEDERATION.md
• FEPs Repository