Skip to content

Commit 8e2d56d

Browse files
docs(spec): manage_connector_connections comments name the organization administrators' default grant (#28460)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoLXAkT8qKBzZ1B3UVHJPkjN)_ Fixes #28453 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`packages/spec` 里三处注释改为如实写明:平台管理员与两个组织管理员权限集(`organization_admin`、`organization_admin_no_bypass`)默认持有 `manage_connector_connections`,其它岗位仍需显式授予。只改注释,不改任何代码、能力清单或测试断言。 - 为什么改:#28441(裁决 B,记录 6545223261)已让组织管理员默认持有该能力,旧注释仍说"组织管理员也要显式授予",会让读 spec 的作者和 AI 多加一条重复授权,或误告客户管理员没有这项权利。 - 风险与回滚:零运行时风险;去注释后的 TypeScript 输出与 main 逐文件相同(见 Verification)。回滚即 revert。 - 先看:`packages/spec/src/security/capabilities.ts` 的 `manage_connector_connections` 注释;`packages/spec/src/identity/platform-admin-capabilities.test.ts` 改指向的 pin;`packages/spec/src/identity/eval-user.zod.ts`。 - 两分钟验证:`git grep -n "organization administrator included" -- packages/spec`,预期无命中。 - 需要你做的:无,席位落地。 ## What changes Three comments, reworded to what #28441 ships (ruling B, record 6545223261): platform administrators and the two shipped organization-administrator sets, `organization_admin` and `organization_admin_no_bypass`, hold `manage_connector_connections` by default, and every other position holds it only by explicit grant. - `packages/spec/src/security/capabilities.ts`: the `PLATFORM_CAPABILITIES` row's line comment. - `packages/spec/src/identity/eval-user.zod.ts`: the line comment above the entry in `ADMIN_FULL_ACCESS_CAPABILITIES.systemPermissions`. - `packages/spec/src/identity/platform-admin-capabilities.test.ts`: the case comment now says the organization-administrator sets hold it, and points at the pin #28441 added in plugin-security's `default-permission-sets.test.ts`, the case `[ADR-0143 D5] the connector connection capability ships with the platform administrator and both organization-administrator sets, and no other`, which asserts the exact holder list. No code, capability list or test assertion changes. **Contract review:** none owed. No `.describe()` and no exported TSDoc moved: all three edits are `//` line comments inside initializers, not declaration docblocks. **Changeset:** none (label `skip-changeset`). Measured after `pnpm --filter @objectstack/spec build` on 4f75d57: the new wording is absent from every `dist/**/*.d.ts` / `.d.mts` file (control: the capability's `description` string is found in dist). The bundler does carry the line comments into the `dist` JS chunks, so the comment bytes there change; no symbol, value or type does. **Grep:** `git grep -n "manage_connector_connections" -- packages/spec skills content/docs` after the edit shows no other spec sentence that contradicts the default grant. Hits outside `packages/spec`: `content/docs/automation/connectors.mdx:535` already says organization administrators hold it by default (updated in #28441); no hit in `skills/`. ## Tests `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/identity/platform-admin-capabilities.test.ts` on 4f75d57: `Test Files 1 passed (1)`, `Tests 6 passed (6)`. No ablation: no tested behaviour moved. ## Acceptance notes - Branch `claude/project-thread-1t227a` is the card thread's platform-assigned branch; claim 6546643088 names it. - `content/docs/permissions/permission-sets.mdx` (the `organization_admin` summary row) was already judged out of scope in #28441's notes, since that row lists a subset of capabilities; not touched here. ## Verification <details><summary>Comment-only proof</summary> TypeScript `createPrinter({ removeComments: true })` output of each changed file, `origin/main` (776c1d8) against HEAD (4f75d57): `capabilities.ts EQUAL`, `eval-user.zod.ts EQUAL`, `platform-admin-capabilities.test.ts EQUAL`. </details> <details><summary>Derived gates on 4f75d57</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 73 families from the 3-file diff. Each ran with stdin from `/dev/null`, exit captured by redirect before any pipe. All 73 exit 0. Three (`check:doc-formula-expressions`, `check:dual-build-cjs-loads`, `check:lean-entry-closure`) first exited 3, PREREQUISITE NOT MET, and were re-run after a whole-tree `pnpm turbo run build --filter='!@objectstack/docs' --concurrency=2` (lock VERDICT command-exit 0). `--ran`: `73 derived famil(ies) accounted for — 73 run, 0 NOT-MEASURED`, exit 0. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01L9qibyawL9DFnt7gutTH6R)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent bede9de commit 8e2d56d

