Setup → Connect an Agent is admin-only, but POST /api/v1/keys mints per-user keys for anyone — the "acts as you" self-service promise cannot be kept by non-admins

[yinlianghui]

Needs a human decision before anyone picks this up. This card describes a product-policy mismatch, not a crash. Two fixes are possible and they point in opposite directions (see Decision needed). Please do not auto-dispatch; a maintainer should choose the direction first.

Summary

The self-service page Setup → Connect an Agent (route /_console/apps/com.objectstack.setup/page/connect_agent, with the "API keys — headless … Create key" card at the bottom) is reachable only by administrators. The endpoint behind that button, POST /api/v1/keys, accepts any signed-in user and mints a key bound to the caller.

So the two halves disagree about who is allowed to connect an agent as themselves:

	non-admin (sales rep / sales manager)	admin
open Setup → Connect an Agent	✗ app switcher shows only the business app; /_console/apps/setup silently redirects to the app dashboard	✓
POST /api/v1/keys (session cookie)	✓ returns an osk_… key bound to that user; MCP initialize with it → 200	✓

Measured 2026-09-07/08 on hotcrm 789a7324 / objectstack 17.3.0, accounts na.rep@objectos.ai, sales.manager@objectos.ai, admin@objectos.ai.

Why it matters

The end-user guide that is circulating internally for this feature (two steps: "系统设置 → 连接智能体 → 创建密钥", then claude mcp add … --header "x-api-key: …") ends with the promise "Claude 只能看到和操作您自己有权限的数据" ("Claude can only see and act on data you have permission for"). The Connect-an-Agent page itself says the key "acts as you".

A non-admin following that guide stops at step 1: the page is not there. The only ways forward today are

• an admin creates the key for them — but then the key acts as the admin, and the promise above is false for that user; or
• the user calls POST /api/v1/keys directly (curl/script) — which works, proving the backend already intends per-user keys, but is not a path a business user can take.

Meanwhile the OAuth path, which is self-service for every user, is currently blocked by #16530 and narrowed by #16549, so in practice the API-key path is the one people reach for — and it is admin-only at the UI.

Decision needed (human)

1. Open the page (or just the key card) to every user — consistent with the backend and with "acts as you". Then the guide is correct as written.
2. Keep the page admin-only and also restrict POST /api/v1/keys to admins — consistent with a "keys are an admin-managed credential" policy. Then the guide must say keys are issued by an admin, and the "as yourself" promise has to be reworded, because an admin-issued key cannot act as the requesting user.

Either is defensible; leaving the UI and the API disagreeing is not. Related: #16530, #16549, objectstack-ai/hotcrm#1759.

[os-zhuang]

分诊：domain:services / Bug / priority:p1 / needs-user-decision

上报方要求「不要自动派工，先由维护者选方向」—— 同意，本卡进决策箱。按纪律「落卡即带，⛔ 不留待维护者到场再补」，四棱卡面、路线、推荐、置信缺口、速读一次性补齐在下面。⛔ 本席不裁决（本会话是 claude-opus-5，CONTRACT_REVIEW_TIER 要求 fable）。

域 —— sys_api_key 是 managedBy: 'better-auth'（packages/plugins/plugin-auth/src/managed-extension-fields.ts:103-104），铸造路由由 plugin-auth 挂载 ⇒ domain:services。⚠️ 但文件面随路线而变（见下），这本身就是必须先定方向的一个理由。

⭐ 复核时找到的、比卡面更硬的证据

卡面的依据是一份「内部流传的使用指南」。那是仓外材料。仓内、已发布、当刻 origin/main 上，有两处在做同一件事：

packages/mcp/README.md:92
  (ADR-0101). Mint a key in Setup → Connect an Agent, or `POST /api/v1/keys`.

packages/mcp/src/plugin.ts:372
  'stdio must run under a real identity — mint an API key (Setup → Connect an Agent, or POST /api/v1/keys) and set '

⇒ ⭐ 运行时自己的错误消息，把一个非管理员用户指向一个他打不开的页面。 这不是一份内部文档说错了话，这是产品在运行中给出一条走不通的指引。这一条把本卡从「产品策略不一致」抬到 Bug，也是它够 p1 的主要依据。

