Skip to content

Commit 59a1f56

Browse files
committed
Merge S8 (claude/issue-15204-s8-catalog-objects @ dbae752, carries D fcaedfd) into the C3 integration tree
# Conflicts: # packages/plugins/plugin-security/src/security-plugin.ts
2 parents 712361b + dbae752 commit 59a1f56

162 files changed

Lines changed: 1221 additions & 9119 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
'@objectstack/plugin-security': minor
3+
---
4+
5+
feat(plugin-security)!: the boot writes no `sys_permission_set` row — the declared-permission seeder and the platform-default materialization are deleted
6+
7+
Clause-②: yes (narrowing)
8+
9+
<!-- adr-0087: not-required (no-migration-prescription) A runtime change on a platform object's rows and on TypeScript surfaces, not on any metadata schema: no key of any spec schema is removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite and no tombstone. The rows the retired seeders wrote stay in the table until a later ADR-0131 stage; nothing reads them for authorization. The package publishes (not unpublished); no ADR-0087 id covers this rule and this diff adds none (not registered / already-registered). -->
10+
11+
**BREAKING**, shipped as `minor` under the repo's launch-window convention for breaking changes.
12+
13+
`SecurityPlugin` no longer writes a `sys_permission_set` row for any permission set: not for the platform defaults (`admin_full_access`, `member_default`, …), not for a set a package declares, not for an organization's copy, and not on a package-door publish, a metadata reload or an organization's creation. Permission sets are served by the security catalog (ADR-0131 D3), and since the grant names its set (`sys_user_permission_set.permission_set`), no grant path needs a row. A fresh database still promotes its first platform administrator, grants organization administrators and self-registered members, and grants every principal what it was granted before. On a database that was already seeded, the existing rows stay as they are; they are no longer refreshed at boot.
14+
15+
- **Accepted package defaults follow every publish.** The `everyone` anchor is derived again after every landed `permission` mutation (publish, direct save or delete, through any door), so an accepted set whose new body no longer qualifies stops granting at once. Before this release the re-derivation ran only inside the publish materializer, and only when the published body carried an `isDefault` key.
16+
- **`drift_status` and `drift_detail` are gone from `sys_permission_set`**, with the **Needs Attention** list view that listed them. Nothing computes them any more: the declared-versus-enforced diagnostic retired with the rows it compared. A Studio overlay that shadows a packaged set is still named at boot.
17+
- `bootstrapPlatformAdmin` no longer takes the `resync` option and no longer reports `seeded`, `resynced` or `resyncSkipped`. A refused read of the legacy `admin_full_access` row (the restrict-only reach to a grant written before the name column existed) withholds the promotion and says so once.
18+
19+
Removed from `@objectstack/plugin-security`'s public exports, with no replacement:
20+
21+
- `bootstrapDeclaredPermissions`
22+
- `normalizeManagedByVocab`
23+
- `computePermissionSetDriftDiagnostics`, `persistPermissionSetDriftDiagnostics`, `runPermissionSetDriftDiagnostics`, and the types `PermissionSetDriftStatus`, `PermissionSetDriftDiagnostic`, `DriftDiagnosticsOptions`
24+
- `CAPABILITY_DECLARATION_UNOWNED`, `CAPABILITY_PLATFORM_NAME_REFUSED`, `PERMISSION_SET_DECLARATION_UNOWNED`, `capabilityDeclarationUnownedDiagnostic`, `capabilityPlatformNameRefusedDiagnostic`, `permissionSetDeclarationUnownedDiagnostic`, `reportCapabilityDeclarationUnowned`, `reportCapabilityPlatformNameRefused`, `reportPermissionSetDeclarationUnowned`, and the types `CapabilityDeclarationUnownedDiagnostic`, `CapabilityPlatformNameRefusedDiagnostic`, `PermissionSetDeclarationUnownedDiagnostic`
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
'@objectstack/plugin-security': minor
3+
'@objectstack/platform-objects': minor
4+
'@objectstack/spec': minor
5+
'@objectstack/core': minor
6+
'@objectstack/metadata-protocol': minor
7+
'@objectstack/cloud-connection': patch
8+
'@objectstack/objectql': patch
9+
'@objectstack/plugin-sharing': patch
10+
'@objectstack/lint': patch
11+
'@objectstack/service-settings': patch
12+
---
13+
14+
feat(plugin-security)!: the four security-catalog row objects are retired — `sys_position`, `sys_permission_set`, `sys_position_permission_set` and `sys_capability` (ADR-0131 D3)
15+
16+
Clause-②: yes (narrowing)
17+
18+
<!-- adr-0087: registered catalog-row-objects-retired -->
19+
20+
**BREAKING**, shipped as `minor` under the repo's launch-window convention for breaking changes.
21+
22+
Positions, permission sets and capabilities live in the security catalog — the environment registry, fed by package declarations and by environment metadata saved through `/api/v1/meta` (ADR-0131 D3). The four row objects that mirrored them are no longer registered, so their data and REST routes and their Setup object pages are gone. No table is dropped and no row is deleted.
23+
24+
FROM → TO:
25+
26+
- `GET|POST|PATCH|DELETE /api/v1/data/sys_permission_set` → `GET|PUT|DELETE /api/v1/meta/permission/:name`; to copy a set, `POST /api/v1/security/permission-sets/:name/clone` with `{ name, label }`.
27+
- `… /api/v1/data/sys_position` → `/api/v1/meta/position/:name`. A position's permission sets are its definition's `permissionSets`.
28+
- `… /api/v1/data/sys_position_permission_set` → the position definition's `permissionSets` (`PUT /api/v1/meta/position/:name`).
29+
- `… /api/v1/data/sys_capability` → read-only `GET /api/v1/meta/capability`; a package declares a capability with `defineCapability` (`stack.capabilities`).
30+
- Setup → Access Control → Positions / Capabilities / Permission Sets now open Setup's catalog lists (`/apps/setup/metadata/<type>?scope=environment`) instead of the object pages; the `sys_position` record page (`SysPositionDetailPage`) is removed.
31+
- An object permission on one of the four names in a permission set grants nothing and can be deleted.
32+
33+
What else changes:
34+
35+
- `sys_user_permission_set.permission_set_id` is a plain text column now, not a lookup: same column, same stored ids, same indexes. It is not written and grants nothing; a grant names its set by `permission_set`.
36+
- A permission set saved through the metadata door is written to no row: the `permission` mutation projector, the `sys_permission_set` and `sys_position` data-door write-throughs and the row-only position backfill are no longer registered.
37+
- On a fresh `single`-posture database the first human is promoted to platform administrator without reading any catalog row. An unscoped grant written before `sys_user_permission_set.permission_set` existed (it names no set) still withholds the promotion until the organization-ownership migration names it.
38+
- Uninstalling a package revokes every grant naming a permission set the package declared. The uninstalling door reads those names off the package before withdrawing it and hands them to each uninstall cleanup as `declared` (`UninstallCleanup`, `@objectstack/metadata-protocol`; `declaredCatalogItemsOf` is exported).
39+
- `capability-reference-unknown` no longer counts a `sys_capability` seed row as a declared capability — no runtime reader consults one. Declare the capability with `defineCapability`.
40+
41+
Removed exports, no replacement:
42+
43+
- `@objectstack/plugin-security`: the object definitions `SysPosition`, `SysPermissionSet`, `SysPositionPermissionSet`, `SysCapability` (from `./objects`); `securityObjects` lists the remaining three.
44+
- `@objectstack/platform-objects/pages`: `SysPositionDetailPage`.
45+
- `@objectstack/spec`: `SystemObjectName.POSITION`, `SystemObjectName.PERMISSION_SET`; the four names leave `PLATFORM_OBJECTS_BY_PACKAGE['plugin-security']` and `PLATFORM_PROVIDED_OBJECT_NAMES`.
46+
- `@objectstack/core`: `isRowActive` and `ActivatableRow` — a catalog row's `active` column decides nothing; deactivation is the activation ledger's (`sys_metadata_activation`).

