[Security][CODE] Use purpose-bound credentials at every desktop Alpha entry point

[jinjunnn]

Covers

jinjunnn/alpha-work#8：桌面所有 Alpha 生产入口使用 purpose-bound credential，并由 main-owned action client 选择服务端授权动作；renderer 不持有 service credential。

Boundary

Desktop identity/account/billing/job/artifact client wiring、credential selection/storage boundary、typed authorization errors、contract tests 与 docs。

Out of scope

服务端 token 签发/验证矩阵；OS vault 的 custom provider secret（alpha-code#226）；旧 user JWT、scope-less token 或 fallback credential 兼容。

Design notes and risks

必须盘点深链、重试、后台恢复和 MCP/tool 入口，避免只有主 UI 切换；token 不得进入 renderer/log。

Exit condition

Merged PR + bin/check green + each production entry wiring test green + docs handled。运行时拒绝矩阵归 VERIFY。

Parent

Refs jinjunnn/alpha-work#8

[jinjunnn]

W0 存量普查复核:PARTIAL(保持 OPEN)

初判为 DONE,经对抗证伪后推翻。

票面要的用户可观察效果
桌面所有 Alpha 生产入口都用按用途签发的凭据(每个入口拿到的 token 只对该动作有效、错用途即拒),凭据选择与存储留在 main 进程,renderer 不持有任何 service credential。

已达成的半场 / 仍缺的半场
原裁决的主实体(main 进程 5 个 HTTP 入口 + 2 条 sidecar env 接缝 + renderer 零凭据)我逐条独立复核后成立。但它判整票 DONE 所依赖的两根支柱都被推翻。

== 已达成的半场(我自己验过) ==
alpha-auth.ts:94-100 ROUTE_PURPOSES 与契约 packages/alpha-contracts-consumer/src/types.ts:1 逐字对齐;:358-368 getAccessToken(purpose) 取出必过 requireTokenPurpose,不匹配就 throw;:530-560 decodeTokenResponse 强制五个 purpose 缺一不可且键与声明一致。逐入口实读均传具体 purpose:alpha-cloud-jobs.ts:44/80/120/129/142/156、alpha-cloud-events.ts:38、alpha-cloud-schedules.ts:32、alpha-platform-models.ts:44、alpha-account.ts:35、cloud-ipc.ts:55。两条 env 接缝写前再验(:281-303),且先无条件 delete。devPlatformToken 已钉死非 packaged(:136-142)。preload/types.ts 的 AuthState 无 token 字段。真存在一道逐入口接线闸(alpha-cloud-jobs.cases.ts:20-31/:97-98/:125)。它对 alpha-upload-manifest.ts:150 的订正也是对的。

== 仍缺的半场（为何 refuted）==
【一】它自己给的例外借口是事实错误。它写云 MCP 那一格「凭据仍是按资源绑定的独立凭据，用户可观察效果(凭据不跨动作复用)成立」。写这份契约的人在源码里逐字否掉了它:alpha-web lib/token-claims.ts:205-212 — mcp_access「is NOT a PurposeBoundClaimsV1: it has no purpose at all … one credential, a set of actions the user consented to once, and that set is the scope array」。桌面那张令牌的 scope 数组实际是 cloud.dispatch, cloud.read, artifact.read,同一张 bearer 可以派作业、读状态、拿产物字节、跑收费的 cloud_web_search(any-of 里 cloud.dispatch 就够，mcp-tool-registry.ts:100-107)。main 侧对这三个动作是三张互不通用的 token。判权口径也不同:token 类是 claims.purpose !== action 即拒(action-authorization.ts:163),mcp_access 是 scopes.includes(action) 的集合成员判定(:189-194);它被三个独立路由面接受而不是一个资源。凭据持有与选择在引擎自己的 OAuth 库,不存在票面要的 main-owned action client。而票面 Design notes 点名要盘的就是 MCP/tool 入口。

