permissions-broker

Permissions Broker 是一种创新的用户控制型 API 代理机制，专为解决 AI Agent 在缺乏本地凭证时的外部数据访问需求而设计。该技能通过建立"申请-审批-执行"的三段式工作流，让用户通过 Telegram 实时掌控每一次对外部服务的访问请求，在便利性与安全性之间实现了精准平衡。

核心用法围绕代理请求的生命周期展开。Agent 使用用户签发的 PB_API_KEY 向 Broker 服务创建代理请求，指定目标上游 URL（如 Google Drive、GitHub API 或 iCloud CalDAV），随后系统自动进入等待状态。用户会在 Telegram 收到审批通知，查看请求的详细信息后决定授权或拒绝。一旦获批，Agent 立即执行该请求并获取上游响应，且每个请求仅能执行一次，有效防止重放攻击。对于 Git 操作，该技能还提供专门的 Smart HTTP 代理会话管理，支持克隆、拉取、推送等完整工作流。

显著优点体现在其安全架构设计上。首先，强制性的 Telegram 人工审批机制确保了"人在回路"（Human-in-the-loop），任何外部数据访问都需用户显式同意，彻底杜绝了静默数据泄露的风险。其次，一次性的执行模型（One-time execution）意味着即使请求 ID 被截获，也无法重复利用，大大降低了凭证泄露后的影响面。此外，该技能对敏感信息的处理极为规范，明确禁止将 API 密钥提交至代码仓库或写入日志，并支持可选的跨会话存储加密。提供商白名单机制（目前支持 Google、GitHub、iCloud）进一步限制了潜在的攻击面。

潜在局限性主要集中在可用性和灵活性方面。由于强制依赖 Telegram 进行审批，该技能无法用于完全自动化的无人值守场景，且审批流程存在超时限制（默认 30 秒轮询），可能导致长时间任务中断。1 MiB 的响应大小限制对于大型文件导出或批量数据查询可能构成瓶颈。此外，当前仅支持三家主流云服务商，对于需要访问其他特定 API 的用户而言扩展性有限。Git 推送操作的单次使用限制也可能在复杂发布流程中带来不便。

适合的目标群体包括：注重数据主权和隐私保护的个人用户；需要在合规环境下操作企业数据的知识工作者；以及无法长期存储本地 OAuth 凭证的临时计算环境用户。特别适合那些希望利用 AI 自动化处理 Google Workspace 文档、GitHub 仓库管理或 iCloud 日历，但又不愿将完整账户权限授予 AI 的场景。

使用风险方面，首先是服务可用性依赖——作为第三方托管服务（permissions-broker.steer.fun），其稳定性直接影响功能可用，建议关键业务场景制定降级方案。其次是密钥管理责任——虽然 Broker 提供了安全的代理层，但 PB_API_KEY 本身的管理仍完全依赖用户，一旦泄露，攻击者可在用户不知情的情况下发起待审批请求（尽管仍需用户点击批准）。最后是数据过境风险——所有请求流量均经过 Broker 服务器中转，虽然采用端到端加密，但敏感数据仍流经第三方基础设施，对极高安全要求的场景需谨慎评估。