Skip to content

Commit 983abd9

Browse files
fix(plugin-security)!: a delegated answer about a user the caller cannot read does not depend on that user's existence or memberships (#31556)
Clause-②: no (narrowing) — the delegated-administration gate judges every target user through the caller's own read, so a user the caller cannot read is outside every delegated subtree: a delegated administrator no longer edits or removes a stored direct grant of such a user, and no longer explains such a user's access or reads its effective access. Nothing is widened: no export, error code or status is added. Metadata-protocol: none Skills-docs: updated here — `content/docs/permissions/delegated-administration.mdx` ("Explaining delegated decisions") states the rule; no `skills/**` file teaches delegated coverage of a target user. ## 维护者速读 - 改了什么:委派管理员(adminScope)对"它读不到的用户"的回答,不再取决于该用户是否存在、有没有业务单元成员关系。直接授权写入的目标用户(新建授权、把授权改指向他人、保留原持有人的编辑、删除已存授权)和两个说明入口(带 `userId` 的 explain、某用户的有效权限)都先按调用者自己的读权限判断,读不到就算在委派子树之外,与"不存在的用户"同一个答案。 - 为什么改:落实维护者 2026-11-08 的裁决「都同意」(选项 A):读不到的用户,在委派门判断目标用户的每一处都算子树外,一次性破坏性改动。属于安全加固,细节归 security#1 席。 - 风险与回滚:收窄(BREAKING,patch 级,不新增错误码或状态):委派管理员不能再编辑或删除它读不到的持有人的已存授权,也不能再说明或读取它读不到的用户的有效权限;租户级管理员与组织管理员两项都不受影响,能读到的目标照旧按业务单元判断。回滚 = revert 本 PR。 - 先看:① `packages/plugins/plugin-security/src/delegated-admin-gate.ts` 的 `judgesTargetUserThroughCallerRead`、`targetUserUnits`,以及 `assertDirectGrantWrite` 与 `scopesCoverUser` 里改用它的两处(风险 hunk);② `delegated-admin-own-name-set.posture.test.ts` 末尾新增的三形态 describe;③ `delegated-admin-gate.test.ts` 末尾的两个 describe。 - 两分钟验证:`pnpm --filter @objectstack/plugin-security exec vitest run --maxWorkers=2 src/delegated-admin-gate.test.ts src/delegated-admin-own-name-set.posture.test.ts`,预期 `Test Files 2 passed (2)`、`Tests 282 passed (282)`。 - 需要你做的:无,席位落地。 ## What changes - **Rule.** A delegated answer about a user the caller cannot read does not depend on that user's existence or memberships (ADR-0090 D12). Wherever the delegated-administration gate judges a target user, a user the caller's own read does not return is outside every delegated subtree, exactly as an id naming no user is. - **Where the gate judges a target user.** The direct-grant write gate (`sys_user_permission_set`): an insert, an update pointing a stored grant at another user, an update that leaves `user_id` as stored, and a removal. And the explain doors' delegated coverage (`DelegatedAdminGate.scopesCoverUser`), which `security/explain` with a `userId` and `security/users/:id/effective-access` share through `mayDescribeAnotherUser`. - **Answers.** The write door's refusal is the gate's existing scope violation for every such target: `403 DELEGATION_SCOPE_VIOLATION`, with the sentence and details every target outside the subtree gets. The explain doors answer the refusal of a user the caller may not describe (`403 PERMISSION_DENIED`; explain's carries `{ object, operation, targetUserId }`, the effective-access read's carries none), which is the answer an id naming no user gets. The `404` user-not-found stays reachable only by an admitted caller. - **Code.** One predicate and one helper serve both doors. `judgesTargetUserThroughCallerRead` holds when `sys_user` is registered and a `find` is available, the gate's own reason, never the schema shape of a grant's `user_id`. `targetUserUnits` asks the caller's own read under the caller's own context (`opCtx.context` at the write door, `callerContext` at the explain doors, never the system's), then the system's membership read. `namesTargetUser` and `referenceCheckAsksCallerAboutUser` lost their only caller and are deleted. What their docblocks recorded (the engine's reference check, the grant-holder membership hook's `callerReadsHolder`) moves into the predicate's docblock, together with why the "as stored" mirror does not hold for a door that judges. - **Order of checks.** In `scopesCoverUser` the caller's read runs only once `resolveHeldScopes` returns a scope, so a context that names no organization covers nobody and asks the read door nothing. At the write door the read sits where the membership read sat, inside `assertDirectGrantWrite`, which `authorize` reaches only for a caller with a resolved scope. - **Unchanged.** A readable target is judged on its business units as before. Tenant-level administrators and organization administrators keep both their writes and their explain coverage. `businessUnitsOfUser` keeps its system reads, and `delegatorAnchorSubtree`, which reads the caller's own memberships and judges no target user, is untouched. - **Docs.** `delegated-administration.mdx` ("Explaining delegated decisions") states the rule. The `mayDescribeAnotherUser` and `describeEffectiveAccess` docblocks state it too; no code in those two files changes. ### Rulings - The maintainer's ruling for this change, 2026-11-08, on the seat's recommendation of option A (a user the caller cannot read counts as outside the delegated subtree, everywhere the delegated gate judges a target user, in one breaking change): > 都同意 - Ruling on #26059, record `6416233738`, Q3, which the refusal class follows (the gate's own scope-violation code): > 3. server p2 — item 3, server half: the delegated-admin gate (`delegated-admin-gate.ts:403–503`, reasons `:1136–1179`) answers its own code (e.g. `DELEGATION_SCOPE_VIOLATION`, status 403, ADR-0112 ledger row), distinct from `PERMISSION_DENIED`. - Every ruling-of-record docblock in `delegated-admin-gate.ts` is kept (`6228728551`, `5985885287`, `6649064874`, `6663849489`). The two this diff edits around are `[ADR-0090 D12; ruling on #26059, Q3]` on the subtree test in `assertDirectGrantWrite`, whose sentence now names a user the caller cannot read, named or stored, and the same tag on the two new helpers. ## Tests - **Fake engine** (`delegated-admin-gate.test.ts`). Four target states (an id naming no user; a user with no business-unit membership; a user whose unit is outside the subtree; a user with a unit inside the subtree whom the caller cannot read) answer one identical refusal (class, name, code, status, statusCode, message, details and the `mapDataError` envelope) on all four write shapes. The CONTROL, the same target inside the subtree and read by the caller, is admitted on every shape. The answer does not change with the grant's `user_id` column (a read-only lookup, a text column, none). The caller's read runs under the write's own context. A tenant-level administrator's removal is admitted and asks the read nothing. For the explain coverage: the four states are covered by no scope, the CONTROL is, the read runs under the caller's own context, and a context naming no organization covers nobody and asks the read door nothing. - **Three postures** (`delegated-admin-own-name-set.posture.test.ts`, single, group and isolated, real `ObjectQL` over SQLite with the real `SecurityPlugin`). One subject id in the four states, asked at six doors: the four direct-grant shapes through `delegatedAdminGate.assert`, `explainAccessForCaller` with `userId`, and `describeEffectiveAccess`. Every state's six answers equal the no-user state's, which are the scope violation at the write shapes and `403 PERMISSION_DENIED` at both explain doors. A ground-truth pin shows which states the delegate reads. The CONTROL is served at all six doors. Second CONTROL: a tenant-level administrator and the organization administrator each remove the stored grant of the subject the delegate cannot read through the write door, and the row is gone. - **Ablation**, one guard at a time, reverted on disk with `scripts/ablation-replace.mjs` and restored (blob equal to `HEAD`, `git diff HEAD` empty): - write door (`targetUserUnits` replaced by the membership read in `assertDirectGrantWrite`): **9 red** (6 fake-engine, 3 postures), then restored; - explain coverage (the same replacement in `scopesCoverUser`): **5 red** (2 fake-engine, 3 postures), then restored. ## Acceptance notes - Open draft #31443 also edits `delegated-admin-gate.ts`: it inserts a module-level function directly below the two helpers this PR deletes. A three-way merge of the two heads is clean in both directions, and the two changes do not overlap in meaning. Draft #31511 touches an unrelated plugin-security test file. - `test:repo` (the vitest `repo` project) is not run locally; the diff touches none of its tests and the derived list does not name it. `Test Core` runs it. ## Verification Every reading below was taken on head `e5738c2609` (`git rev-parse --short HEAD`), the merge of `origin/main` at `a3ac7fb380` included. - `pnpm --filter @objectstack/plugin-security test`: `Test Files 250 passed (250)`, `Tests 5924 passed | 45 skipped (5969)`; lock VERDICT command-exit 0. - `pnpm --filter @objectstack/plugin-security typecheck`: exit 0 (`check:test-typecheck: OK`, 0 ledgered files). - Dogfood battery, `pnpm --filter @objectstack/dogfood test` after `pnpm turbo run build --filter=@objectstack/dogfood --concurrency=2` (no shard, no path): `Test Files 440 passed | 3 skipped (443)`, `Tests 3633 passed | 41 skipped (3674)`; lock VERDICT command-exit 0. - `dispatch-gates --commands` derived 98 families from the 7 changed paths; all 98 run on this head, every one exit 0; `dispatch-gates --ran`: `98 derived, 98 run, 0 NOT-MEASURED, 0 UNRUN` (a derived zero: all 98 recorded an exit code). - Ablation (see Tests): write-door guard reverted, 9 red; explain-coverage guard reverted, 5 red; each restored with blob equal to `HEAD`. <details> <summary>The 98 derived gate commands and their exit codes</summary> - `node scripts/check-adr-0087-registration.mjs --base origin/main` :: exit 0 - `node scripts/check-adr-0087-registration.mjs --self-test` :: exit 0 - `node scripts/check-adr-links.mjs` :: exit 0 - `node scripts/check-adr-links.mjs --self-test` :: exit 0 - `node scripts/check-changeset-no-major.mjs --base origin/main` :: exit 0 - `node scripts/check-closing-keyword-parity.mjs` :: exit 0 - `node scripts/check-closing-keyword-parity.mjs --self-test` :: exit 0 - `node scripts/check-comment-mask-adoption.mjs` :: exit 0 - `node scripts/check-comment-mask-adoption.mjs --self-test` :: exit 0 - `node scripts/check-comment-mask-corpus.mjs` :: exit 0 - `node scripts/check-doc-route-spelling.mjs --advisory` :: exit 0 - `node scripts/check-doc-route-spelling.mjs --self-test` :: exit 0 - `node scripts/check-docs-section-name.mjs` :: exit 0 - `node scripts/check-docs-section-name.mjs --self-test` :: exit 0 - `node scripts/check-dts-emitted.mjs --self-test` :: exit 0 - `node scripts/check-empty-changeset.mjs --base origin/main` :: exit 0 - `node scripts/check-empty-changeset.mjs --self-test` :: exit 0 - `node scripts/check-issue-citations.mjs` :: exit 0 - `node scripts/check-plugin-teardown-shape.mjs` :: exit 0 - `node scripts/check-plugin-teardown-shape.mjs --self-test` :: exit 0 - `node scripts/check-section-landing-index.mjs` :: exit 0 - `node scripts/check-section-landing-index.mjs --self-test` :: exit 0 - `node scripts/check-tenant-audit-census.mjs` :: exit 0 - `node scripts/check-tenant-audit-census.mjs --self-test` :: exit 0 - `node scripts/ci/assert-turbo-remote-cache.mjs --self-test` :: exit 0 - `node scripts/ci/plan-test-core-shards.mjs --self-test` :: exit 0 - `node scripts/ci/prune-turbo-cache.mjs --self-test` :: exit 0 - `node scripts/ci/snapshot-next.mjs --self-test` :: exit 0 - `node scripts/docs-audit/check-affected-docs.mjs` :: exit 0 - `node scripts/docs-audit/check-drift-comment.mjs` :: exit 0 - `node scripts/pm/release-rehearsal-clone.mjs --self-test` :: exit 0 - `node scripts/release-pending-publish.mjs --self-test` :: exit 0 - `pnpm --filter @objectstack/lint run check:doc-formula-expressions` :: exit 0 - `pnpm --filter @objectstack/lint run check:doc-security-posture` :: exit 0 - `pnpm --filter @objectstack/spec run check:docs` :: exit 0 - `pnpm --filter @objectstack/spec run check:duration-unit-keys` :: exit 0 - `pnpm --filter @objectstack/spec run check:empty-state` :: exit 0 - `pnpm --filter @objectstack/spec run check:liveness` :: exit 0 - `pnpm --filter @objectstack/spec run check:skill-examples` :: exit 0 - `pnpm --filter @objectstack/spec run check:strictness-ledger` :: exit 0 - `pnpm --filter @objectstack/spec run check:variant-docs` :: exit 0 - `pnpm --filter @objectstack/spec run check:yaml-examples` :: exit 0 - `pnpm check:adr-symbol-anchors` :: exit 0 - `pnpm check:authz-resolver` :: exit 0 - `pnpm check:changeset-gate-self-tests` :: exit 0 - `pnpm check:ci-filter-parity` :: exit 0 - `pnpm check:closed-ceremony-text` :: exit 0 - `pnpm check:corpus-claim-drift` :: exit 0 - `pnpm check:cross-package-test-inputs` :: exit 0 - `pnpm check:doc-anchors` :: exit 0 - `pnpm check:doc-authoring` :: exit 0 - `pnpm check:doc-frontmatter` :: exit 0 - `pnpm check:docs-audit-scope` :: exit 0 - `pnpm check:docs-redirects` :: exit 0 - `pnpm check:docs-single-h1` :: exit 0 - `pnpm check:docs-spec-enumerations` :: exit 0 - `pnpm check:docs-transcript-drift` :: exit 0 - `pnpm check:driver-memory-census` :: exit 0 - `pnpm check:dts-closure` :: exit 0 - `pnpm check:dual-build-cjs-loads` :: exit 0 - `pnpm check:engine-double-contract` :: exit 0 - `pnpm check:gitlink-declared` :: exit 0 - `pnpm check:i18n` :: exit 0 - `pnpm check:i18n-stale-fill` :: exit 0 - `pnpm check:issue-citations` :: exit 0 - `pnpm check:keyed-text-bounds` :: exit 0 - `pnpm check:lean-entry-closure` :: exit 0 - `pnpm check:logger-receiver-detach` :: exit 0 - `pnpm check:merge-driver` :: exit 0 - `pnpm check:nul-bytes` :: exit 0 - `pnpm check:object-def-param-keys` :: exit 0 - `pnpm check:objectql-double-limit` :: exit 0 - `pnpm check:optional-error-sink` :: exit 0 - `pnpm check:org-identifier` :: exit 0 - `pnpm check:page-declaration-shape` :: exit 0 - `pnpm check:platform-object-tenancy-census` :: exit 0 - `pnpm check:published-files` :: exit 0 - `pnpm check:published-readme-exports` :: exit 0 - `pnpm check:published-readme-links` :: exit 0 - `pnpm check:query-options-erasure` :: exit 0 - `pnpm check:react-page-adapter-contract` :: exit 0 - `pnpm check:refd-timer-probe` :: exit 0 - `pnpm check:registry-log-declared` :: exit 0 - `pnpm check:rest-log-spy-declared` :: exit 0 - `pnpm check:role-word` :: exit 0 - `pnpm check:skill-identifier-liveness` :: exit 0 - `pnpm check:slot-lookup` :: exit 0 - `pnpm check:sourcemap-no-sources-content` :: exit 0 - `pnpm check:system-context-census` :: exit 0 - `pnpm check:test-source-alias` :: exit 0 - `pnpm check:tier-file-adoption` :: exit 0 - `pnpm check:type-check-coverage` :: exit 0 - `pnpm check:type-check-debt` :: exit 0 - `pnpm check:undeclared-dep-imports` :: exit 0 - `pnpm check:vendor-version-stamps` :: exit 0 - `pnpm check:vouch-for-reference-callers` :: exit 0 - `pnpm check:watch-hint-literal` :: exit 0 - `pnpm check:where-matcher` :: exit 0 </details> <details> <summary>Ablation readings</summary> - Write door: anchor `await this.targetUserUnits(opCtx.context, targetUserId)` x1 to x0, blob `9e9aea0388cc` to `cb48799e44a2`; `Tests 9 failed | 273 passed (282)` over the two pin files; restored, blob `9e9aea0388cc` equal to `HEAD`, `git diff HEAD` empty. - Explain coverage: anchor `const userBUs = await this.targetUserUnits(callerContext, targetUserId);` x1 to x0, blob `9e9aea0388cc` to `0fa2d24bf0c9`; `Tests 5 failed | 277 passed (282)`; restored, blob equal to `HEAD`, `git diff HEAD` empty. </details> <!-- signed: security#1 · sunhaolin · session_017xRBcT1w3zpekijraHJE4f --> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2c6b936 commit 983abd9