‎content/docs/permissions/authorization.mdx‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -152,13 +152,11 @@ them, and treat "sensitive field on a public object" as a review smell.
152152
The metadata↔config boundary follows one line: **definitions travel with the
153153
package (metadata); subject bindings and env-specific values stay as config.**
154154

155-
- A package ships **its own permission sets** (Shape B), recorded with
156-
`managedBy: 'package'` + owning `packageId` on `sys_permission_set`
157-
(`package_id` / `managed_by` columns). `bootstrapDeclaredPermissions`
158-
(`packages/plugins/plugin-security/src/bootstrap-declared-permissions.ts`)
159-
seeds `stack.permissions` at boot — idempotent, re-seeded on upgrade, and it
160-
**never clobbers** env-authored (`platform`/`user`/legacy) rows. A package
161-
never writes into a foreign record.
155+
- A package ships **its own permission sets** (Shape B): its
156+
`stack.permissions` are registry items stamped with the owning package
157+
(`_packageId`), served by name from the security catalog (ADR-0131 D3). The
158+
boot writes no `sys_permission_set` row for them, and a package never
159+
writes into a foreign definition.
162160
- The environment admin **assigns** sets to positions/users; the runtime unions
163161
them. One shared set with hand-picked cross-package grants remains an
164162
env-admin-only construct.

