Mastodon

概览

提供商 ID 为 mastodon。Mastodon 没有全局主机：你指定的实例处理所有请求，并确定已保存账号身份和连接使用的 HTTPS 地址（域名）。提供商会在这个实例上注册应用，使用 PKCE 运行授权码流程，并发布一条文本动态。

要求

• 实例的基础 URL，例如 https://mastodon.social。
• 一个可供授权步骤回调的重定向 URI。
• 一个授权范围列表，其中包含流程之后需要使用的全部范围。

实例的授权端点必须收到之后请求的所有范围；否则它会以 invalid_scope 拒绝，完全不会签发令牌。

凭证

该提供商没有凭证输入模式：接受的凭证对象为空，连接改为通过浏览器授权完成。client id、client secret 和 PKCE verifier 都保存在连接的私有状态中，绝不会复制到预览、写入结果或错误中。

连接

{
  "type": "start",
  "provider": "mastodon",
  "options": {
    "instance": "https://mastodon.social",
    "redirectUri": "https://example.com/oauth/callback/mastodon",
    "scopes": ["read:accounts", "write:statuses"]
  }
}

syndroo connect --input connect.json --json

instance、redirectUri 和 scopes 必填；已经注册应用的调用方可以选择提供 clientId 和 clientSecret。启动步骤会返回一个由浏览器在实例上完成的授权动作。

本地 CLI 会使用 --redirect-uri 和控制终端，或使用 --callback-url - 自行完成该 OAuth 回调，如凭证参考所述。这条本地回调路径只针对本地服务器做了模拟测试；尚未连接真实的 Mastodon 账号。

首次发布

{
  "type": "prepare",
  "content": { "text": "Hello from Syndroo." },
  "targets": [{ "provider": "mastodon", "options": { "visibility": "public" } }]
}

syndroo publish --input post.json --json

发布操作是一次 POST /api/v1/statuses，并带有确定性的 Idempotency-Key 请求头。服务器文档说明该键最多保存一小时，复用时返回已保存的响应。这是提供商的能力，并不允许重试：Syndroo 仍会将未知写入报告为未知，绝不会重新分类。

能力

清单声明 text。字符限制属于每个实例，而不是全局数字：提供商会在连接时从 GET /api/v2/instance 读取该值，并在冻结内容时强制执行。无法读取限制时会安全失败，而不会假设默认值，因此本指南不给出限制数字。

选项

该提供商已经验证 PKCE，原生客户端必须使用：它采用 S256 挑战方法。刷新令牌仅在实例启用过期令牌时存在，因此提供商把它视为逐实例能力，而不是全局承诺。

故障排除

错误使用通用的 { "error": "..." } 结构，空文本等验证失败会报告为 422。未解决。完整错误实体的字段列表尚未确认，因此本指南不逐一列出。

撤销与安全

撤销流程已有文档并经过验证：使用 client id、client secret 和令牌调用 POST /oauth/revoke，会返回状态码 200 且没有正文。从实例设置中移除应用也能达到相同效果；断开连接会删除本地记录：

syndroo connect --disconnect <connectionId>