7 files changed

Lines changed: 452 additions & 160 deletions
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@objectstack/plugin-security': patch
3+
---
4+
5+
fix(plugin-security)!: a delegated answer about a user the caller cannot read does not depend on that user's existence or memberships
6+
7+
Clause-②: no (narrowing) — the delegated-administration gate judges every target user through the caller's own read, so a user the caller cannot read is outside every delegated subtree: a delegated administrator no longer edits or removes a stored direct grant of such a user, and no longer explains such a user's access or reads its effective access. Nothing is widened: no export, error code or status is added.
8+
Metadata-protocol: none
9+
10+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no export of the package entry changes: an adminScope and a direct grant keep their shape and meaning, and a target user is judged through the caller's own read. There is nothing for a migration to rewrite and no tombstone. -->
11+
12+
**BREAKING** accept-set narrowing in the delegated-administration gate (`@objectstack/plugin-security`), only for a delegated administrator asking about a user it cannot read.
13+
14+
- **Rule.** A delegated answer about a user the caller cannot read does not depend on that user's existence or memberships (ADR-0090 D12). Wherever the gate judges a target user, such a user is outside every delegated subtree, exactly as an id naming no user is: the holder a direct grant names (a new grant, or a stored grant pointed at another user), the holder a stored grant keeps (its removal, or an edit that leaves `user_id` as stored), and the user the explain doors ask about.
15+
- **What a caller sees.** A delegated direct-grant write whose target user the caller cannot read answers `403 DELEGATION_SCOPE_VIOLATION`, with the sentence and details of every target outside the subtree. `security/explain` with a `userId`, and `security/users/:id/effective-access`, answer a delegate asking about a user it cannot read with their refusal of a user the caller may not describe (`403 PERMISSION_DENIED`), the answer an id naming no user gets.
16+
- **Unchanged.** A target user the caller reads is judged as before, on its business units. A tenant-level administrator's writes, and an organization administrator's writes and explain coverage, are judged as before.
17+
- **Who moves.** A delegate whose stored grant's holder it cannot read can no longer edit or remove that grant, and a delegate can no longer explain, or read the effective access of, a user it cannot read. Tenant-level and organization administrators keep both: either still removes such a grant, and explains such a user, as before.

‎content/docs/permissions/delegated-administration.mdx‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,15 @@ fact. Capability bits are never BU-scoped.
102102

103103
The [explain engine](/docs/permissions/explain) closes the loop twice:
104104

105-
- explaining **another user** is authorized by `manage_users` *or* a delegated
106-
`adminScope` whose subtree covers that user — a delegate can diagnose their
107-
own people, and only their own people;
105+
- explaining **another user** — and reading that user's effective access — is
106+
authorized by `manage_users`, organization administration of an
107+
organization that user is a member of, *or* a delegated `adminScope` whose
108+
subtree covers that user — a delegate can diagnose their own people, and
109+
only their own people. A scope covers a user the delegate can read, through
110+
a business unit of the subtree; a user it cannot read is covered by no
111+
scope, so the answer about that user does not depend on whether it exists
112+
or what it is a member of. The direct-grant write gate judges its target
113+
user the same way, a stored grant's holder included;
108114
- contributor attribution plus the `granted_by` stamp answer both *who
109115
granted this* and *who could have*.
110116

0 commit comments

Comments
 (0)