‎content/docs/permissions/permission-sets.mdx‎

Lines changed: 19 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -161,8 +161,9 @@ the anchor decides *which* unit `unit*` means.
161161

162162
## Built-in permission sets
163163

164-
Auto-seeded on boot by `plugin-security`
165-
(`objects/default-permission-sets.ts`):
164+
Declared by `plugin-security` on its own manifest
165+
(`objects/default-permission-sets.ts`) and served from the security catalog —
166+
the boot writes no row for them:
166167

167168
| Name | Scope | What it unlocks | Notes |
168169
|:--|:--|:--|:--|
@@ -337,9 +338,10 @@ tenant-level.
337338

338339
## Provenance — package vs environment sets (ADR-0086)
339340

340-
A package ships its own sets (`managedBy: 'package'` + `packageId`), seeded
341-
idempotently at boot and re-seeded on upgrade; environment-authored sets
342-
(`platform`/`user`) are never clobbered. The data layer refuses forging package
341+
A package ships its own sets as registry items stamped with the owning package
342+
(`packageId`), served from the security catalog — the boot writes no row for
343+
them, and an upgrade is served as soon as the package registers its new
344+
version; environment-authored sets are never clobbered. The data layer refuses forging package
343345
provenance through the admin door (two-doors separation, evolved by ADR-0094 —
344346
an edit of a set shipped in code is refused; clone it instead, see below), which
345347
is what makes package uninstall well-defined — and enforced: uninstalling a
@@ -423,47 +425,21 @@ it was copied from, so changes to the source never reach the copy.
423425

424426
### Declared ≠ enforced — diagnosing a frozen package set
425427

426-
A package-declared set's *enforced* grants (what `sys_permission_set` stores
427-
and what the evaluator resolves) can diverge from its shipped *artifact*
428-
(what the package currently declares) through two independent mechanisms —
429-
either can be live on one row, and they need different remedies:
428+
A package-declared set's *enforced* grants (what the security catalog serves
429+
and the evaluator resolves) can diverge from its shipped *artifact* (what the
430+
package currently declares) in one way:
430431