3 files changed

Lines changed: 16 additions & 9 deletions

File tree

‎packages/spec/src/identity/eval-user.zod.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,9 @@ export const ADMIN_FULL_ACCESS_CAPABILITIES: Pick<PermissionSet, 'objects' | 'sy
165165
'manage_mailboxes',
166166
// [ADR-0143 D5] The connector connection capability: its holder connects,
167167
// reconnects and revokes its organization's OAuth2 connector connections.
168-
// Platform administrators hold it by default; every other position, the
169-
// organization administrator included, only by explicit grant.
168+
// Platform administrators hold it by default, and so do organization
169+
// administrators (ruling B, record 6545223261); every other position only
170+
// by explicit grant.
170171
'manage_connector_connections',
171172
],
172173
};

‎packages/spec/src/identity/platform-admin-capabilities.test.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,13 @@ describe('ADMIN_FULL_ACCESS_CAPABILITIES — the one platform-admin list plugin-
5050
});
5151

5252
it('carries the connector connection capability, declared org-scoped (ADR-0143 D5)', () => {
53-
// Platform administrators hold it by default through this grant; the
54-
// organization administrator's shipped sets withhold it, pinned on the
55-
// seeded sets in plugin-security's `default-permission-sets.test.ts`.
53+
// Platform administrators hold it by default through this grant. The two
54+
// organization-administrator sets hold it by default too (ruling B, record
55+
// 6545223261), and every other shipped set withholds it: the exact holder
56+
// list is pinned by the `[ADR-0143 D5] the connector connection capability
57+
// ships with the platform administrator and both organization-administrator
58+
// sets, and no other` case in plugin-security's
59+
// `default-permission-sets.test.ts`.
5660
expect(ADMIN_FULL_ACCESS_CAPABILITIES.systemPermissions).toContain('manage_connector_connections');
5761
expect(PLATFORM_CAPABILITIES.find((c) => c.name === 'manage_connector_connections')?.scope).toBe('org');
5862
});

‎packages/spec/src/security/capabilities.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,12 @@ export const PLATFORM_CAPABILITIES: readonly PlatformCapability[] = [
104104
// (`/automation/connectors/:name/connection` and the OAuth callback, in
105105
// `@objectstack/runtime`) asks this capability and nothing else — never the
106106
// platform-scoped `manage_metadata`. Held by default by platform
107-
// administrators (`ADMIN_FULL_ACCESS_CAPABILITIES`); every other position,
108-
// the organization administrator included, only by explicit grant. `org`:
109-
// the door acts on the caller's own organization's connection, and the
110-
// holder never sees a token.
107+
// administrators (`ADMIN_FULL_ACCESS_CAPABILITIES`) and by organization
108+
// administrators (the shipped `organization_admin` and
109+
// `organization_admin_no_bypass` sets, ruling B, record 6545223261); every
110+
// other position only by explicit grant. `org`: the door acts on the
111+
// caller's own organization's connection, and the holder never sees a
112+
// token.
111113
{ name: 'manage_connector_connections', label: 'Manage Connector Connections', description: 'Connect, reconnect and revoke the holder’s organization’s connection of an OAuth2 connector instance, and read its status. A connection authorizes the platform to call the vendor on the organization’s behalf; no token is ever shown to the holder.', scope: 'org' },
112114
];
113115

0 commit comments

Comments
 (0)