fred
009a0ef18e
ci/woodpecker/pr/ci Pipeline was canceled
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).
370 lines
22 KiB
Markdown
370 lines
22 KiB
Markdown
# RBAC Grant Model Contract
|
||
|
||
Status: DRAFT — awaiting ratification (webui-audit S2, contract 2 of 9).
|
||
Authority: PRD Part I §4 ("Granular RBAC: admins restrict access per company,
|
||
estate, and project; grants are evaluated down the chain") and the
|
||
native-kanban SOT Amendment A1 (§8.1.3 RBAC evaluation, §8.3 acceptance 2).
|
||
This document defines the grant vocabulary, evaluation semantics, and
|
||
revocation propagation that the hierarchy schema contract
|
||
(`docs/requirements/hierarchy-schema.md`, contract 1) attaches to. Contract 1
|
||
pins the `hierarchy_grants` table shape and defers the `role` vocabulary and
|
||
the meaning of "authority" here; the identity contract
|
||
(`docs/requirements/identity-lifecycle.md` §1.4) pins that account creation
|
||
grants nothing.
|
||
|
||
Revision 2 (independent review, GLM 5.3): §1.1 consequence analysis
|
||
completed — the two existing platform-admin bypass code paths are named as
|
||
non-conformant and §7.4 retires them; team grant subjects suspended pending
|
||
a team contract (§1.4, §3.3–3.4, §7.5); no-self-escalation restated with
|
||
its true rationale and a constructible observable (§4.2, §7.7);
|
||
node-creation seeding scoped to the bootstrap path, resolving the §7.7/§4.3
|
||
contradiction; A1 quotation corrected; audit-field provenance corrected;
|
||
principal-position consequence named (§1.3); membership-row,
|
||
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
|
||
tables themselves (contract 1), workspace-internal membership and its
|
||
role/capability vocabulary (native-kanban SOT REQ-ID-001 and its implementing
|
||
schema), roll-up projection semantics (contract 8), wizard seeding
|
||
(contract 3), the team model (suspended here; see §1.4).
|
||
|
||
## 1. Three authority layers, none substitutable
|
||
|
||
1. **Platform role** (`users.role`, better-auth: `member` | `admin`) governs
|
||
instance administration — user management, system settings, provider
|
||
configuration. It is not tenancy authority: holding platform `admin`
|
||
confers **no implicit hierarchy grant and no workspace authorization**.
|
||
An operator who should see tenant content holds an explicit, audited
|
||
grant like anyone else. This is the deny-by-default consequence of A1
|
||
§8.1.3 ("not a bypass of workspace authorization"). `AdminGuard`'s
|
||
`role === 'admin'` check on admin endpoints stays the platform role's
|
||
only meaning. **Two shipped code paths violate this rule today and are
|
||
implementation defects this contract makes non-conformant:** (a) the
|
||
command authorization service short-circuits every command scope to
|
||
allowed for platform admins
|
||
(`apps/gateway/src/commands/command-authorization.service.ts`,
|
||
`hasScope` returning true when `role === 'admin'`), and (b) the MCP
|
||
scope derivation maps platform `admin` to tenant-admin MCP scopes
|
||
including task create/update
|
||
(`apps/gateway/src/mcp/mcp.service.ts`,
|
||
`deriveMcpToolScopesForUser`). Ratifying this contract revokes both;
|
||
§7.4 names them as the surfaces the deny-by-default test retires.
|
||
2. **Hierarchy grants** (`hierarchy_grants`, contract 1 §3) declare tenancy
|
||
authority at company, estate, or platform-project scope and evaluate down
|
||
the chain to workspace-scoped authorization (§3 below).
|
||
3. **Workspace membership** (SOT REQ-ID-001) remains its own mechanism.
|
||
A chain grant confers command authorization over descendant workspaces;
|
||
it does not create membership rows, and row-level principal positions
|
||
(task owner, proposer, decision actor) still require ACTIVE workspace
|
||
membership exactly as REQ-TEN-001/REQ-ID-001 acceptance states.
|
||
Consequence, stated so implementing PRs do not weaken REQ-TEN-001 to
|
||
remove the friction: a chain-granted actor who is not a workspace member
|
||
may issue the write commands their role implies but cannot occupy a
|
||
principal position — any command taking a principal argument must name
|
||
an ACTIVE member of the target workspace (§7.2 enumerates this cell).
|
||
4. **Team grant subjects are suspended.** Contract 1 §3.1 reserves a
|
||
`team_id` attachment point, but no ratified contract yet defines the
|
||
team it would bind: the only existing `teams` table is the legacy global
|
||
Brain table (own authority columns, no workspace binding, not
|
||
repurposed per contract 1 §1.3), while the SOT's teams are
|
||
workspace-bound (REQ-ID-001) — and a workspace-bound team holding a
|
||
company-level grant would be a cross-workspace authority group nothing
|
||
has ratified. Until a team contract defines the subject (which table,
|
||
which membership rows, and its relation to D2/REQ-ID-001), creating a
|
||
grant with a team subject MUST be refused at the command surface (the
|
||
schema column remains, per contract 1). §3's evaluation semantics for
|
||
team-conferred grants are specified now so the team contract activates
|
||
them without amending this one.
|
||
|
||
## 2. Role vocabulary
|
||
|
||
One vocabulary at every hierarchy level, totally ordered — a higher role
|
||
includes everything below it:
|
||
|
||
1. `viewer` — read: sees the node, its subtree structure, and the roll-up
|
||
aggregates over descendant workspaces (within contract 8's carve-out
|
||
bounds); read access to descendant workspace content per the SOT's read
|
||
command families. No mutation of anything.
|
||
2. `member` — work: everything `viewer` has, plus write authorization for
|
||
business/orchestration command families in descendant workspaces (the
|
||
concrete command-family mapping is implementation work under SOT
|
||
REQ-ID-001; this contract pins that `member` maps to the workspace write
|
||
families and nothing structural).
|
||
3. `owner` — structure: everything `member` has, plus hierarchy mutations on
|
||
the subtree (create/rename/delete child nodes, transfers per §5), and
|
||
grant management on the node and its subtree (§4).
|
||
|
||
No other value is valid in `hierarchy_grants.role`; the column is
|
||
constraint-checked against exactly these three. Extending the vocabulary is a
|
||
contract amendment, not an implementation decision.
|
||
|
||
## 3. Evaluation semantics
|
||
|
||
1. **Deny by default.** No grant on any ancestor → no authority. There are
|
||
no implicit grants: not from platform role (§1.1), not from creating a
|
||
node (§4.3), not from workspace membership (membership without a chain
|
||
grant confers exactly what the SOT's own membership rules confer inside
|
||
that workspace, nothing up the chain).
|
||
2. **Down-the-chain only.** A grant on a node applies to that node and its
|
||
entire descendant subtree. Nothing evaluates upward or sideways: a grant
|
||
on an estate says nothing about the parent company or sibling estates.
|
||
3. **Effective role = maximum.** A subject's effective role at any node is
|
||
the highest role among grants held directly by the subject's user on
|
||
that node or any ancestor — and, once the team contract activates team
|
||
subjects (§1.4), grants held by any team the user is a member of on that
|
||
node or any ancestor. Roles never subtract — there is no negative/deny
|
||
grant in this model; revocation is deletion (§6).
|
||
4. **Team grants follow live membership** (specified now, active only per
|
||
§1.4). A team grant confers its role on the team's current members,
|
||
evaluated at decision time. Leaving the team is loss of the grant with
|
||
§6's propagation bound.
|
||
5. **Live evaluation, fail closed.** Authorization decisions derive from the
|
||
live grant and team-membership rows (or from a cache that is invalidated
|
||
in the same transaction as any grant/membership/hierarchy mutation). A
|
||
decision path that cannot read grant state denies. No materialized ACL is
|
||
ever authoritative.
|
||
6. **Tenant context stays derived from authenticated authority**
|
||
(REQ-TEN-001). The chain adds where grants can be declared; a workspace
|
||
request is still authorized against that workspace, with the chain
|
||
contributing the effective role — never letting the chain become what A1
|
||
§8.1.3 forbids: "a bypass of workspace authorization".
|
||
|
||
## 4. Grant management
|
||
|
||
1. Creating, changing, or revoking a grant on a node requires effective
|
||
`owner` on that node (directly or via any ancestor).
|
||
2. **No self-escalation.** A grant manager cannot create a grant with a role
|
||
higher than their own effective role on the target node. Under the §2
|
||
vocabulary this rule is currently implied by §4.1 (managers are `owner`,
|
||
the top role — no constructible grant exceeds it); it is stated
|
||
explicitly so it survives any future amendment that decouples
|
||
grant-management authority from role height. Its observable is the §7.7
|
||
audit invariant, not a refusal test.
|
||
3. **Bootstrap of authority is explicit; inheritance covers the rest.**
|
||
Creating the first company (the wizard path, contract 3) and any
|
||
top-level company creation MUST name the initial `owner` grant in the
|
||
same audited operation — a top-level node has no ancestor to inherit
|
||
from, so without this the node would be unownable. Creating a child node
|
||
(estate, platform-project, workspace) requires effective `owner` on the
|
||
parent (§2.3) and confers no automatic grant; the creator's authority
|
||
over the new node already follows from §3.2 down-the-chain evaluation.
|
||
The creating command MAY additionally name an explicit initial grant for
|
||
a child node; it is not required to.
|
||
4. Every grant mutation is a semantic audit event under contract 1 §5.2's
|
||
guarantees, extended by this contract with two further fields: the event
|
||
carries actor, verb, target, **subject, and role** (subject and role are
|
||
this contract's addition; contract 1 §5.2 does not enumerate them).
|
||
5. **Role strings are namespaced.** `viewer`/`member` exist at hierarchy
|
||
level, `member`/`admin` on `users.role`, and the current command layer
|
||
uses a third `viewer|member|admin` vocabulary — same strings, different
|
||
meanings. Any serialized role string (audit events per §4.4, API
|
||
responses, logs) MUST identify its layer (e.g. `hierarchy:owner`,
|
||
`platform:admin`); a bare role string in a serialized artifact is
|
||
non-conformant.
|
||
|
||
## 5. Transfer authority (completes contract 1 §4.2)
|
||
|
||
"Authority over BOTH the source and the destination parent" means: effective
|
||
`owner` on the current parent node (or an ancestor) AND effective `owner` on
|
||
the destination parent node (or an ancestor), evaluated at transfer time in
|
||
the transfer's own transaction. One subject must hold both; two cooperating
|
||
half-authorized subjects are not a transfer protocol this contract defines.
|
||
|
||
## 6. Revocation propagation
|
||
|
||
1. Revoking a grant (deleting the row), removing a user from a team that
|
||
carries a grant (once team subjects activate, §1.4), or the cascade
|
||
deletion of a node's grants during node deletion (contract 1 §3.3) all
|
||
propagate identically: the authority derived from that grant is gone for
|
||
every descendant workspace.
|
||
2. **Bound:** the next authorization decision on any affected transport
|
||
decides against the revoked grant. Concretely: no new HTTP/MCP command
|
||
authorized by the revoked grant after the revoking transaction commits;
|
||
an open Socket.IO connection whose subscriptions depend on the revoked
|
||
grant is re-evaluated within 30 seconds or at its next inbound message,
|
||
whichever comes first (same bound as the identity contract's §7.1
|
||
deactivation rule; same mechanism may serve both).
|
||
3. Revocation is subtractive only in effect, not in representation: the
|
||
evaluator never needs tombstones; deletion of the row is the revocation.
|
||
|
||
## 7. Verification requirements
|
||
|
||
Binding on the implementing PRs (extends A1 §8.3 acceptance 2–3 and
|
||
contract 1 §6):
|
||
|
||
1. Vocabulary: the role CHECK constraint rejects any value outside
|
||
`viewer|member|owner` (real-PostgreSQL witness, `ci-postgres` service in
|
||
the `test` CI step).
|
||
2. Per-level conferral: for each of the three levels × three roles, a grant
|
||
yields exactly the implied workspace authorization in a descendant
|
||
workspace and nothing in a non-descendant workspace (the A1 §8.3
|
||
"exactly the permissions the chain implies" matrix, enumerated). The
|
||
matrix includes: a chain grant creates zero workspace-membership rows
|
||
(assert row counts); a chain-granted non-member is refused as the
|
||
principal argument of any principal-taking command while their
|
||
non-principal writes succeed (§1.3); structure reads leak no existence
|
||
of nodes the reader holds no grant on (no cross-tenant existence
|
||
oracle, A1 §8.3 acceptance 3).
|
||
3. Ordering: `owner` ⊇ `member` ⊇ `viewer` behaviorally — each higher role
|
||
passes every lower role's positive cases.
|
||
4. Deny-by-default: platform `admin` with no grant reaches no tenant
|
||
content — asserted against the two §1.1 non-conformant surfaces after
|
||
their retirement: the command-authorization admin short-circuit and the
|
||
MCP tenant-admin scope derivation both gone (a platform admin with no
|
||
grant is refused workspace commands and receives no tenant MCP scopes);
|
||
workspace member with no chain grant gains nothing outside SOT
|
||
membership semantics; fresh account reaches nothing (identity contract
|
||
§1.4 cross-check).
|
||
5. Team subjects: while suspended (§1.4), creating a team-subject grant is
|
||
refused at the command surface. On activation by the team contract:
|
||
user-direct and team-conferred grants combine to the maximum; team-leave
|
||
drops authority within the §6.2 bound; decision-time evaluation
|
||
witnessed (grant added → next decision allows; no restart or re-login
|
||
required).
|
||
6. Revocation: each revocation path in §6.1 denies the next command on
|
||
every transport; the socket bound is measured; a cached-authorization
|
||
implementation proves transactional invalidation (grant revoked and
|
||
decision made on two distinct physical connections). Fail-closed fault
|
||
witness for §3.5: with grant state unreadable (fault injection), the
|
||
decision denies.
|
||
7. Grant management: non-`owner` cannot mutate grants; top-level company
|
||
creation without the named initial `owner` grant is refused, while child
|
||
node creation under ancestor authority succeeds without one (§4.3 both
|
||
directions); every mutation produces its audit event with the §4.4
|
||
fields. Self-escalation observable: over the audit event stream, every
|
||
grant-create/change event's role is ≤ the acting user's effective role
|
||
on the target at event time (reconstructable invariant, not a refusal
|
||
test — see §4.2).
|
||
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
|
||
interpretive resolution named:
|
||
|
||
- Decision: platform `admin` confers no implicit tenant access — operators
|
||
see tenant content only through explicit, audited grants (§1.1), which
|
||
retires the two existing admin bypass paths named there. Say "agreed" or
|
||
name the implicit access you want platform admins to keep.
|
||
- Interpretive resolution (for visibility, not a separate question): PRD
|
||
Part I §4 says "admins restrict access per company, estate, and project";
|
||
this contract resolves "admins" as hierarchy `owner`s (§4.1), not
|
||
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.
|