feat: allow read API scoped PATs

[Robs87]

Summary

• add a dedicated read:api PAT scope for long-lived read API clients
• allow /api/v1/read/* to authenticate with read:api PATs while keeping MCP and write/profile boundaries intact
• update PAT docs and tests for the new boundary

Tests

• uv run --with-requirements requirements.txt pytest tests/test_pats_api.py tests/test_app_scope_guardrail.py tests/test_tx_read_id_resolution.py -q

[TNT-Likely]

Hey @Robs87,感谢你的贡献 —— 实现质量很扎实(scope 边界清晰、测试覆盖完整、文档也同步了)。

想了一下,目前先不合并这个 PR。把考虑过的理由写清楚,不想让你觉得是在敷衍掉:

暂时不合的几个理由

1. 心智模型变复杂。 目前的不变量 ——「PAT 只能用在 /api/v1/mcp/*,其它所有 API 看到 PAT 一律 403」—— 是一行就能说清的模型,整个 codebase 都靠这个假设。一旦加上第二个接受 PAT 的入口(即便有显式 scope gate),模型就变成「PAT 在这些路径用这些 scope 可以,在那些路径不行」。后续每个贡献者和 reviewer 都得装更复杂的模型,这个成本是累积的。

2. /read/* 会变成对外契约。 现在 /read/* 是 Web 端自己的内部 API,schema 可以随时改。一旦外部长期 PAT 在拉它,schema 改动要么静默 break 外部 consumer,要么得做 deprecation 周期。这是个不小的灵活度损失。

3. 泄露半径不对称。 JWT 泄露 → 1 小时自动过期。read:api PAT 泄露 → 除非用户主动 revoke 否则持续被拉。对个人记账这种敏感数据,这个不对称是有分量的。

4. get_current_user 里的隐形不变量。 缓存检查顺序调换之后,任何未来 dep 把 request.state.bc_user 设上,PAT 就能透传过 get_current_user。这个安全不变量现在是靠代码风格维持的,不是类型或测试强制的 —— 后续贡献者迟早会破。

5. 还没有验证过的需求。 目前没有 issue 或用户反馈要求这个能力。如果你有具体的使用场景(自建 dashboard、同步到别的工具等),欢迎单独开个 issue 描述一下 —— 这种讨论经常能挖出更合适的方案。

保留原不变量的替代方案

如果将来重新评估,几个保留「PAT = MCP」清白模型的方向:

• 长期只读 JWT(独立 token 类型)给外部只读 consumer 用
• STS 式换 token:PAT 调 /auth/token 换短 JWT,客户端用 JWT 调 /read/* —— 保留边界,代价是多一步换 token
• endpoint 级显式 opt-in 装饰器,而不是路由级一刀切 —— 强制每个 endpoint 显式声明是否允许 PAT,review 时容易抓

后续

如果你在做某个具体集成,欢迎开 issue 把场景说一下,我们一起想想合适的设计形态。你这份代码会是个不错的起点,如果将来真要做这个能力。

再次感谢付出和这份用心。先留个档。

[TNT-Likely]

@pullfrog 分析下这个pr