Skip to content

Commit e3f0aa4

Browse files
committed
docs(permissions): count the record-file verbs in the tenant-audit and system-context censuses (#30892)
The upload link's field write and the conditional spend are two engine write call sites (263, from 261), regenerated with `tenant-audit-census.mjs --write` and the page's hand-stated figures moved to match. Row 47e names the record-file verbs beside the attach verbs: both refuse the system context through a `requireUserContext`, so the row's key is now pinned per file. Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WV4cyqd3A7fbCWrqM3KCz
1 parent ebd0dbc commit e3f0aa4

3 files changed

Lines changed: 46 additions & 44 deletions

File tree

‎content/docs/permissions/system-context.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ One of the largest consumers of the flag;
186186
| 47b | The inbound-mail ingest seam: `ingest` admits the system context ALONE, and `rematch` admits it without the organization, owner or `manage_mailboxes` check | service-mailbox | Get: a mail source hands a mailbox its messages, and server code re-matches any mailbox. Lose: nothing a user held — every other caller of `ingest` is refused (`PERMISSION_DENIED`), because an ingested message is shown on every record its correspondents' addresses match and a user who could hand the seam a message could write one in a correspondent's name; every other caller of `rematch` must be in the mailbox's organization and own the mailbox or hold `manage_mailboxes` | `ingest`, `authorizeRematch` |
187187
| 47c | The inbound-mail IMAP sync: `syncMailbox` and `syncAll` admit the system context ALONE | service-mailbox | Get: the sync job reads every mailbox row (its organization, address and IMAP cursor), writes the cursor back, and hands each fetched message to `ingest` under the system context. Lose: nothing a user held — every other caller is refused (`PERMISSION_DENIED`), because a sync stores a mailbox's mail and moves its cursor | `syncMailbox`, `syncAll` |
188188
| 47d | The print service REFUSES the system context: `printRecordToFile` admits a human user acting for themselves alone | service-print | Get: nothing — a system caller is refused (`PERMISSION_DENIED`) before any page is read, session minted or browser started. Lose: nothing a user held — the PDF is rendered as the requesting user and never as the system, so a record is archived only by someone who could read it | `refuseUnlessHumanCaller` |
189-
| 47e | The caller-scoped attach verbs REFUSE the system context: `attachFileAs` and `assertMayAttach` admit a signed-in user alone | service-storage | Get: nothing — a system caller is refused (`PERMISSION_DENIED`); the system attaches through `attachFile`, whose rows name no user. Lose: nothing a user held — the caller-scoped verbs insert the attachment under the caller's context so every insert gate judges that user and both rows name them | `requireUserContext` |
189+
| 47e | The caller-scoped attach verbs REFUSE the system context: `attachFileAs` and `assertMayAttach` admit a signed-in user alone, and so do the caller-scoped record-file verbs the MCP `read_file` and `create_upload_link` tools call (`listRecordFilesAs`, `readRecordFileAs`, `createUploadLinkAs`) | service-storage | Get: nothing — a system caller is refused (`PERMISSION_DENIED`); the system attaches through `attachFile`, whose rows name no user. Lose: nothing a user held — the caller-scoped verbs insert the attachment under the caller's context so every insert gate judges that user and both rows name them, and the record-file verbs read the record and judge the file as that user, and bind an upload link to them | `packages/services/service-storage/src/file-attachment-service.ts#requireUserContext`, `packages/services/service-storage/src/record-file-access.ts#requireUserContext` |
190190
| 47f | The file-reference claim path asks no read verdict of a system write: a record write claims or copies a referenced file only as its caller may read it (the download door's verdict), and a system write carries no caller to ask | service-storage | Get: a system write claims or copies any file the organization-scoped lookup reaches, as before #25692; a deliberate server-side copy between records runs this way. Lose: nothing a user held — a user write is judged by the download door's verdict, and a context-less programmatic write is not asked either | `referencingCallerOf` |
191191
| 47g | The `sys_file` storage-owned columns guard returns early on create: a system insert keeps the `key`, `mime_type`, `size`, `status` and `etag` it writes | service-storage | Get: the storage service's own inserts (the upload doors, the field-file copy and backfill) write those five columns. Lose: nothing a user held — a non-system create has them dropped and starts `pending`, and on update the same columns are `readonly`, so the UPDATE `readonly` strip keeps them for every non-system caller | `installSysFileStorageOwnedColumnsGuard` |
192192

@@ -674,6 +674,7 @@ and CI refuses one that differs from what the tree produces.
674674
| `packages/services/service-storage/src/attachment-access-hooks.ts#installAttachmentReadVisibility` | 1 | 44 |
675675
| `packages/services/service-storage/src/file-attachment-service.ts#requireUserContext` | 1 | 47e |
676676
| `packages/services/service-storage/src/file-reference-lifecycle.ts#referencingCallerOf` | 1 | 47f |
677+
| `packages/services/service-storage/src/record-file-access.ts#requireUserContext` | 1 | 47e |
677678
| `packages/services/service-storage/src/sys-file-storage-owned-columns.ts#installSysFileStorageOwnedColumnsGuard` | 1 | 47g |
678679

679680
{/* END GENERATED: system-context-census */}

‎content/docs/permissions/tenant-audit-census.mdx‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ what moved this page's population from 225 to 227; nothing about the two sites
9393
changed, only whether this instrument could see them.
9494

9595
**The expensive failure direction is a keyword.** Sites whose receiver the author
96-
typed `any` have no type to read, and there are 62 of them — just over a fifth
96+
typed `any` have no type to read, and there are 63 of them — just over a fifth
9797
of the population, concentrated in exactly the seed and bootstrap paths this
9898
control exists for. Scoring an unreadable receiver as "not an engine" would have
9999
dropped every one of them silently, with a clean exit and a smaller number that
@@ -132,7 +132,7 @@ are reported as `undecidable` rather than assumed either way.
132132

133133
The same holds twice over for the context. An options argument spelled as a
134134
literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
135-
forwarding shim cannot, and **55 of the 261 sites are spelled that way**. A
135+
forwarding shim cannot, and **56 of the 263 sites are spelled that way**. A
136136
context resolved from an inline literal or a local `const` can be tested for
137137
`isSystem`; one arriving from a helper call cannot.
138138

@@ -160,8 +160,8 @@ now **0**: nothing on this surface threads a context that provably lacks the fla
160160

161161
**"No tenant context" counted sites it had not read.** An options argument the
162162
walker could not parse was folded into the same bucket as one it had read and
163-
found empty. That published **63 sites "carrying no tenant context at all"**
164-
when 8 said so and 55 were simply unread — an over-claim in the *alarming*
163+
found empty. That published **64 sites "carrying no tenant context at all"**
164+
when 8 said so and 56 were simply unread — an over-claim in the *alarming*
165165
direction, on the very figure this page tells other cards to cite. `carries` is
166166
now three-valued, and an unreadable argument can never contribute to the
167167
provable count.
@@ -197,10 +197,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
197197

198198
| carried figure | where it survives | this census |
199199
| :--- | :--- | ---: |
200-
| 175 write call sites | quoted in the merged changeset | **261** |
201-
| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **29** more whose options argument is unreadable |
202-
| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **184 of 261** decidable, **77** undecidable |
203-
| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 144 decidably elevated, 0 decidably not, 109 undecidable |
200+
| 175 write call sites | quoted in the merged changeset | **263** |
201+
| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **30** more whose options argument is unreadable |
202+
| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **185 of 263** decidable, **78** undecidable |
203+
| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 144 decidably elevated, 0 decidably not, 111 undecidable |
204204
| 141 and 132, two independent re-derivations | the card that filed this work | — |
205205

206206
**The differences are not reconciled, and deliberately so.** The old census's
@@ -210,21 +210,21 @@ be stated is what this instrument counts, which is written above and re-runnable
210210
at any commit.
211211

212212
Two structural facts do plausibly widen this reading against any hand or regex
213-
one, and both are counted in the generated tables below: the 62 sites reached
213+
one, and both are counted in the generated tables below: the 63 sites reached
214214
through an erased (`any`) receiver, and the 68 that name their object through a
215215
`const` rather than inline. An instrument that read either the way a person does
216216
would report a smaller number and would not say so.
217217

218218
The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
219219
figure has no surviving corroboration anywhere in the tree.** This census reads
220-
144 of 261 (55%) as decidably elevated, with 109 more whose elevation is a
220+
144 of 263 (55%) as decidably elevated, with 111 more whose elevation is a
221221
run-time fact — so the claim is neither confirmed nor refuted, and the honest
222222
answer is that a static reading cannot settle it.
223223

224-
⇒ **Cite `2 / 261`, and say what it is**: the sites whose options argument was
224+
⇒ **Cite `2 / 263`, and say what it is**: the sites whose options argument was
225225
READ and holds no tenant context, against a decidably tenancy-enabled object.
226226
That is the control's provable yield surface. ⛔ Do not cite it as "the sites
227-
without tenant context" — **29 further sites** have an options argument this
227+
without tenant context" — **30 further sites** have an options argument this
228228
cannot read, and they are neither in nor out.
229229

230230
{/* BEGIN GENERATED: tenant-audit-census (scripts/tenant-audit-census.mjs) — DO NOT EDIT */}
@@ -233,31 +233,31 @@ cannot read, and they are neither in nor out.
233233

234234
| what | count |
235235
| :--- | ---: |
236-
| write call sites on the application surface | **261** |
237-
| …whose object name is statically decidable | 184 |
238-
| …whose object name is chosen at run time | 77 |
239-
| …against an object with tenancy ENABLED | 178 |
236+
| write call sites on the application surface | **263** |
237+
| …whose object name is statically decidable | 185 |
238+
| …whose object name is chosen at run time | 78 |
239+
| …against an object with tenancy ENABLED | 179 |
240240
| …against an object that declares tenancy off | 6 |
241-
| threading a tenant context | 198 |
241+
| threading a tenant context | 199 |
242242
| PROVABLY carrying none (options read, no context key) | **8** |
243243
| …of those, against a decidably tenancy-enabled object | **2** |
244-
| options argument UNREADABLE — may or may not carry one | 55 |
245-
| …of those, against a decidably tenancy-enabled object | 29 |
244+
| options argument UNREADABLE — may or may not carry one | 56 |
245+
| …of those, against a decidably tenancy-enabled object | 30 |
246246
| threading a decidably ELEVATED (`isSystem`) context | 144 |
247247
| threading a context that is decidably NOT elevated | 0 |
248-
| threading a context whose elevation is a run-time fact | 109 |
248+
| threading a context whose elevation is a run-time fact | 111 |
249249

250250
| how the instrument reached the site | count |
251251
| :--- | ---: |
252-
| receiver carried a readable engine type | 199 |
253-
| receiver erased, placed by the object NAME | 52 |
252+
| receiver carried a readable engine type | 200 |
253+
| receiver erased, placed by the object NAME | 53 |
254254
| receiver erased, placed by an `object: string` PARAMETER | 5 |
255255
| receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
256256

257-
| object name spelled inline | 116 |
257+
| object name spelled inline | 117 |
258258
| object name spelled through a `const` | 68 |
259259
| object name is an `object: string` parameter | 7 |
260-
| object name is some other run-time expression | 70 |
260+
| object name is some other run-time expression | 71 |
261261

262262
### Subtractions the census could NOT defend — enforced
263263

@@ -307,13 +307,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
307307
their values are not compared. The reasoning, and the measurement behind it,
308308
are in `scripts/check-tenant-audit-census.mjs`.
309309

310-
Measured on 2026-11-05 at `e40e04854`.
310+
Measured on 2026-11-06 at `ebd0dbc44`.
311311

312312
| corpus scale (not enforced) | count |
313313
| :--- | ---: |
314-
| tracked non-test sources scanned | 871 |
315-
| engine-shaped types recognised | 105 |
316-
| declared objects in the registry | 127 |
317-
| same-named calls subtracted as non-engine | 229 |
314+
| tracked non-test sources scanned | 1035 |
315+
| engine-shaped types recognised | 111 |
316+
| declared objects in the registry | 130 |
317+
| same-named calls subtracted as non-engine | 232 |
318318

319319
{/* END GENERATED: tenant-audit-census */}

‎docs/audits/2026-08-tenant-audit-write-call-sites.counts.md‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -33,19 +33,19 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
3333

3434
| Measure | Value |
3535
|---|---:|
36-
| Write call sites | 261 |
37-
| Object name statically decidable | 184 |
38-
| Object name chosen at run time | 77 |
39-
| Against a tenancy-enabled object | 178 |
36+
| Write call sites | 263 |
37+
| Object name statically decidable | 185 |
38+
| Object name chosen at run time | 78 |
39+
| Against a tenancy-enabled object | 179 |
4040
| Against an object declaring tenancy off | 6 |
41-
| Threading a tenant context | 198 |
41+
| Threading a tenant context | 199 |
4242
| Provably carrying none | 8 |
4343
| …and decidably tenancy-enabled | 2 |
44-
| Options argument unreadable | 55 |
45-
| …and decidably tenancy-enabled | 29 |
44+
| Options argument unreadable | 56 |
45+
| …and decidably tenancy-enabled | 30 |
4646
| Threading a decidably elevated context | 144 |
4747
| Threading a decidably non-elevated context | 0 |
48-
| Threading a context of undecidable elevation | 109 |
48+
| Threading a context of undecidable elevation | 111 |
4949

5050
## Subtractions the census could NOT defend — enforced
5151

@@ -90,14 +90,14 @@ holds still. They are required to be HERE and to say WHEN they were true;
9090
their values are not compared. The reasoning, and the measurement behind it,
9191
are in `scripts/check-tenant-audit-census.mjs`.
9292

93-
Measured on 2026-11-05 at `e40e04854`.
93+
Measured on 2026-11-06 at `ebd0dbc44`.
9494

9595
| corpus scale (not enforced) | count |
9696
| :--- | ---: |
97-
| tracked non-test sources scanned | 871 |
98-
| engine-shaped types recognised | 105 |
99-
| declared objects in the registry | 127 |
100-
| same-named calls subtracted as non-engine | 229 |
97+
| tracked non-test sources scanned | 1035 |
98+
| engine-shaped types recognised | 111 |
99+
| declared objects in the registry | 130 |
100+
| same-named calls subtracted as non-engine | 232 |
101101

102102
## Every site
103103

@@ -271,7 +271,8 @@ Measured on 2026-11-05 at `e40e04854`.
271271
| `packages/services/service-storage/src/file-reference-lifecycle.ts` | `update` | `sys_file` | enabled | elevated | 2 |
272272
| `packages/services/service-storage/src/metadata-store.ts` | `delete` | `sys_file` | enabled | options unreadable | 1 |
273273
| `packages/services/service-storage/src/metadata-store.ts` | `insert` | `sys_file` | enabled | options unreadable | 1 |
274-
| `packages/services/service-storage/src/metadata-store.ts` | `update` | `sys_file` | enabled | options unreadable | 1 |
274+
| `packages/services/service-storage/src/metadata-store.ts` | `update` | `sys_file` | enabled | options unreadable | 2 |
275275
| `packages/services/service-storage/src/metadata-store.ts` | `delete` | `sys_upload_session` | enabled | options unreadable | 1 |
276276
| `packages/services/service-storage/src/metadata-store.ts` | `insert` | `sys_upload_session` | enabled | options unreadable | 1 |
277277
| `packages/services/service-storage/src/metadata-store.ts` | `update` | `sys_upload_session` | enabled | options unreadable | 2 |
278+
| `packages/services/service-storage/src/record-file-access.ts` | `update` | `state.object` | undecidable | context, elevation undecidable | 1 |

0 commit comments

Comments
 (0)