431432
- **Overlay shadow.** An active `sys_metadata` overlay for the set's name
432433
(from a Studio save made while overlaying was still permitted, or through
433-
the `OS_METADATA_WRITABLE` escape hatch) is re-projected onto the record on
434-
every boot, unconditionally — the overlay wins forever, regardless of what
435-
the package ships next. No door creates such an overlay any more: the
436-
metadata door refuses a save over a packaged set, and so does the data door
437-
(clone the set instead). **Remedy:** delete the overlay row. From the
438-
release that adds ADR-0048's cold-boot check, a deployment that still holds
439-
one does not boot: `os migrate security-catalog-overlays` lists every such
440-
row with no server running, and `--apply` deletes them, after which the
441-
package's definition is served again.
442-
- **Provenance skip.** The record's `managed_by` column predates package
443-
provenance tracking (a legacy insert without `managed_by: 'package'` —
444-
typically a database first initialized on an older release line), so boot
445-
seeding treats it as environment-authored and never reconciles it with the
446-
package — permanently. There is currently no automated adoption path for
447-
this case (boot-time auto-adoption and a bulk `os meta
448-
adopt-permission-sets` command were both deliberately deferred as migration
449-
machinery for a customer population that does not yet exist — see the
450-
discussion on the tracking issue for this section). The manual recovery is
451-
the same one-time SQL a field remediation used, run against the
452-
environment's database with a backup first:
453-
454-
```sql
455-
UPDATE sys_permission_set
456-
SET managed_by = 'package', package_id = '<owning package id>'
457-
WHERE name = '<permission set name>';
458-
```
459-
460-
Restart the environment afterward so boot seeding re-adopts the row as
461-
package-owned and reconciles its grants to the shipped artifact.
462-
463-
Both mechanisms are surfaced on the record itself: `drift_status`
464-
(`'overlay_shadow'` / `'provenance_skip'`) and `drift_detail` name the cause,
465-
recomputed every boot, and the **Needs Attention** list view collects every
466-
currently drifted set — an in-sync set is never listed there.
434+
the `OS_METADATA_WRITABLE` escape hatch) answers ahead of the package's
435+
definition — the overlay wins forever, regardless of what the package ships
436+
next. No door creates such an overlay any more: the metadata door refuses a
437+
save over a packaged set, and so does the data door (clone the set instead).
438+
The boot names every such set in its log. **Remedy:** delete the overlay
439+
row. From the release that adds ADR-0048's cold-boot check, a deployment
440+
that still holds one does not boot: `os migrate security-catalog-overlays`
441+
lists every such row with no server running, and `--apply` deletes them,
442+
after which the package's definition is served again.
467443

468444
---
469445

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

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

8585
**The expensive failure direction is a keyword.** Sites whose receiver the author
86-
typed `any` have no type to read, and there are 44 of them — just under a fifth
86+
typed `any` have no type to read, and there are 42 of them — just under a fifth
8787
of the population, concentrated in exactly the seed and bootstrap paths this
8888
control exists for. Scoring an unreadable receiver as "not an engine" would have
8989
dropped every one of them silently, with a clean exit and a smaller number that
@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
122122

123123
The same holds twice over for the context. An options argument spelled as a
124124
literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
125-
forwarding shim cannot, and **53 of the 227 sites are spelled that way**. A
125+
forwarding shim cannot, and **53 of the 225 sites are spelled that way**. A
126126
context resolved from an inline literal or a local `const` can be tested for
127127
`isSystem`; one arriving from a helper call cannot.
128128

@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
187187

188188
| carried figure | where it survives | this census |
189189
| :--- | :--- | ---: |
190-
| 175 write call sites | quoted in the merged changeset | **227** |
190+
| 175 write call sites | quoted in the merged changeset | **225** |
191191
| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **32** more whose options argument is unreadable |
192-
| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **155 of 227** decidable, **72** undecidable |
193-
| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 122 decidably elevated, 0 decidably not, 97 undecidable |
192+
| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **155 of 225** decidable, **70** undecidable |
193+
| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 120 decidably elevated, 0 decidably not, 97 undecidable |
194194
| 141 and 132, two independent re-derivations | the card that filed this work | — |
195195

196196
**The differences are not reconciled, and deliberately so.** The old census's
@@ -200,18 +200,18 @@ be stated is what this instrument counts, which is written above and re-runnable
200200
at any commit.
201201

