Repository navigation
Commit 983abd9
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
File tree
- .changeset
- content/docs/permissions
- packages/plugins/plugin-security/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
102 | 102 | | |
103 | 103 | | |
104 | 104 | | |
105 | | - | |
106 | | - | |
107 | | - | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
108 | 114 | | |
109 | 115 | | |
110 | 116 | | |
| |||
0 commit comments