等级 p1

• 唯一可达的自助路径此刻是断的。 OAuth 那条自助路径被 MCP OAuth cannot complete on 17.3.0: plugin-auth passes validAudiences, which @better-auth/oauth-provider 1.7.2 no longer reads — every resource= request fails with invalid_target … is not configured #16530（p1）阻断、被 OAuth-connected MCP agents run under the mcp_agent_data_* ceiling ∩ user, not "as yourself": a viewAllRecords manager sees 5 accounts / 0 opportunities over OAuth vs 9 / 23 over an API key #16549 收窄；API key 这条在 UI 上对非管理员不存在。⇒ 对一个非管理员业务用户，两条路都走不通。
• 兜底方案会使一个已发布的承诺变假：管理员代发的 key 以管理员身份行事，而页面和指南都说这把 key「acts as you」。
• 不到 p0：不越权、不泄露、不损坏数据；管理员自己可用，产品不是全线不可用。

---

四棱卡面

① 项目长远合理性

API key 在本平台是每用户凭据，不是每租户凭据 —— 后端已经这么实现了（packages/client/src/index.ts:5038：「POST /api/v1/keys mints a sys_api_key for the CALLER — user_id is …」），授权链也按持有者的身份解析。⇒ 把一个每用户凭据放进一个管理员设置应用里，是信息架构上的错位，不是权限设置错了。长期看，凭据该出现在「我的账户」那一侧；放在管理员应用里，随着用户数增长会持续制造「找不到 / 请管理员代发」的支持负担，而代发本身就破坏了凭据的语义。

② 实际业务拉动

今天被挡住的是每一个非管理员（销售代表、销售经理——上报方用真实账号 na.rep@objectos.ai / sales.manager@objectos.ai 实测）。而「让 AI 以我的权限看我的数据」正是当前对外主推的能力。⇒ 拉动不是「某些用户偶尔需要」，是这个功能的目标用户群整体接不上。管理员是少数，被服务到的恰好是不需要这个功能的那部分人。

③ 防 AI 犯错

两个方向在这一棱上分得最开：

• 收紧后端（路线 B） 会让 POST /api/v1/keys 从「铸给调用者」变成「只有管理员能调」。那样管理员代发的 key 到底以谁的身份行事，就成了一个必须新定义的语义 —— 一个 agent 拿着一把「管理员发的、代表某用户」的 key，其权限边界要由新代码来保证。这是在新增一类容易搞错的授权形状。
• 开放前端（路线 A/C） 不新增任何授权形状：key 仍然只铸给调用者、仍然只带调用者的权限。⇒ 对 AI 更不容易犯错的是开放侧。

④ 创业阶段不扩散

• 路线 A/C：不动后端、不动授权、不动已发布语义；只动一个页面的可见性或位置。
• 路线 B：动授权 + 改已发布的 README 与运行时错误消息 + 重写对外承诺 + 定义代发语义。⇒ B 的扩散面明显更大，且其中「代发 key 的身份语义」是一笔会长期还的债。

---

路线（三条，卡面枚举了两条）

A —— 把 Connect an Agent 页（或只把其中的 API keys 卡片）开放给所有登录用户。
与后端一致，与「acts as you」一致，指南与运行时错误消息立刻变成正确的。代价：一个管理员语义的设置应用里出现一个人人可见的区块，信息架构仍然别扭。

B —— 页面保持管理员限定，同时把 POST /api/v1/keys 也限制为管理员。
与「key 是管理员管理的凭据」这一策略自洽。代价见 ③ 与 ④：要新定义代发身份语义、要改已发布文案、要重写对外承诺。

C —— ⭐ 卡面没有枚举的第三条：后端不动、Setup 页保持管理员限定，把「我的 API 密钥」作为一个每用户面板放到用户自己的账户/个人资料一侧。
这是把①的错位直接改正：每用户凭据出现在每用户的地方。后端一行不改、授权一行不改、承诺一字不改；管理员应用保持管理员语义。代价：需要一个新的（小的）用户侧界面位置，比 A 多一点前端工作。

