Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
08410dbd84 | ||
|
|
6a49de55bf |
@@ -72,25 +72,6 @@ example now lists the complete measured set, and the import analysis
|
||||
is extended to resolve literal dynamic `import()` routes, which two of
|
||||
the four members use.
|
||||
|
||||
Amendment 1 (Ruling 4b, 2026-08-28): company visibility classes. The
|
||||
directory exists so one shared company can serve many users instead of
|
||||
each user creating a duplicate private company (Ruling 4b, webui-audit
|
||||
lane, ruled 2026-08-27). §2.1 gains a `visibility` column; §2.8 defines
|
||||
the two classes (`private`/`directory`), the directory's existence-only
|
||||
disclosure, and the pre-binding invariants for the deferred
|
||||
see-and-ask-to-join flow (no join-request surface is authorized here —
|
||||
its flow is a follow-up contract); §5.2's mutation
|
||||
enumeration gains the visibility change; §5.5 defines who may change
|
||||
visibility (platform admins, plus a company-CRUD capability whose
|
||||
definition is a follow-up amendment to contract 2 — until it ratifies,
|
||||
admin-only); §6.1 and §6.9 add the witnesses; §6.7's existence-oracle
|
||||
rule is scoped around the ratified directory carve-out. Top-level
|
||||
creation (contract 3 §5.2) is unchanged and always yields a private
|
||||
company. Upstream, SOT Amendment A2 (native-kanban-sot.md §9, this PR)
|
||||
expressly extends A1 §8.1.2 to admit the visibility column and A1
|
||||
§8.1.3 to admit the directory function — this contract relies on that
|
||||
amendment, not on a reinterpretation of A1.
|
||||
|
||||
Scope: the tenancy/authorization structure record class — companies,
|
||||
estates, platform-projects, workspaces, hierarchy grants, their parentage,
|
||||
and constraints. Out of scope: the RBAC grant vocabulary and evaluation
|
||||
@@ -105,13 +86,8 @@ legacy flat data (future work; see §1.3).
|
||||
AND `hierarchy_grants` (§3) — A1 includes hierarchy-level access grants
|
||||
in the class. Every rule addressed to "the class" in this contract
|
||||
(payload prohibition, mutation path, audit) binds all five tables. Class
|
||||
rows carry parentage, naming, grant, audit-linkage, and visibility-class
|
||||
data only — never task, plan, or any business/orchestration payload.
|
||||
Visibility (`companies.visibility`, §2.8) is admitted into that
|
||||
enumeration by SOT Amendment A2 §9.1.1, which expressly extends A1
|
||||
§8.1.2 for exactly this one column: it is disclosure data about the
|
||||
class's own nodes — not a payload field, carries no business content,
|
||||
and widens the payload prohibition for nothing else.
|
||||
rows carry parentage, naming, grant, and audit-linkage data only — never
|
||||
task, plan, or any business/orchestration payload.
|
||||
References from business/orchestration rows into the class are limited
|
||||
to exactly one form: the canonical `workspace_id` tenancy column that
|
||||
REQ-TEN-001 requires on every canonical row, referencing
|
||||
@@ -140,9 +116,7 @@ MUST NOT merge the two. (A rename of either remains an implementation-PR
|
||||
decision under A1; this contract pins only that they stay distinct tables.)
|
||||
|
||||
1. `companies` — id (uuid pk), name, slug (unique per deployment),
|
||||
`visibility` (text NOT NULL, DEFAULT `private`, CHECK constrained to
|
||||
exactly `private` | `directory`; semantics §2.8), created_at,
|
||||
updated_at. N per deployment (D2).
|
||||
created_at, updated_at. N per deployment (D2).
|
||||
2. `estates` — id, name, slug, `company_id` NOT NULL →
|
||||
`companies.id` ON DELETE RESTRICT. Exactly one company per estate; a
|
||||
company holds any number of estates.
|
||||
@@ -168,31 +142,6 @@ decision under A1; this contract pins only that they stay distinct tables.)
|
||||
free-form payload field. The columns declared in this section and §3
|
||||
are exhaustive: a class table's column set is exactly its declared set
|
||||
(verified per §6.2) — nothing else (A1 §8.1.2).
|
||||
8. **Company visibility classes (Ruling 4b).** Every company is exactly
|
||||
one of two classes, carried by `visibility`:
|
||||
- `private` (the default): the company is disclosed only to subjects
|
||||
holding a grant on it or on a descendant — the resting state every
|
||||
company is created in. Open creation under contract 3 §5.2
|
||||
(Ruling 4) survives unchanged: it creates private companies.
|
||||
- `directory`: the company is listed in the deployment-wide company
|
||||
directory. Directory listing discloses **existence, name, and slug
|
||||
to every authenticated user — nothing else**: no subtree structure,
|
||||
no roll-up aggregates, no workspace content, no grant or membership
|
||||
information.
|
||||
Visibility is disclosure, not authority. Content and structure access
|
||||
to a directory-listed company still require explicit grants —
|
||||
contract 2 §3.1 deny-by-default is unchanged, and the ownership model
|
||||
(§4.4, contract 2 §4.3) is unchanged. Ruling 4b decision 5 wants a
|
||||
see-and-ask-to-join flow for directory-listed companies. **This
|
||||
contract authorizes no join-request runtime surface**: the flow in
|
||||
its entirety — the ability to submit a request, its transport,
|
||||
storage, and request lifecycle — is a follow-up contract, and until
|
||||
that contract ratifies, the directory's only function is the
|
||||
read-only listing above (A2 §9.1.2 admits nothing more). Two
|
||||
invariants pre-bind that future contract now:
|
||||
a join request confers no authority of any kind, and approval is
|
||||
ordinary grant creation by an effective `owner` under contract 2 §4.1
|
||||
— there is no other acceptance path.
|
||||
|
||||
## 3. Grant attachment points
|
||||
|
||||
@@ -274,8 +223,7 @@ shape contract 2 attaches to:
|
||||
2. **Audit parity.** A1 §8.2 leaves every pre-existing REQ binding, so
|
||||
hierarchy mutations get REQ-AUD-001's guarantees, not a weakened
|
||||
substitute. Concretely:
|
||||
- Every create, rename, transfer, visibility change (§5.5), grant
|
||||
create/change/revoke, and
|
||||
- Every create, rename, transfer, grant create/change/revoke, and
|
||||
delete — including every grant deletion cascaded by a node delete —
|
||||
emits a semantic audit event carrying actor, verb, target, and (for
|
||||
transfers) source and destination parents, with the correlation,
|
||||
@@ -300,25 +248,6 @@ shape contract 2 attaches to:
|
||||
workspace work. Contract 8 owns projection details but cannot narrow
|
||||
this rule. This contract additionally guarantees the chain roll-ups
|
||||
aggregate over is unique and non-null (§2.5).
|
||||
5. **Visibility administration (Ruling 4b decisions 2–3).** Changing
|
||||
`companies.visibility` is a hierarchy mutation through the §5.1
|
||||
command path, audited per §5.2 (the event carries the old and new
|
||||
visibility values as its semantic content). It is authorized for
|
||||
exactly two actor classes: platform admins (`users.role = 'admin'`)
|
||||
and subjects holding the company-CRUD capability that a follow-up
|
||||
amendment to contract 2 will define — until that amendment ratifies,
|
||||
the capability class is empty and the command is admin-only.
|
||||
A company `owner` as such may NOT change visibility: standard users
|
||||
cannot publish a company into the directory. This is the one
|
||||
hierarchy mutation a platform admin performs without holding a
|
||||
hierarchy grant, and it is ratified here as instance administration
|
||||
(directory curation) in contract 2 §1.1's sense, not tenant access:
|
||||
the command mutates the single `visibility` column, reads no tenant
|
||||
content, and confers no grant — contract 2 §1.1's
|
||||
no-implicit-tenant-access rule is otherwise untouched. Top-level
|
||||
company creation (contract 3 §5.2) always creates
|
||||
`visibility = 'private'`; the creation command cannot set or change
|
||||
visibility.
|
||||
|
||||
## 6. Verification requirements
|
||||
|
||||
@@ -335,10 +264,7 @@ Binding on the implementing PRs (extends A1 §8.3):
|
||||
witnessed (zero and two set → refused). Grant uniqueness: a duplicate
|
||||
(subject, target, role) row refused for each of the six subject×target
|
||||
forms, proving NULLS-NOT-DISTINCT semantics; NOT NULL on `role`,
|
||||
`granted_by`, and all `name`/`slug` columns witnessed. Company
|
||||
visibility (§2.8): a value outside `private`/`directory` refused with
|
||||
both valid values accepted as the control; an insert omitting the
|
||||
column defaults to `private`.
|
||||
`granted_by`, and all `name`/`slug` columns witnessed.
|
||||
2. Column allowlist: an information_schema assertion that each class
|
||||
table's column set is exactly the set declared in §2/§3 — the bounded
|
||||
observable for no-payload (§2.7) and no-`owner_id` (§4.4).
|
||||
@@ -420,19 +346,9 @@ Binding on the implementing PRs (extends A1 §8.3):
|
||||
static analysis cannot see, and any such evasion found later is
|
||||
corrected as a conformance defect, not grandfathered.
|
||||
4. Audit witnesses: for each mutation class (create, rename, transfer,
|
||||
visibility change, grant create/change/revoke, delete) — the event
|
||||
exists after commit
|
||||
with actor/verb/target and same-transaction atomicity, and the
|
||||
event's outbox record exists after the same commit — state row,
|
||||
audit event, and outbox record are witnessed as one transaction
|
||||
(REQ-AUD-001); a rolled-back
|
||||
mutation leaves no event, no outbox record, AND no state effect —
|
||||
a rolled-back create leaves no row, a rolled-back rename, transfer,
|
||||
or visibility change leaves the prior values in place, and a
|
||||
rolled-back delete or grant revoke leaves the row present
|
||||
(rollback witness on all three legs, per REQ-AUD-001's
|
||||
commit-or-roll-back-together acceptance); a
|
||||
node delete's cascaded
|
||||
grant create/change/revoke, delete) — the event exists after commit
|
||||
with actor/verb/target and same-transaction atomicity; a rolled-back
|
||||
mutation leaves no event (rollback witness); a node delete's cascaded
|
||||
grant deletions are each covered by events; events survive deletion of
|
||||
their target (query the events of a deleted node).
|
||||
5. Transfer tests: parent-FK update moves the subtree resolution and
|
||||
@@ -452,30 +368,10 @@ Binding on the implementing PRs (extends A1 §8.3):
|
||||
endpoints mutate no canonical state anywhere (assert zero writes across
|
||||
hierarchy AND workspace tables, not hierarchy only); readers see
|
||||
aggregates only over workspaces they are authorized on, with no
|
||||
cross-tenant existence oracles (A1 §8.3 acceptance 3, as narrowed by
|
||||
A2 §9.1.2) beyond the one
|
||||
ratified carve-out — the §2.8 company directory, witnessed in §6.9.
|
||||
cross-tenant existence oracles (A1 §8.3 acceptance 3).
|
||||
8. Real-PostgreSQL coverage for every constraint witness (unique/CHECK/
|
||||
RESTRICT/NULLS NOT DISTINCT behavior), using the `ci-postgres` service
|
||||
in the `test` CI step; mocked specs cannot witness database constraints.
|
||||
9. Visibility witnesses (§2.8, §5.5): the directory read returns exactly
|
||||
the `visibility = 'directory'` companies to any authenticated user,
|
||||
disclosing existence, name, and slug only (closed-field assertion on
|
||||
the response shape); a private company never appears in the directory
|
||||
for a reader without a grant on it (with the control: it appears in
|
||||
that reader's granted-structure reads); a directory-listed company's
|
||||
subtree, aggregates, and content remain refused for a non-granted
|
||||
reader (disclosure ≠ authority); the visibility command is refused
|
||||
for a non-admin actor — including an effective `owner` of the target
|
||||
company — with the platform-admin accept control; top-level creation
|
||||
yields `visibility = 'private'` and accepts no visibility argument;
|
||||
each visibility change emits its §5.2 audit event carrying old and
|
||||
new values — the full audit pattern for the mutation class
|
||||
(same-transaction atomicity of state row, audit event, and outbox
|
||||
record; rollback leaving no state effect, no event, and no outbox
|
||||
record; actor/verb/target) is §6.4's, which enumerates
|
||||
visibility change; this item adds only the old/new-value payload
|
||||
assertion.
|
||||
|
||||
## Ruling request
|
||||
|
||||
|
||||
@@ -456,61 +456,3 @@ this line is weakened.
|
||||
- Negative tests prove roll-up endpoints cannot mutate state and that a
|
||||
reader sees aggregates only over workspaces they are authorized on
|
||||
(no cross-tenant existence oracles).
|
||||
|
||||
## 9. Amendment A2 — company visibility classes and the company directory
|
||||
|
||||
**Status:** amendment to Amendment A1, added by reviewed PR under Ruling 4b
|
||||
(operator ruling, 2026-08-27; decision owner Jason; recorded in the webui-audit
|
||||
lane RULINGS.md). Everything in §§1–8 remains binding verbatim, with exactly
|
||||
the two express modifications below. Nothing else is weakened. The detailed
|
||||
contract text lives in the hierarchy schema contract
|
||||
(`hierarchy-schema.md` §2.8, §5.5, §6.9); this amendment changes only what A1
|
||||
itself permits, so that contract does not stretch A1 by interpretation.
|
||||
|
||||
### 9.1 What A2 modifies in A1
|
||||
|
||||
1. **Class data (extends §8.1.2's first constraint).** The tenancy/authorization
|
||||
structure record class additionally carries **visibility-class data**: the
|
||||
single column `companies.visibility`, values `private` | `directory`
|
||||
(hierarchy schema §2.8). Visibility is disclosure data about the class's own
|
||||
nodes — what a company row reveals about its own existence — and is part of
|
||||
the class's tenancy/authorization purpose. It is not business or
|
||||
orchestration payload. §8.1.2's payload prohibition is widened for nothing
|
||||
else: hierarchy tables still MUST NOT carry task, plan, or any other
|
||||
business/orchestration payload, and this amendment admits exactly this one
|
||||
column.
|
||||
2. **The company directory (extends §8.1.3's function enumeration).** The
|
||||
hierarchy serves one additional, express, narrow runtime function: the
|
||||
**company directory** — a read-only disclosure listing of exactly the
|
||||
companies whose `visibility = 'directory'`, revealing existence, name, and
|
||||
slug to every authenticated user of the deployment and nothing else. It
|
||||
mutates nothing, confers no authority, evaluates no grant down the chain,
|
||||
and aggregates nothing (it is not a roll-up). §8.3's
|
||||
no-cross-tenant-existence-oracle acceptance is narrowed by exactly this one
|
||||
ratified carve-out: the directory is the sole permitted existence
|
||||
disclosure, and it discloses only directory-class companies (witnessed in
|
||||
hierarchy schema §6.7 and §6.9). Private companies remain undisclosed to
|
||||
non-granted subjects everywhere, including the directory.
|
||||
|
||||
### 9.2 What A2 explicitly does not change
|
||||
|
||||
1. Content access stays grant-only under the RBAC grant model contract:
|
||||
directory listing discloses existence, never content, membership, or any
|
||||
authority (Ruling 3 unchanged; hierarchy schema §2.8).
|
||||
2. **No join-request surface is authorized.** Ruling 4b decision 5's
|
||||
see-and-ask-to-join flow is a follow-up contract in its entirety —
|
||||
including the ability to submit a request. A2 admits exactly the
|
||||
read-only listing of §9.1.2 and nothing more; hierarchy schema §2.8
|
||||
states the invariants that pre-bind the future flow contract, and that
|
||||
contract must itself amend this enumeration before any join-request
|
||||
runtime surface exists.
|
||||
3. Visibility changes are hierarchy mutations on the existing §8.2.3 audited
|
||||
mutation path — audited maintenance of the class's own structure in
|
||||
§8.1.3's sense, not a further runtime function. Authorization for them is
|
||||
defined in hierarchy schema §5.5 (platform admins plus the future
|
||||
company-CRUD capability; owner-as-such cannot publish).
|
||||
4. Company creation is unchanged and always yields `visibility = 'private'`
|
||||
(onboarding wizard §5.2); this amendment adds no creation path and no
|
||||
default-open disclosure.
|
||||
5. Every other constraint of A1 — §8.1.2's remaining bullets, §8.2 in full,
|
||||
and §8.3's other acceptance criteria — is untouched.
|
||||
|
||||
@@ -397,14 +397,6 @@ seed-workspace-scoped mutant, correctly refusing outside the seed
|
||||
set, passes branch (c), so the two branches detect distinct
|
||||
mutants. No other change.
|
||||
|
||||
Amendment 1 (Ruling 4b, 2026-08-28): §5.2's embedded decision was RULED
|
||||
AGREED (Jason, 2026-08-27), and Ruling 4b adds company visibility
|
||||
classes (hierarchy schema §2.8): open top-level creation always yields
|
||||
a **private** company; publishing a company into the deployment-wide
|
||||
directory is a separate, gated visibility mutation (hierarchy schema
|
||||
§5.5) that is never part of the creation command. §5.2 is amended to
|
||||
state both.
|
||||
|
||||
Scope: the Gateway-backed product onboarding wizard. Out of scope: the
|
||||
host-local install wizard (`mosaic wizard`, which drives host install and
|
||||
gateway bootstrap and is not this artifact — audit REPORT.md layer 3);
|
||||
@@ -1177,18 +1169,15 @@ collects no sensitive category, so v1 ships no custody surface.
|
||||
party, service actor, or wizard-privileged writer exists in this
|
||||
flow.
|
||||
2. **Post-bootstrap top-level company creation** — the "N companies" flow
|
||||
— RULED AGREED (Jason, 2026-08-27): any **eligible platform user** MAY
|
||||
— is decided by the ruling below: any **eligible platform user** MAY
|
||||
create a top-level company and MUST name an initial `owner` grant in
|
||||
the same audited operation (contract 2 §4.3); the creator naming
|
||||
themselves is the default. Eligible means, in identity-contract
|
||||
terms: an authenticated account (identity §2) that is not banned
|
||||
(identity §7.1 — deactivation on this platform IS the better-auth
|
||||
ban; no separate deactivated state exists). No further role or grant
|
||||
is required. Creation always yields a **private** company
|
||||
(`visibility = 'private'`, hierarchy schema §2.8, Ruling 4b): the
|
||||
creation command accepts no visibility argument, and publishing into
|
||||
the deployment-wide directory is a separate, gated mutation
|
||||
(hierarchy schema §5.5) that standard users cannot perform.
|
||||
is required. Until that ruling, deny-by-default holds (contract 2
|
||||
§3.1): no implicit creation authority exists.
|
||||
3. Child-node creation inside the wizard (estate, project, workspace
|
||||
under the seeded company) follows contract 2 §4.3: parent
|
||||
`owner` authority, no automatic grant needed — for canonical seed
|
||||
@@ -1943,13 +1932,7 @@ contracts and are not additions:
|
||||
suffix at all — each contradicting PRD D4's no-lock-in
|
||||
requirement (§4.4).
|
||||
|
||||
## Ruling request — RULED AGREED (Jason, 2026-08-27; Amendment 1)
|
||||
|
||||
The §5.2 decision below was ruled agreed: open eligible-user creation
|
||||
stands (yielding private companies per Amendment 1), and the
|
||||
"alternative if rejected" did not take effect. The request is retained
|
||||
below as historical record of what was put to ruling; it is no longer
|
||||
live.
|
||||
## Ruling request
|
||||
|
||||
Ratify sections 1–7 as written, with one decision embedded:
|
||||
|
||||
|
||||
@@ -1,259 +0,0 @@
|
||||
# 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".
|
||||
|
||||
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).
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user