From 009a0ef18e0abd9dd359bcbafee3fe340a175dea Mon Sep 17 00:00:00 2001 From: fred Date: Sat, 29 Aug 2026 13:35:59 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20contract=202=20Amendment=201=20?= =?UTF-8?q?=E2=80=94=20company-CRUD=20capability=20definition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Defines the capability class hierarchy schema §5.5 / contract 1 Amendment 1 anticipates: a platform-scoped, admin-assigned, audited delegation of exactly the company visibility command. No read surface, no other company operation; §2 vocabulary and §3 evaluation untouched. Ends in a one-sentence ruling request (S2 process). --- docs/requirements/rbac-grant-model.md | 110 ++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/requirements/rbac-grant-model.md b/docs/requirements/rbac-grant-model.md index edcd86f8..30ff3b94 100644 --- a/docs/requirements/rbac-grant-model.md +++ b/docs/requirements/rbac-grant-model.md @@ -24,6 +24,19 @@ fail-closed-fault, and existence-oracle observables added (§7); role-string namespacing rule added (§4.5); ruling request now names the interpretive resolution of PRD "admins". +Amendment 1 (company-CRUD capability): defines the capability class that +contract 1 Amendment 1 (Ruling 4b, 2026-08-28) and hierarchy schema §5.5 +anticipate. §8 defines the capability as a platform-scoped, admin-assigned, +audited delegation of exactly the hierarchy schema §5.5 company visibility +command — no read surface, no other company operation. The hierarchy role +vocabulary (§2), every evaluation rule (§3), and grant management (§4) are +untouched: the capability is not a `hierarchy_grants.role` value and +evaluates outside the chain. Until this amendment ratifies, the capability +class is empty and +the visibility command remains admin-only (hierarchy schema §5.5 states +this fallback; the shipped gate at +`apps/gateway/src/hierarchy/hierarchy.repository.ts` implements it). + Scope: the roles that can appear in `hierarchy_grants.role`, what a grant at each hierarchy level confers, how grants evaluate down the chain, how revocation propagates, and who may manage grants. Out of scope: the hierarchy @@ -242,6 +255,91 @@ contract 1 §6): 8. Transfer: both-sides `owner` accepted, each single-side case refused (completing contract 1 §6.5). +## 8. Company-CRUD capability (Amendment 1) + +Hierarchy schema §5.5 authorizes the company visibility mutation for +exactly two actor classes: platform admins and "subjects holding the +company-CRUD capability that a follow-up amendment to contract 2 will +define". This section is that definition. The name is historical — coined +in contract 1 Amendment 1 before the capability's content was fixed — and +confers nothing by connotation: the ratified content is exactly §8.1. +Company _creation_ is already ruled open to active users and always +private (contract 3 §5.2, Ruling 4); rename, delete, and transfer of +companies remain hierarchy `owner` operations (§2.3, §5); none of those is +part of this capability, and widening it to any other operation is a +further amendment, not an implementation decision. + +1. **Content: exactly one command, no read surface.** Holding the + capability authorizes executing the hierarchy schema §5.5 visibility + command (`companies.visibility`, both directions: + `private → directory` and `directory → private`) on any company in the + deployment. It authorizes nothing else — and in particular it carries + **no read surface**: no company enumeration, no structure read, no + existence probe beyond what every authenticated user already has (the + §2.8 directory listing). The practical flow this implies is + deliberate: to publish a private company, the holder is given the + target identifier by the requesting company `owner` out of band; to + unpublish, the target is already directory-listed. A curation listing + for capability holders, if ever wanted, is a further amendment with its + own disclosure analysis under hierarchy schema §6.7. +2. **Holding: platform-scoped assignment, user subjects only.** The + capability is not a hierarchy grant: it attaches to no node, has no + role, and never enters §3 chain evaluation. It is held via a + `platform_capabilities` table: `id`, `user_id` (FK `users`, NOT NULL), + `capability` (text, NOT NULL, constraint-checked against exactly + `company_crud`), `granted_by` (FK `users`, NOT NULL), `created_at`; + UNIQUE (`user_id`, `capability`). No team subjects (§1.4's suspension + reasoning applies with more force here — a workspace-bound team holding + deployment-wide curation authority has no ratified meaning), no expiry + column: revocation is row deletion, as everywhere in this contract. +3. **Assignment is instance administration.** Only platform admins + (`users.role = 'admin'`) may assign or revoke the capability — + assignment delegates a slice of instance administration and is itself + an instance-administration act under §1.1. A capability holder as such + may NOT assign or revoke it (no self-propagation). Every assignment + and revocation is a semantic audit event carrying actor, verb, subject + user, and capability; serialized capability strings are namespaced per + §4.5 (`platform-capability:company-crud` — a bare `company_crud` in + any serialized artifact is non-conformant). +4. **Evaluation and revocation follow this contract's existing rules.** + The hierarchy schema §5.5 command's authorization predicate is: `users.role = 'admin'` + OR a live `platform_capabilities` row (`user_id`, `company_crud`) — + evaluated live and fail-closed per §3.5 (unreadable capability state + denies). Revocation propagates per §6: the next authorization decision + on any transport decides against the deleted row, within §6.2's bound. +5. **What it does not confer**, stated so implementing PRs cannot drift: + no hierarchy grant or effective role at any node; no workspace + authorization or membership; no content, structure, or roll-up read; + no grant management (§4.1 unchanged); no MCP scope; no other instance + administration (user management, system settings, provider + configuration remain platform-admin-only); no company create, rename, + delete, or transfer. Hierarchy schema §5.5's rule that a company + `owner` as such may NOT change visibility is unchanged — `owner` and + this capability are disjoint authorities that combine only by a + subject holding both. +6. **Verification requirements** (extends §7, binding on implementing + PRs): + 1. Vocabulary: the `capability` CHECK constraint rejects any value + outside `company_crud` (real-PostgreSQL witness, `ci-postgres` + service in the `test` CI step). + 2. Conferral exactness: a non-admin holder succeeds on the visibility + command in both directions with contract 1 §5.2's audit event + (old and new values as semantic content); the same holder, with no + other grants, is refused a workspace command, receives the + not-found-indistinguishable refusal on a structure read of the very + company they just mutated (hierarchy schema §6.7), cannot create a + grant, and derives no MCP scope — the §7.4 deny-by-default matrix + gains this cell. + 3. Assignment authority: a non-admin — including a current capability + holder — is refused assign and revoke; every assign/revoke produces + its audit event with the namespaced string (§8.3). + 4. Revocation and fail-closed: after row deletion, the ex-holder's + next visibility command is refused; with capability state + unreadable (fault injection), the decision denies (§3.5). + 5. Owner-as-such refusal re-witnessed: hierarchy schema §6.9's + owner-cannot-publish witness re-asserted with the + `platform_capabilities` table present and empty for that owner. + ## Ruling request Ratify sections 1–7 as written, with one decision embedded and one @@ -257,3 +355,15 @@ interpretive resolution named: platform admins. A1 §8.1.3 does not attribute grant declaration to platform admins, and the §1.1 decision above is what makes this reading binding. + +## Ruling request (Amendment 1) + +Ratify §8 and the Amendment 1 header note as written, with one decision +embedded: + +- Decision: the company-CRUD capability is a platform-scoped, + admin-assigned, audited delegation of exactly the hierarchy schema §5.5 + visibility command — no read surface, no other company operation. Say + "agreed" or + name the additional operations (or the curation listing) you want it to + carry.