stack/docs/requirements/rbac-grant-model.md

# 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.

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).

## 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's "never a bypass" rule; today's `AdminGuard` checks
   `role === 'admin'` for admin endpoints and that stays its only meaning.)
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.

## 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 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.** 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 a bypass of workspace-scoped
   checks.

## 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. (With the §2
   vocabulary this only bites managers acting through team-conferred
   `owner`: the rule is stated so it survives vocabulary amendments.)
3. Creating a hierarchy node confers no automatic grant. Bootstrap of
   authority is explicit: the creating command names the initial `owner`
   grant in the same audited operation, and the wizard (contract 3) seeds
   the first company's initial `owner` the same way.
4. Every grant mutation is a semantic audit event per contract 1 §5.2
   (actor, verb, subject, target, role).

## 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, or deleting an ancestor node's grant 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.4):

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).
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; workspace member with no chain grant gains nothing outside SOT
   membership semantics; fresh account reaches nothing (identity contract
   §1.4 cross-check).
5. Max-rule and teams: 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).
7. Grant management: non-`owner` cannot mutate grants; self-escalation
   attempt refused; node creation without the explicit initial grant
   refused; every mutation produces its audit event.
8. Transfer: both-sides `owner` accepted, each single-side case refused
   (completing contract 1 §6.2).

## Ruling request

Ratify sections 1–7 as written, with one decision embedded: platform `admin`
confers no implicit tenant access — operators see tenant content only
through explicit, audited grants (§1.1) — say "agreed" or name the implicit
access you want platform admins to have.