Repository navigation
Commit 2ecf6a7
fix(plugin-audit)!: serve the ledger’s deployment-level rows to the platform administrator alone, in every posture (#28047)
<!-- claude-projects-attribution: {"github_login":"os-elon-musk"} -->
_Requested by **Elon** · [project
thread](https://claude.ai/code/project/chan_01WedDzV26nniwxv7jC88B9D?thread=cmsg_01WedDzV26nniwxv7jC88B9DUkDtugva69s3nUwLDmAzKf)_
Fixes #26750
Clause-②: no (narrowing)
Metadata-protocol: none
Skills-docs: updated here
## 维护者速读
- **改了什么**:合规审计账本里不属于任何组织的部署级记录(`tenant_id`
为空:全局设置变更、用户导入、平台管理员身份变更、管理员建号与重置密码),在所有租户姿态下(含
`single`)只给平台管理员看;其他读者,包括 `view_all_audit_log` 的持有者,只看属于某个组织的记录。
- **为什么改**:落实 #26750 的裁决 A。`single` 姿态下组织行策略被剥离,任何拿到账本读权的人都能读到部署级记录。
- **风险与回滚**:读范围收窄(BREAKING)。`single`
部署里自建的审计角色和组织管理员将看不到部署配置历史;记录仍在库,系统上下文的导出不受影响。回滚即 revert 本 PR,无数据迁移。
-
**先看**:`packages/plugins/plugin-audit/src/audit-log-read-visibility.ts`(中间件末尾新增的一行规则与
`readsDeploymentLevelLedgerRows`)、`packages/plugins/plugin-audit/src/audit-log-deployment-level-rows.integration.test.ts`、`packages/qa/dogfood/test/admin-ledger-decision-metadata.dogfood.test.ts`(按裁决翻转的钉子)。
- **两分钟验证**:`pnpm --filter @objectstack/plugin-audit exec vitest run
src/audit-log-deployment-level-rows.integration.test.ts`,预期 `single` /
`group` / `isolated` 三个姿态共 18 条全绿。
- **需要你做的**:无,席位落地。
## What changes
- **The read rule**
(`packages/plugins/plugin-audit/src/audit-log-read-visibility.ts`). On
every non-system engine read of `sys_audit_log` (find, findOne, count,
aggregate), a reader that is not the platform administrator gets one
more clause ANDed into its `where`: `tenant_id` is neither null nor
empty. It is added after the parent-record gate, which plans its parents
off the read's own `where`, and it reaches the holder of
`view_all_audit_log` too, whom that gate exempts. The platform
administrator is the carried `PLATFORM_ADMIN` posture rung
(`PLATFORM_OPERATOR_POSTURE`, ADR-0095 D2/D3), which the unscoped
`admin_full_access` grant derives. Positions, set names and capabilities
are not read, and a context with no rung gets the clause. Writes,
system-context reads and context-less programmatic reads are untouched.
Which organization's rows an organization reader is served stays the row
policy's answer (ADR-0131 D8). The module is not re-exported, so the
package's public surface is unchanged.
- **The capability text**
(`packages/spec/src/security/capabilities.ts`). The `view_all_audit_log`
description gains one sentence for `single`. Nothing else in
`packages/spec` changes.
- **Docs.** One sentence in
`content/docs/permissions/record-view-auditing.mdx`.
- **Changeset** `.changeset/26750-ledger-deployment-level-rows.md`:
patch for both packages, the two declaration lines, a BREAKING banner,
and an upgrade note for `single` operators who granted the ledger to
someone who is not the platform administrator.
## Why
Ruling A on #26750 (comment 6457448424): deployment-level ledger rows
(no `tenant_id`, ADR-0131 D7) are served only to the platform
administrator in every tenancy posture, `single` included, and an
organization-scoped holder of `view_all_audit_log` reads only the rows
about its organization(s). Under `single` the shipped row policy
`sys_audit_log_org` is stripped (a platform tenant policy by provenance,
ADR-0105 D3), so every reader with a ledger grant was served those rows.
On the ruling's "its superuser read bypass": the bypass
(`viewAllRecords`) skips plugin-security's Layer 1 only and never
reaches this plugin's read middleware. So the rule reads the carried
rung that names the platform administrator, and no new capability is
introduced.
## Tests
- `audit-log-read-visibility.test.ts` (unit):
- the clause's shape, and a fresh tree per call;
- the rung-only predicate: `TENANT_ADMIN`, `MEMBER`, `EXTERNAL`, a
mis-cased rung, no rung, `platform_admin` as a position, and
`admin_full_access` as a permission or a capability all answer false;
- a non-holder gets the gate, then the clause;
- a holder on every non-admin rung gets the clause alone, on find,
findOne, count and aggregate;
- the platform administrator, with or without the capability, gets no
clause;
- writes, system reads and context-less reads get none.
- `audit-log-read-visibility.integration.test.ts`: the fixture rows now
carry the tenant each real writer stamps. A new case serves the
deployment-level rows to the platform administrator alone; the member,
the other member, the organization admin and the holder are served none.
- `audit-log-deployment-level-rows.integration.test.ts` (new): one boot
per posture (`single`, `group`, `isolated`) with the real CRUD mirror.
The organization holder and the organization admin are served their
organization's rows and no deployment-level row, through find, count, a
`tenant_id: null` filter, findOne by id and a grouped aggregate. The
platform administrator is served both.
- The dogfood pin sweep. Both files were named to the seat and added to
the claim's file surface before they were edited.
- `audit-log-audit-capability.dogfood.test.ts`: the broad read's bulk
rows were system inserts with no `tenant_id`, which made them
deployment-level rows. They now carry the holder's organization, as the
CRUD mirror stamps a row about a record of it. The test's subject is
unchanged.
- `admin-ledger-decision-metadata.dogfood.test.ts`: **a pin flip caused
by ruling 6457448424, not a fix-to-green.** Every row about the subject
(plugin-auth's explicit rows and the mirror's rows, written by the
platform administrator's endpoints with no organization) is
deployment-level, so no class reader can be served one in any posture.
The decisions-only guarantee is now asserted at the producer, on the
rows at rest. The read side pins the ruling: every reader is served only
a control row about the same subject that carries the readers'
organization, and the platform administrator is served every row. The
armed checks keep their shape: the rows exist and the mirror carries
every class; every reader opens the subject; no row about the subject
carries an organization, and every reader is served the control row.
- Two plugin-audit fixtures the full package suite found (inside the
claim's surface, "its tests under
`packages/plugins/plugin-audit/src/`"):
- `audit-log-field-redaction.test.ts`: the rows from other writers were
system inserts with no `tenant_id`, so the organization readers there
were no longer served them. They carry the Default Organization, as a
tenant-scope writer stamps them. The redaction cases are unchanged.
- `parent-record-read-leaf.integration.test.ts`: the rows about no
record carry the Default Organization the same way. The observer that
records each ledger read's WHERE "as the gates left it" takes the
deployment-level clause, ANDed after the gate, off what it records, so
the gate's own WHERE is still what is measured. The holder's case now
also pins that the clause is there.
## Acceptance notes
- **Measurement (the card's first step).** Under `group` and `isolated`,
a custom set that grants the ledger read and `view_all_audit_log` and
omits `sys_audit_log_org` was measured on a real boot before the change.
Its holder was served only its own organization's rows, so that set has
no NULL-tenant leak to fix.
- **The cross-organization half is outside this card.** The same
measurement found that under a wall, a custom set that authors its own
ledger row policy, or that grants the read bypass on the ledger, is
served rows beyond its holder's organization. This change closes the
deployment-level half of that: those rows are now the platform
administrator's alone, in every posture. Rows about other organizations
stay reachable through such a set. No reproduction detail is given here;
the withheld detail stays on #26640.
- The ledger rows stay stored, and nothing is re-attributed (the ruling:
not B).
## Verification
Final head `af925f22`. It differs from `173abc30` only in the two
plugin-audit fixtures above, which no dogfood file runs.
<details><summary>Ablation 1: the rule line replaced by a marker, three
plugin-audit files: 20 red, restored</summary>
```text
node scripts/ablation-replace.mjs --file packages/plugins/plugin-audit/src/audit-log-read-visibility.ts \
--anchor 'if (!readsDeploymentLevelLedgerRows(ctx.context)) andIntoWhere(ctx, ledgerRowAboutAnOrganizationWhere());' \
--replacement '// ABLATION: the deployment-level rule removed' -- pnpm --filter @objectstack/plugin-audit exec vitest run \
src/audit-log-read-visibility.test.ts src/audit-log-read-visibility.integration.test.ts src/audit-log-deployment-level-rows.integration.test.ts
ablation-replace: ok mutation landed: anchor 1 -> 0, blob c49da4b -> f05a69cb34ea
Test Files 3 failed (3)
Tests 20 failed | 44 passed (64)
red (count × title):
3 × the organization holder of the audit capability is served its organization's rows, and no deployment-level row (single, group, isolated)
3 × the organization admin is served its organization's rows, and no deployment-level row (single, group, isolated)
3 × a read that asks for the deployment-level rows by name or by id is served none of them (single, group, isolated)
3 × a grouped count sees no deployment-level row (single, group, isolated)
1 × a caller without the audit capability gets the gate, then the clause ANDed after it
1 × an organization holder of the audit capability, on every rung but the platform administrator's, gets the clause alone
1 × its holder is not narrowed by the parent-record gate, on any read operation, and nothing is scanned for it
1 × [#26750] the deployment-level rows are served to the platform administrator alone
1 × [#21260] a holder of the ledger audit capability is served every row about the organization, deleted and unreadable records included
1 × find: a member reads the rows about records it can read and the organization's rows about no record, and nothing else
1 × aggregate: a grouped count sees only the readable rows
1 × an admin, who reads every record, keeps every row about a record that exists and the organization's rows about none
ablation-replace: ok restored: blob == HEAD (c49da4b) and `git diff HEAD` is empty
```
</details>
<details><summary>Ablation 2: the predicate also reads a
<code>platform_admin</code> position: the rung-only pin red,
restored</summary>
```text
--anchor 'return context?.posture === PLATFORM_OPERATOR_POSTURE;'
--replacement 'return context?.posture === PLATFORM_OPERATOR_POSTURE || ((context as any)?.positions ?? []).includes("platform_admin"); // ABLATION: positions read beside the rung'
Test Files 1 failed | 2 passed (3)
Tests 1 failed | 63 passed (64)
× the platform administrator is the carried PLATFORM_ADMIN rung, and nothing else
AssertionError: {"userId":"u1","positions":["platform_admin"]}: expected true to be false
ablation-replace: ok restored: blob == HEAD (c49da4b) and `git diff HEAD` is empty
```
</details>
<details><summary>Ablation 3: the rule removed, against the re-armed
leaf fixture: the holder's clause pin red, restored</summary>
```text
Test Files 1 failed | 1 passed (2)
Tests 1 failed | 32 passed (33)
× ledger: the audit capability's holder is not narrowed — the gate writes nothing for it
AssertionError: expected false to be true
ablation-replace: ok restored: blob == HEAD (c49da4b) and `git diff HEAD` is empty
```
</details>
<details><summary>Package suites (green), each under the verify
lock</summary>
```text
pnpm --filter @objectstack/plugin-audit test Test Files 66 passed (66) · Tests 1077 passed (1077)
pnpm --filter @objectstack/spec exec vitest run src/security src/identity Test Files 26 passed (26) · Tests 601 passed (601)
pnpm --filter @objectstack/plugin-security test Test Files 237 passed (237) · Tests 5119 passed | 45 skipped (5164)
plugin-auth: durability-swallow-repair + admin-user-endpoints Test Files 2 passed (2) · Tests 115 passed (115)
service-settings: config-change-audit Test Files 1 passed (1) · Tests 17 passed (17)
service-automation: resume-decider-identity + runas-attribution-contract Test Files 2 passed (2) · Tests 23 passed (23)
```
The neighbouring suites are the ones outside plugin-audit that boot the
audit plugin and read the ledger.
</details>
<details><summary>Full dogfood battery: red on the first head (the two
fixtures, named above), green after</summary>
```text
46f5ab6 · os-verify-lock: VERDICT command-exit 1 · held the lock 1175s
Test Files 2 failed | 355 passed | 3 skipped (360)
Tests 1 failed | 2866 passed | 28 skipped (2895)
audit-log-audit-capability.dogfood.test.ts:352 expected 2055, received 5 (the bulk rows carried no tenant_id)
admin-ledger-decision-metadata.dogfood.test.ts assertArmed disarmed (no reader served any row about the subject)
173abc3 · pnpm --filter @objectstack/dogfood test
os-verify-lock: VERDICT command-exit 0 · held the lock 1118s (18m38s) · waited 0s
Test Files 357 passed | 3 skipped (360)
Tests 2877 passed | 20 skipped (2897)
```
</details>
<details><summary>dispatch-gates: 106 derived families, run and
reconciled</summary>
```text
173abc3: node scripts/pm/dispatch-gates.mjs --ran gates-ran.txt
Run reconciliation — 106 derived, 106 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 106 derived famil(ies) accounted for — 106 run, 0 NOT-MEASURED (a DERIVED zero — all 106 recorded an exit code and none of them is 3).
every family exit 0
af925f2: the same 106 families (re-derived, identical list) are re-running; the reconciliation goes in the card's report comment.
```
Three families needed a prerequisite in this shallow cloud clone before
they measured: `check-plugin-teardown-shape --self-test` (the pinned
fixture commit fetched), `spec check:skill-examples` (client SDK
declarations built), `check:dual-build-cjs-loads` (six package builds).
</details>
<details><summary>Lint and generated artifacts</summary>
```text
pnpm lint exit 0
pnpm --filter @objectstack/spec run check:generated exit 0 · All 14 generated artifacts are up to date
node scripts/pm/check-governed-merges.mjs --branch … NOT governed · 0 of 9 paths hit the register
```
</details>
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(The only spec change is one sentence in a capability description.)
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (`check:generated`: all 14 up to date; no
artifact carries the description.)
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English. (The `维护者速读` block is
the fleet's one sanctioned Chinese section.)
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
Contract review is owed: the seat runs it on the final head.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_016WV4cwC9jjzyBACUnk1V9V
---
_Generated by [Claude
Code](https://claude.ai/code/session_016WV4cwC9jjzyBACUnk1V9V)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 5448585 commit 2ecf6a7
11 files changed
Lines changed: 567 additions & 119 deletions
File tree
- .changeset
- content/docs/permissions
- packages
- plugins/plugin-audit/src
- qa/dogfood/test
- spec/src/security
| 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 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
220 | 220 | | |
221 | 221 | | |
222 | 222 | | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
223 | 228 | | |
224 | 229 | | |
225 | 230 | | |
| |||
| 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 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
48 | 48 | | |
49 | 49 | | |
50 | 50 | | |
51 | | - | |
| 51 | + | |
52 | 52 | | |
53 | 53 | | |
54 | 54 | | |
| |||
186 | 186 | | |
187 | 187 | | |
188 | 188 | | |
189 | | - | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
190 | 193 | | |
191 | 194 | | |
192 | 195 | | |
| |||
196 | 199 | | |
197 | 200 | | |
198 | 201 | | |
199 | | - | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
200 | 207 | | |
201 | 208 | | |
202 | 209 | | |
| |||
0 commit comments