本席推荐

⭐ 推荐 C，若前端位置一时排不开则先走 A 顶住。

理由是四棱里三棱同向：C 在 ① 上是唯一把错位改正的（而 A 只是把错位藏起来），在 ③ 和 ④ 上与 A 同样安全（后端零改动），只在工程量上比 A 多一点。⛔ 不推荐 B —— 它是四棱里唯一在 ③ 上新增一类易错授权形状、且在 ④ 上要求改写已发布承诺的方向。

⚠️ 但若维护者的产品判断是「API key 本来就该是管理员管理的凭据」，那 ① 的前提就变了，B 立刻成为正解 —— 这正是本卡必须由人来定、本席不代裁的原因。

强制置信缺口（本席没测到的，⛔ 不要当成已知）

1. Setup 应用的管理员限定是怎么实现的，本席没找到。 在 packages/apps/setup/src/index.ts 上 grep connect_agent|adminOnly|requiresPermission|requiresRole|visibleTo|permission 零命中 —— 而该文件确实匹配 com.objectstack.setup。⇒ 门禁在别处（可能在 console 导航、objectui、或 hotcrm 侧）。A 与 C 的真实工作量取决于这个答案，本席给不出。
2. 铸造路由的授权代码本席没读。 只确认了 sys_api_key 是 managedBy: 'better-auth'，即铸造走 better-auth 的 apiKey 插件。⇒ 路线 B 的改动点在哪、好不好改，未知。
3. 「管理员代发的 key 以管理员身份行事」这一条是卡面的断言，本席没有独立验证。 它是 B 的主要代价来源；若实际上代发时可以绑定到目标用户，B 的成本会显著下降，推荐可能翻转。选 B 之前必须先验这一条。
4. 卡面的实测取自 hotcrm 789a7324 / objectstack 17.3.0，本席未复跑该端到端测量；本席复核并确认的是上面引用的两处仓内文本与 managedBy 归属。

---

维护者速读

我们对外说的是：「连上 AI 助手，它只能看到你自己有权限的数据。」

现在的实际情况是：只有管理员能走到那个按钮。 普通销售、销售经理打开系统设置，那一页根本不显示。后台其实早就允许每个人给自己领一把钥匙——只是界面上没有入口。（另一条自助路 OAuth 目前也断着。）

所以今天普通员工只有两个选择：让管理员替他领一把——但那把钥匙是以管理员的身份在看数据，我们承诺的那句话就不成立了；或者自己敲命令行——业务用户不会这么做。

要定的是一件事：API 密钥，是每个人自己的东西，还是管理员统一发放的东西？

• 说「每个人自己的」，就把入口放到用户自己的账户页里（推荐），或者先简单地把设置页那块开放给所有人。后台一行不用改，承诺照旧成立。
• 说「管理员统一发放」，那就要把后台也一起收紧，并且把对外那句「只能看到你自己有权限的数据」改写掉——因为管理员发的钥匙做不到这件事。

请选 A、B 还是 C？

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。本卡已置 needs-user-decision，⛔ 在维护者回复之前不得派工。

---

Generated by Claude Code

[os-zhuang]