【二】它自称比逐点枚举强一格的「咽喉级判据」不是咽喉。那只对 stored.platformAccessTokens 这一个字段成立,对凭据材料不成立:applyAuthEnv 把两张 token 明文写进 main 自己的 process.env(alpha-auth.ts:294-303),整个会话都留着(server.ts:117 / alpha-config-injection.ts:90 每次 fork 前还在读),并镜像成 alpha-secrets/* 文件(alpha-secret-files.ts:18-20 明写同 UID 进程去找就读得到)。一个新模块写 fetch(cloudUrl, { authorization: Bearer ${process.env.ALPHA_API_KEY} }) 一个字节不碰那个字段,它的判据全绿而 AC 被违反 —— 错误实现能满足它的判据,判据就太粗。

【三】Exit condition 明写 each production entry wiring test green;它自己承认 #405 无 PR,而我只找到 cloud jobs 一族的接线闸,云 MCP 入口无对应的「凭据只对该动作有效」闸。

== 为何不是 SUPERSEDED ==
REQ-130/#733/aw#127 确实是已批决定,改掉的只是六个入口族里的一个;票面「所有入口」这个范围本身没被推翻。按 DONE 关会把「桌面每个入口都是 purpose-bound」写进留痕,而这句话今天是假的。建议:要么保票 open 只剩 MCP 入口一格,要么关票时将那一格另开一票并写明「引擎持有的三动作 bearer」是 owner 已接受的形态。

推翻方给出的反证

• /Users/tide/app/alpha-web/lib/token-claims.ts:205-212 — 契约作者原文:mcp_access「is NOT a PurposeBoundClaimsV1: it has no purpose at all … 'one credential, a set of actions the user consented to once', and that set is the scope array」。直接否掉原裁决「凭据不跨动作复用」那句。
• /Users/tide/app/alpha-web/lib/oauth.ts:99 — CLOUD_CLIENT_SCOPES = ["cloud.dispatch", "cloud.read", "artifact.read"]:桌面 MCP 通道实际被授予的三个动作,装在同一张令牌里。
• /Users/tide/app/alpha-platform/packages/gateway/src/lib/mcp-tool-registry.ts:122-124 — MCP_SUPPORTED_SCOPES = 注册表 requiredAction 并集(含 model.invoke);生产消费点两处非注释:protected-resource-metadata.ts:50 的 PRM scopesSupported、mcp-transport-auth.ts:104 的 401 challenge。
• /Users/tide/app/alpha-platform/packages/gateway/src/lib/mcp-tool-registry.ts:68-107 — 五工具 requiredAction:cloud_dispatch=[cloud.dispatch]、cloud_status/cloud_await=[cloud.read]、cloud_artifacts=[artifact.read]、cloud_web_search=[cloud.dispatch, model.invoke] any-of ⇒ 三 scope 令牌可达全部五个工具(含收费的 web search)。
• /Users/tide/app/alpha-platform/packages/gateway/src/lib/action-authorization.ts:189-194 — mcp_access 判权是 principal.scopes.includes(request.action)(集合成员);对照 :163 的 claims.purpose !== request.action → 拒。两种口径。
• /Users/tide/app/alpha-platform/packages/gateway/src/lib/tenant-auth.ts:162 — claims.scope ∩ MCP_SUPPORTED_SCOPES → mcpAccessPrincipal(tenant, granted):多动作 principal 的真实构造点。
• /Users/tide/app/alpha-platform/packages/gateway/src/lib/mcp-transport-auth.ts:41 与 /Users/tide/app/alpha-platform/packages/gateway/src/worker.ts:194 与 /Users/tide/app/alpha-platform/packages/gateway/src/routes/cloud-jobs.ts:59 — 同一张 mcp_access 被三个独立路由面接受(整个 /mcp 面、网关 web-search 路由、产物字节内容端点),不是「按单一资源绑定」。
• /Users/tide/app/alpha-code/packages/ui-mac/src/main/cloud-sidecar-config.ts:16-19 — 凭据「改由引擎自己的 OAuth 凭证库按 server URL 绑定持久化并自动刷新」,这份定义里「一个凭证通道都不该有」⇒ 该入口的凭据选择/存储不在 main。

---

出处:2026-08-10 W0 存量普查第二轮。方法 = 12 个子系统批各自实读代码给出裁决,再对每一条会导致关票的裁决单独派对抗方证伪。本批 6 条关票候选全部被推翻(5 条从 DONE/SUPERSEDED 降为 PARTIAL,1 条方向相反),所以本票保持 OPEN。

[jinjunnn]

票面清理(2026-09-16):关闭 —— 已完成。

这张票要的是:桌面端每个连云的入口,只带「这件事专用」的登录凭证,拿去做别的事会被服务器拒绝;凭证由后台进程保管,界面层拿不到。今天主干上这件事已经成立,所以关闭。

2026-08-10 普查曾以三条理由保留本票,逐条对照今天的主干:

1. 「云 MCP 那一格的凭证由引擎自己的授权库持有,且一张令牌带三个动作」—— REQ-144(alpha-code#1188,已关)之后,云 MCP 凭证改为登录时由后台进程铸造、经文件通道注入(oauth:false),不再由引擎交互式授权持有;三动作的范围是 REQ-144 已批方案基线明确选定的形态(docs/design/req-144-login-minted-mcp-access.md:149-151 DESKTOP_MCP_SCOPES)。
2. 「令牌写进后台进程环境变量,新模块可能拿错」—— 这是判据粒度问题,不是用户可见行为:拿模型令牌去调云任务,平台按用途拒绝(alpha-platform lib/action-authorization.ts:167)。
3. 「云 MCP 入口没有接线测试」—— 现有 cloud-mcp-header.test.ts、cloud-mcp-auth-sweep.test.ts。

证据(alpha-code origin/alpha):

• packages/ui-mac/src/main/alpha-auth.ts:102-111(ROUTE_PURPOSES / AUTH_ENV_PURPOSES)、:285-318(applyAuthEnv 写入前逐个校验用途)
• 入口按用途取令牌:alpha-cloud-jobs.ts:83,220、alpha-cloud-events.ts:38、alpha-cloud-schedules.ts:39、alpha-platform-models.ts:50、alpha-account-request.ts:39
• 云 MCP:cloud-sidecar-config.ts([REQ-144][CODE] 云 MCP 凭证改走登录铸 token 的 {file:} header 通道(oauth:false) #1200)
• 相关合并 PR:feat(ui-mac): REQ-109/110 T2+T5+T3+T4 —— 有界续期 + expiresAt 调度 + 目录/账户解耦 + token 换血免 reload #556、fix(auth): #600/#601/#602 token 生命周期 —— 终态可达、401 不自激、旧响应不复活登出、无效期限不成环 #610、[REQ-144][CODE] 云 MCP 凭证改走登录铸 token 的 {file:} header 通道(oauth:false) #1200

重开条件:新增的桌面连云入口不经按用途取令牌;或 owner 决定云 MCP 也要拆成单动作令牌。

如判断有误,直接重开即可;重开时请在评论里说明新出现的情况。