Skip to content

Commit cae8d8f

Browse files
docs(adr): ADR-0151 an AI service account is a registered principal of its own, with its own keys and its own name on every row (#31615)
<!-- claude-projects-attribution: {"github_login":"os-zhuang"} --> _Requested by **Sam** · [project thread](https://claude.ai/code/project/chan_01GsBogozeZG5sdpAARrN7HP?thread=cmsg_01GsBogozeZG5sdpAARrN7HPVAuE8pR4mjNZGhhDFx4Kap)_ ## 维护者速读 今天通过 MCP 用 API 密钥接入的 AI 就是密钥主人本人:系统列不出它、数不清它,也不能单独收窄权限或停用。本 PR 新增 ADR-0151(草案)定义「AI 服务账号」: - **是什么**:一行 `sys_user`,`principal_kind = 'agent'`,有一位负责人;只属于一个组织,只是普通成员;由组织管理员登记。 - **永不登录**:在身份驱动层一处拒绝为它创建会话和登录凭据,覆盖所有登录方式和模拟登录。 - **权限**:只来自显式授予的权限集,受 ADR-0090 D10 规则 2 的 agent 上限约束,在求值时生效;不继承负责人的权限。 - **凭据**:由已登录的管理员或负责人为它签发 API 密钥。个人自己的密钥仍然是本人(2026-09-16 的裁定不变)。 - **归属**:账号本身就是写入主体,审计行的 `user_id` 就是它。 - **停用**:暂停就是现有的 ban 状态,下一次调用即被拒;恢复后原密钥照常可用。 - **计数**(cloud ADR-0116 D7):一个登记账号算一个 agent 身份,按行计,不按密钥或调用计。开源侧不含任何许可逻辑。 **与卡片不同的一处,请留意**:卡片第 3 项建议用 `performedBy` 记录账号。本 ADR 改为让账号本身做主体(`user_id`),`performedBy` 仍只记 OAuth 客户端。原因见 D5:否则审计行会写成「agent 代表它自己」,同一个键也会混用两种 id。 合并方式:`docs/adr/**` 是受治理路径(Tier H),本 PR 保持草稿,由维护者合并,合并即采纳。合并后可以按本 ADR 立 O3(账号本身)和 O4(归属)。 Closes #31603 ## What changes - **New**: `docs/adr/0151-ai-service-account-a-headless-agent-is-a-registered-principal-of-its-own.md`, status **Proposed**. It decides: - **D1**, the account: a `sys_user` row with `principal_kind = 'agent'`, born with its kind and never changed; an accountable owner (`accountable_user_id`); exactly one organization as a `member`; a placeholder address; an organization administrator or a platform administrator registers it. - **D2**, no sign-in: session creation and sign-in credentials are refused in better-auth's own hooks, for every caller. - **D3**, authority: the account is the authorization subject, with its own grants only (no member baseline, no `everyone` anchor), under rule 2's ceiling enforced at evaluation. Rule 1 does not apply, rule 3's confirmation is never self-given, and rule 5 needs nothing new. - **D4**, credentials: dedicated API keys minted for it by a signed-in person. `POST /keys` is unchanged, and a person's key stays the person's. - **D5**, attribution: `user_id` is the account, and `performedBy` stays OAuth-only (reasoned refusal of the card's item 3). - **D6**, lifecycle: register, grant, mint, revoke, suspend (the ban state), resume (administrators only), change owner, the owner leaving suspends it, retire, and last use derived from the keys. - **D7**, the boundary for cloud ADR-0116 D7: one row per agent, no licence logic here, and how cloud#3886's question 3 stands. - Options considered, non-goals, and what O2, O3, O4, O6 and cloud build on. - **ADR-0090**: a status-line amendment, plus a note under D10's 2026-09-16 API-key note that its reopening condition is met without reopening it. - **ADR-0093**: a status-line amendment. D7's deferred service-account row is resolved: the marker is `principal_kind`, and the reconciler never binds an account. - **`docs/adr/README.md`**: regenerated (`node scripts/adr-index.mjs`). ## Why cloud ADR-0116 D7 (adopted 2026-11-08) counts each agent that connects over MCP with an API key as one AI user. Its own Consequences says the rule is contract-counted only, because the runtime has no agent identity, and that the mechanism waits on this record. cloud#3820 needs the same identity for its inventory, kill switch and trace. This is the mechanism half (Prime Directive #13): the identity in open code, with the commercial half left in cloud. ## Verification Readings are of code, on `objectstack-ai/objectstack` at `158cc2aa`. Nothing was run against a server. Gates, run on the head `e93a2ada`: - `node scripts/check-adr-symbol-anchors.mjs`: ✅ 3297 anchors across 152 records resolve. A negative probe (one bogus `user-ban.ts#…` symbol appended to ADR-0151) turned it red on that line, so the gate does judge the new record; the probe was removed before commit. - `node scripts/check-adr-anchors.mjs`: OK. - `node scripts/check-adr-links.mjs`: ✅ 1064 relative links resolve. - `node scripts/adr-index.mjs --report`: OK, the index is current. Clause-②: no Metadata-protocol: none ## Acceptance notes - **Number**: 0151, because 0150 is held by open PR #31586. - **Claim**: the card carried no `Claim:`, so this thread posted one (comment 6724190959) naming this branch. - **Departures from the card**: - Item 3, `performedBy` naming the account, is refused with reasons in D5. - Item 2's optional OAuth `client_credentials` is left as a named follow-up in D4. - **Facts O3 must re-measure before building**: the resolver's `everyone` anchor skips only externals today (D3), and several readers treat `principalKind === 'agent'` as OAuth-shaped (listed under "What builds on this"). - **Owed outside this repo**: cloud ADR-0116 gains a one-line pointer to ADR-0151, as a cloud-lane edit. - **Label**: `skip-changeset`. The diff is `docs/adr/**` only and publishes nothing. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (No code.) - [x] 2. Every name I added uses the casing for its kind (`principal_kind`, `accountable_user_id`, snake_case machine names). - [x] 3. No formatter ran; no lintable source changed. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. Publishes nothing; `skip-changeset`. - [x] 6. `packages/spec` not touched. - [x] 7. No hand edits to generated or release-owned docs. - [ ] 8. Title, body and comments are in English, except the 维护者速读 above, which is Chinese for the maintainer by this project's convention. --- _Generated by [Claude Code](https://claude.ai/code/session_01QUs3BrfVH2WkyVdVACF8U8)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5d8e559 commit cae8d8f

4 files changed

Lines changed: 190 additions & 4 deletions

‎docs/adr/0090-permission-model-v2-concept-convergence.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
· **Amended** (2026-10-14, [ADR-0138](./0138-guest-model-anonymous-principal-doors-grants-and-organization.md) D3 item 5, ruling C of record 6159279205 on #23267) — D9's last bullet holds for `everyone` alone: a package suggests `everyone` bindings and the admin confirms each, while no door binds a set to `guest` (no package suggestion, no confirmation, no operator bind) until ADR-0138 D3 item 5's bind door is built, an act of the environment's administrator, never of a package. Read that bullet's `guest` half as superseded by this line.
1010
· **Amended** (2026-10-17, ruling of record 6228728551 on #23960, letter B) — D12 names three kinds of administrator, tenant-level, organization-level and delegated: an organization administrator (`organization_admin` / `organization_admin_no_bypass` for the organization, not a platform administrator) creates and removes `sys_user_position` / `sys_user_permission_set` rows for that organization's members when every set the row distributes has no `*` wildcard superuser bit, no `adminScope` and only `scope: 'org'` capabilities; `admin_full_access`, platform sets, `organization_admin` itself and every delegated set stay outside, and organization-administrator status is conferred by membership grade only. Strict containment and the `everyone` / `guest` anchors are unchanged. See the note under D12.
1111
· **Amended** (2026-10-31, ruling of record 6545950368 on #28367, go as shaped) — D10 gains rule 5, the **agent forward credential**: an `api` action's in-process forward carries the agent principal in a credential the server mints itself, bound to that one forward, single-use, short-lived and unreachable out of process, never the caller's token or key and never a human session. Two cells of the credential-kind × target-door table flip from "refuse by name" to "accept with a forward credential" (an OAuth-connected agent at an identity route and at a platform route), and a scope-family rule bounds every target outside MCP. See the amendment under D10.
12+
· **Amended** (2026-11-08, [ADR-0151](./0151-ai-service-account-a-headless-agent-is-a-registered-principal-of-its-own.md), proposed, adopted by its merge) — D10 gains a second provenance for an agent principal: a registered **AI service account**, a `sys_user` row of kind `agent` that is its own authorization subject. It holds its own grants under rule 2's ceiling, enforced at evaluation, and authenticates with its own API keys; rule 1's intersection does not apply because it acts for nobody; rule 4 records it as `user_id` and leaves `performedBy` to the OAuth client. The 2026-09-16 note stands: a person's key stays that person's credential. See the note under D10.
1213
**Deciders**: ObjectStack Protocol Architects
1314
**Builds on**: [ADR-0049](./0049-no-unenforced-security-properties.md) (enforce-or-remove),
1415
[ADR-0056](./0056-permission-model-landing-verification.md) (permission-model landing verification),
@@ -478,6 +479,8 @@ alias tax on every API.
478479
> ⛔ not a reading of this one.
479480
>
480481
> Ruling: director seat, batch #139 item 1, maintainer 「同意」 2026-09-16 — letter **A**.
482+
>
483+
> **Note (2026-11-08, [ADR-0151](./0151-ai-service-account-a-headless-agent-is-a-registered-principal-of-its-own.md)).** The requirement this note names as its reopening condition is now stated: cloud ADR-0116 D7 counts each agent that connects over MCP with an API key as one AI user. ADR-0151 meets it without reopening this note. A key still never becomes a principal; an administrator registers an AI service account, a principal of its own, and that account's keys are its credentials.
481484
482485
> **Status (2026-09-20, #18374) — rule 4's third part is NOT delivered.** `performed_by` and
483486
> `on_behalf_of` ship (#18371); no **run id** is stamped and none is pending — no agent-run

‎docs/adr/0093-tenancy-mode-and-membership-lifecycle.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-0093: Tenancy mode as a first-class capability, and a single owner for the user→membership lifecycle
22

3-
**Status**: Accepted (2026-07-13) — implemented: `tenancy` kernel service (`plugin-auth/src/tenancy-service.ts`), membership reconciler (`reconcile-membership.ts`), locked by `dogfood/test/membership-reconciler.dogfood.test.ts`
3+
**Status**: Accepted (2026-07-13) — implemented: `tenancy` kernel service (`plugin-auth/src/tenancy-service.ts`), membership reconciler (`reconcile-membership.ts`), locked by `dogfood/test/membership-reconciler.dogfood.test.ts` · **Amended** (2026-11-08, [ADR-0151](./0151-ai-service-account-a-headless-agent-is-a-registered-principal-of-its-own.md) D1, proposed, adopted by its merge) — D7's machine / service-account row: the first-class marker it waited on is `sys_user.principal_kind`. The membership reconciler never binds an account of kind `agent`, whose one membership its registration creates.
44
- **Date:** 2026-07-13
55
- **Deciders:** ObjectStack Protocol Architects
66
- **Implementation:** #2882 (Phase 0 — tactical create-user bind, merged) → this PR (Phases 1–3 — `tenancy` service, fail-fast boot guard, membership reconciler, consumer migration, backfill, docs). One revision from the original plan, ratified in D2: the endpoint-level create-user bind **delegates to the shared reconciler** (one implementation, two call sites) instead of being deleted. Runtime verification confirmed the hook fires for `admin.createUser`, but better-auth *defers* `user.create.after` post-commit (#1881), so the endpoint keeps its delegated call to report `organizationId` / `membershipCreated` deterministically in its response. Cloud-host semantics (personal-org hook precedence, multi-org non-binding, D5 blast radius) verified against `objectstack-ai/cloud` — see D2/D3/D5.

0 commit comments

Comments
 (0)