202202
Two structural facts do plausibly widen this reading against any hand or regex
203-
one, and both are counted in the generated tables below: the 44 sites reached
203+
one, and both are counted in the generated tables below: the 42 sites reached
204204
through an erased (`any`) receiver, and the 52 that name their object through a
205205
`const` rather than inline. An instrument that read either the way a person does
206206
would report a smaller number and would not say so.
207207

208208
The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
209209
figure has no surviving corroboration anywhere in the tree.** This census reads
210-
122 of 227 (54%) as decidably elevated, with 97 more whose elevation is a
210+
120 of 225 (53%) as decidably elevated, with 97 more whose elevation is a
211211
run-time fact — so the claim is neither confirmed nor refuted, and the honest
212212
answer is that a static reading cannot settle it.
213213

214-
⇒ **Cite `2 / 227`, and say what it is**: the sites whose options argument was
214+
⇒ **Cite `2 / 225`, and say what it is**: the sites whose options argument was
215215
READ and holds no tenant context, against a decidably tenancy-enabled object.
216216
That is the control's provable yield surface. ⛔ Do not cite it as "the sites
217217
without tenant context" — **32 further sites** have an options argument this
@@ -223,30 +223,30 @@ cannot read, and they are neither in nor out.
223223

224224
| what | count |
225225
| :--- | ---: |
226-
| write call sites on the application surface | **227** |
226+
| write call sites on the application surface | **225** |
227227
| …whose object name is statically decidable | 155 |
228-
| …whose object name is chosen at run time | 72 |
229-
| …against an object with tenancy ENABLED | 154 |
228+
| …whose object name is chosen at run time | 70 |
229+
| …against an object with tenancy ENABLED | 151 |
230230
| …against an object that declares tenancy off | 1 |
231-
| threading a tenant context | 166 |
231+
| threading a tenant context | 164 |
232232
| PROVABLY carrying none (options read, no context key) | **8** |
233233
| …of those, against a decidably tenancy-enabled object | **2** |
234234
| options argument UNREADABLE — may or may not carry one | 53 |
235235
| …of those, against a decidably tenancy-enabled object | 32 |
236-
| threading a decidably ELEVATED (`isSystem`) context | 122 |
236+
| threading a decidably ELEVATED (`isSystem`) context | 120 |
237237
| threading a context that is decidably NOT elevated | 0 |
238238
| threading a context whose elevation is a run-time fact | 97 |
239239

240240
| how the instrument reached the site | count |
241241
| :--- | ---: |
242242
| receiver carried a readable engine type | 183 |
243-
| receiver erased, placed by the object NAME | 30 |
244-
| receiver erased, placed by an `object: string` PARAMETER | 9 |
245-
| receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
243+
| receiver erased, placed by the object NAME | 27 |
244+
| receiver erased, placed by an `object: string` PARAMETER | 7 |
245+
| receiver erased, placed by an `UNTYPED_RECEIVERS` row | 8 |
246246

247247
| object name spelled inline | 103 |
248248
| object name spelled through a `const` | 52 |
249-
| object name is an `object: string` parameter | 11 |
249+
| object name is an `object: string` parameter | 9 |
250250
| object name is some other run-time expression | 61 |
251251

252252
### Subtractions the census could NOT defend — enforced
@@ -297,13 +297,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
297297
their values are not compared. The reasoning, and the measurement behind it,
298298
are in `scripts/check-tenant-audit-census.mjs`.
299299

300-
Measured on 2026-10-11 at `be55432f6`.
300+
Measured on 2026-10-12 at `c9ef4fbce`.
301301

302302
| corpus scale (not enforced) | count |
303303
| :--- | ---: |
304-
| tracked non-test sources scanned | 632 |
305-
| engine-shaped types recognised | 72 |
306-
| declared objects in the registry | 117 |
304+
| tracked non-test sources scanned | 624 |
305+
| engine-shaped types recognised | 71 |
306+
| declared objects in the registry | 113 |
307307
| same-named calls subtracted as non-engine | 161 |
308308

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

0 commit comments

Comments
 (0)