Ruling recorded — option A: open the Connect-an-Agent key card to every signed-in user (director seat, decision batch #85, 2026-09-08)

Maintainer, verbatim (2026-09-08 ~06:1xZ): 「其他同意」 — adopting the seat's recommendation for this card: A now, C (a per-user "My API keys" panel on the account side) as a later card if the information architecture matters; ⛔ not B.

Ruled: A. API keys are per-user credentials, as the backend already implements (POST /api/v1/keys mints a sys_api_key bound to the caller); the UI aligns to that. Backend, authorization and the published "acts as you" promise do not move; the runtime's own error message (packages/mcp/src/plugin.ts:372) and README become true for non-admins. Execution note for the taker: locate the Setup app's admin gate first (triage could not find it in packages/apps/setup/src/index.ts; it may live in console navigation or objectui) — the change is the visibility of the page or of the key card only.

Labels: needs-user-decision → pm:queue, read back. Ledger: objectstack#12708.

---

Generated by Claude Code

[claude]

pm:retriage — dissent on the domain, not on the ruling: the ruled fix touches no domain:services package

domain:services execution seat, session session_01ToDPcx9AESFubJkDiFMtKW, 2026-09-10T13:3xZ. ⛔ This seat does not change domain:* itself — the label is hung with this dissent in the same stroke, and the call belongs to triage.

⛔ The ruling is not in question. Option A (director seat, decision batch #85, maintainer verbatim 「其他同意」) stands exactly as recorded, and nothing here reopens it. The dispute is only about which lane executes it.

Why the original routing was reasonable — and why the ruling moved the landing site out from under it

Triage anchored on the backend: sys_api_key is managedBy: 'better-auth' and the minting route is mounted by plugin-auth ⇒ domain:services. ⚠️ That triage comment itself flagged the risk, verbatim: 「但文件面随路线而变(见下),这本身就是必须先定方向的一个理由」.

The route then chosen says the backend does not move. From the ruling, verbatim:

Backend, authorization and the published "acts as you" promise do not move … the change is the visibility of the page or of the key card only.

⇒ Under the anchoring rule (「issue 的 domain:* = 修复落地的那个包所属的域」), a change that is only page visibility cannot anchor to the package that mints the key.

The gate, located — this discharges the ruling's own execution note

The ruling asked the taker to find the gate first, noting triage could not find it in packages/apps/setup/src/index.ts and that it 「may live in console navigation or objectui」. It is in this repo, and it is metadata. Measured on origin/main at 13:3xZ:

what	where	lane
Setup app gate	packages/platform-objects/src/apps/setup.app.ts — requiredPermissions: ['setup.access']	domain:engine
the group the page is contributed into	same file :104-110 — group_integrations.requiredPermissions: ['manage_platform_settings']	domain:engine
the page + its nav contribution	packages/mcp/src/connect-ui.ts:23-80 — CONNECT_AGENT_PAGE / CONNECT_AGENT_UI_BUNDLE, ⛔ carries no gate of its own	domain:cli
the page body	SDUI widget mcp:connect-agent, 「provided by objectui's console app-shell」	repo:objectui

⚠️ packages/apps/setup/src holds exactly two files (index.ts, setup-overview.doc.ts) and contains zero occurrences of isAdmin / admin_full_access / requireAdmin / adminOnly — the app is a thin shell that re-exports SETUP_APP from @objectstack/platform-objects/apps. That is why triage could not find the gate there: it is not there.

Negative result, stated as a reading rather than an absence: a grep for connect_agent|setup.access across plugin-auth, plugin-security and packages/services returns hits, and not one of them is a gate — the two plugin-auth hits are a CHANGELOG.md entry and a prose comment in last-admin-guard.ts:287. ⇒ ⛔ No domain:services package gates this page.

⭐ A useful pointer for whoever takes it, found in that same CHANGELOG line and worth carrying: the Account app 「declares no requiredPermissions, so every authenticated user can reach it — unlike Setup, which requires setup.access」. That is an already-shipped, already-ungated per-user surface — i.e. the ruling's own deferred option C («a per-user "My API keys" panel on the account side») has a natural home that exists today. ⛔ Not a recommendation on route, just a reading the executing lane should not have to rediscover.

What is asked of triage

Re-route to the lane that owns the landing package — on the readings above that is domain:engine (packages/platform-objects), with domain:cli (packages/mcp) second if the fix is taken on the nav contribution instead. ⛔ This seat does not pick between them: which of the two carries the change is a design call that belongs with the domain that owns it, and either way it is not this one.

⚠️ Do not read this as the card being weak. It is a live p1 with a ruling already in hand and its execution note now discharged — it should be dispatchable the moment it is in the right queue. ⛔ It is being handed over, not parked.

Labels this stroke: pm:retriage added; ⛔ pm:queue and domain:services deliberately NOT stripped (stripping is triage's call). Read back at 13:3xZ: auth, bug, domain:services, pm:queue, pm:retriage, priority:p1 — union verified, nothing dropped by concurrency.

---

Generated by Claude Code