From c66cd58846994208e509134cd7aa7e93c47c97b8 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 10 Nov 2026 12:46:18 -0600 Subject: [PATCH 1/3] docs(plans): accounts design draft 3, rights-based membership (#1873) Applies Jason's three rulings of 2026-11-10. Named rights, role bundles and per-member grants replace the fixed owner and member split. A member holds org.view, thread.read and board.read by default. decide and task.write are grantable. The rights table lands first as slice M1. --- docs/plans/2026-11-10_accounts-design.md | 846 +++++++++++++++-------- 1 file changed, 573 insertions(+), 273 deletions(-) diff --git a/docs/plans/2026-11-10_accounts-design.md b/docs/plans/2026-11-10_accounts-design.md index 5f0cf7fa0..520cf600d 100644 --- a/docs/plans/2026-11-10_accounts-design.md +++ b/docs/plans/2026-11-10_accounts-design.md @@ -1,9 +1,10 @@ # Accounts, membership and invites: design (Phase M, #1873) -Status: draft 2 for the lead, lane org-m-design, 2026-11-10. Design only. -Nothing here changes source, roles, contracts or a schema until a build -slice in section 9 is granted. Draft 2 is the one fix round after the luna -and sol reviews. The change list is at the end. +Status: draft 3 for the lead, lane org-m-design-3, 2026-11-10. Design +only. Nothing here changes source, roles, contracts or a schema until a +build slice in section 9 is granted. Draft 3 applies Jason's three rulings +of 2026-11-10 and replaces the fixed owner and member split with named +rights. The change list is at the end. Owner words: "The deployed system has user sign-in. Users create organizations, belong to any number of them, and can be invited into another @@ -16,6 +17,9 @@ draft 2 REQ-ACCT-1, REQ-ACCT-2, REQ-USER-1, REQ-WS-2 and REQ-WEB-3 `docs/prd/mosaic-stack.md:1446`; Q203 in `docs/plans/2026-10-21_bundled-pocket-id.md:9`; the 2026-11-07 rulings 2, 3, 5 and 11 in `docs/plans/2026-11-07_organizations-owner-rulings.md`. +Jason's rulings of 2026-11-10 on members deciding, invite binding, and +board read and task write, recorded in "Owner rulings, 2026-11-10" at the +end. All file:line references are at BASE `8630b8dfc`. @@ -196,7 +200,9 @@ and the bus is an instance-wide list, which cannot express two users who own different orgs. The granted-user path from FED R6 has the right shape for a member: a live grant, re-read per request, carried to the bus over a separate transport that the bus checks again. And that member path today -reaches threads only, not the board. +reaches threads only, not the board. Jason's rulings of 2026-11-10 make +board reads, task writes and deciding grantable rights, so section 3 adds +named rights on top of that path. ## 2. Accounts @@ -344,30 +350,93 @@ The session caps at `sso.mjs:22` rise from 64 sessions and 32 logins to 512 and 128, with a cap of 8 sessions per account. The oldest session of that account is evicted first. -## 3. Membership in N organizations +## 3. Membership and rights in N organizations + +### The owner rulings this section follows + +Jason ruled on draft 2's three open questions on 2026-11-10. Verbatim: + +1. On members deciding: "This should be a grantable right with RBAC. + Default is owner yes, member no." +2. On an email-domain invite binding: "agreed". Invites bind to one + verified email or one subject, never to a domain. +3. On member board reads and task writes: "Similar to 1. grantable right + via RBAC. Default owner R/W, member R". + +Draft 2 had a fixed split: the owner did everything, a member got threads +and nothing else. Draft 3 replaces that split with named rights, roles that +bundle them, and per-member rights the owner adds or removes. + +### Rights + +A right is a name that `checkOrgAccess` and the org bus check. One module, +`packages/organization/src/org-rights.mjs`, holds the whole table. The +Console and the bus both import it, so they cannot disagree on what a right +allows. + +| Right | What it allows | Grantable | +| --- | --- | --- | +| `org.view` | See the org in lists and the U1 read, with its label, theme and the projects in scope. Bus verbs `project.list` and `names`. | Comes with every membership and cannot be removed | +| `thread.read` | Read threads. Bus verbs `thread.list` and `thread.messages`, and the chat's `plugins` read. | Yes | +| `thread.write` | Open, create, send and share threads. Bus verbs `thread.open`, `thread.create`, `thread.send`, `thread.share`, `thread.unshare` and `thread.shares`, at the collaborator level the broker already uses (`broker.mjs:182-184`). | Yes | +| `board.read` | The U1 board sections `inbox`, `agents`, `thread.claims`, `tasks`, `usage`, `limits` and `decisions`, and the request reads `request.get.console`, `request.projects.console`, `request.artifact.console` and `request.workspace.console`. | Yes | +| `task.write` | The U4b task writes, create, move, edit and archive, through the task verbs (`packages/tasks/src/store.mjs:58-143`). | Yes | +| `decide` | `decision.preview.console`, `decision.resolve.console` and `prd.revoke.console`. | Yes | +| `request.write` | The owner's intake controls `request.answer.console`, `request.attach.console`, `request.cancel.console`, `request.mode.console` and `request.draft.console`. | Yes | +| `members.manage` | Create, list and revoke invites, remove members, change a member's rights. | No, owner only | +| `org.setup` | The org admin and setup routes (`serve.mjs:802-805`), `plugins.set`, `system-types.console` and `project.remote.get.console` and `.set.console`. | No, owner only | +| `org.lifecycle` | Archive, restore, delete and restart the org. | No, owner only | + +The lead asked for decide, board read and task write plus whatever today's +owner-only operations need. `request.write` and the three reserved rights +are those operations. + +Three rights stay with the owner, and I think they should: + +- `members.manage`, because granting is the owner's alone. A member who + could grant could widen themselves. +- `org.setup`, because setup changes the plugins and bus configuration that + run as the org's `human`, which is the owner's account. A member holding + it would act with the owner's identity on the human transport. +- `org.lifecycle`, because delete cannot be undone and removes every + member. + +Making any of them grantable later is a separate owner decision. The table +has a `grantable` flag per right, so that change is one reviewed line plus +its tests. + +Every bus verb a member can reach has exactly one entry in +`VERB_RIGHTS`, the verb-to-right map in the same module. A verb with no +entry refuses every member. That includes verbs added later, until someone +maps them in a reviewed commit. ### Roles -An org has exactly one owner account and any number of members. +A role is a named bundle of rights, a constant in `org-rights.mjs`: -- **Owner.** The account that holds the subject in the org's `owner.json`, - by the rule below. `owner.json` is set once, at create, by the creating - account (`org-service.mjs:160`), and nothing rewrites it. The owner reads - and writes everything in the org, decides, invites, removes members, - changes grants, archives, restores and deletes. -- **Member.** An account with a membership row for the org. A member carries - a REQ-USER-3 grant: `projects`, `instances` and a `level`, `collaborator` - or `viewer`, with an optional `expires`. What a member can do on the bus - is set by the transport table below, which is narrower than "everything - in the grant" until slice M8. A member never decides, invites, changes - grants or touches org setup. +| Role | Rights | +| --- | --- | +| `owner` | Every right, reserved ones included. It comes only from `owner.json`. Nobody can be granted it. | +| `member` | `org.view`, `thread.read`, `board.read`. The default for invites. | +| `collaborator` | `member` plus `thread.write` and `task.write`. | +| `approver` | `collaborator` plus `decide` and `request.write`. | -Owner transfer and a second owner are out of the MVP. They change who may -rewrite `owner.json`, which is a separate decision. +So the defaults match the rulings. The owner has every right. A member +reads the board and its threads, and cannot decide or write tasks. -Decisions stay owner-only because today's code already makes them so -(`cli.mjs:167`), and REQ-USER-3 keeps "restructures the organization" with -the owner. Letting a collaborator decide is a later grant level. +I read ruling 3's "member R" as read on the board and on threads, with no +write of any kind. Draft 2 let an invite give thread write by default. Now +thread write is a grantable right, bundled in `collaborator`. + +A role is a template, not a live reference. The membership stores the +expanded list of rights, and nothing evaluates the role name. So a later +code change to a bundle changes no existing member. The cost is that an +improved bundle does not reach existing members until the owner applies the +role again. I chose that because one code change silently widening every +member in every org is the escalation path I most want closed. + +Custom roles per org are out of the MVP. Adding or removing rights on one +member gives the owner the same result. ### The ownership rule @@ -380,26 +449,26 @@ this org". It is true when the account is active and some subject through every provider on the same account. A different account never matches, because a subject belongs to one account. +`owner.json` is set once, at create, by the creating account +(`org-service.mjs:160`), and nothing rewrites it. Owner transfer and a +second owner are out of the MVP. They change who may rewrite `owner.json`, +which is a separate decision. + The same rule runs at all three boundaries: -- `checkOrgAccess`, step 3 below. +- `checkOrgAccess`, step 4 below. - `org-service`. In accounts mode, the owner check in `readCurrentUnlocked` (`org-service.mjs:129`) calls `ownsOrg` with the caller's account instead of comparing one principal. -- The org bus. Its console-call check derives `consoleOwners` per call from - `owner.json` and accounts.json: every subject of the account that owns - the org, each with its configured issuer. The Console sends the subject - it verified at sign-in, and the bus matches it against that list. Nothing - in the request names the account. The bus already re-reads access.json - per request (`packages/bus/src/runtime.mjs:693`), and this read uses the - same reader. +- The org bus, on the console transport, described under "Which transport + carries which call". Removing a subject from an account bumps `authGen`, which ends the Console sessions of that subject, and the bus's next console call no longer -lists it. If the removed subject is the one in `owner.json`, the account -still owns the org through its other subjects. If it was the account's -last subject, the account cannot sign in, and `mosaic accounts user remove` -refuses while it owns orgs (section 5). +maps it to the account. If the removed subject is the one in `owner.json`, +the account still owns the org through its other subjects. If it was the +account's last subject, the account cannot sign in, and +`mosaic accounts user remove` refuses while it owns orgs (section 5). ### The business human @@ -432,34 +501,75 @@ it gets a new random incarnation, so old rows grant nothing even if their cleanup failed. The `created` timestamp is not used for this, since two reservations in the same millisecond would share it. -### The membership record +### Where rights live: the membership record ```json { "org": "acme", "incarnation": "5c1e0f3a9b7d2e4c8a6f1b3d5e7c9a0b", "user": "u-77aa01bc9e3d", - "grant": { "projects": ["*"], "instances": ["*"], "level": "collaborator", "expires": "2027-01-01T00:00:00Z" }, + "role": "member", + "rights": ["board.read", "org.view", "task.write", "thread.read"], + "scope": { "projects": ["*"], "instances": ["*"], "expires": "2027-01-01T00:00:00Z" }, + "rev": 2, "added": "2026-11-13T09:00:00Z", "by": "u-3f9c2a71d04e", "via": "invite:9b0e..." } ``` +This member started from the `member` role, and the owner then added +`task.write`. + +- `role` is the bundle the owner last applied. The UI shows it. No check + reads it. +- `rights` is exactly what the member holds. The loader requires it sorted, + with no duplicates, containing `org.view`, and naming no reserved right. + A row that breaks one of these is malformed. A name this build does not + know is not malformed, and the next subsection covers it. A write + normalizes `rights` the same way. +- `scope` replaces draft 2's `grant` without `level`. `projects` and + `instances` follow the REQ-USER-3 scope rules, a `"*"` or a list, and + `expires` is optional. The bus level now comes from the rights. +- `rev` starts at 1 and goes up by one on every change to `rights` or + `scope`. + The owner has no membership row. Ownership comes only from `owner.json`, so no write to accounts.json can create an owner. +### An unknown right fails closed + +Four rules cover a right name the running code does not know: + +- The loader still refuses the whole file for a malformed row. A row that + is well formed but names a right or role this build does not know grants + nothing. `memberGrant` returns nothing for it, so `checkOrgAccess` treats + the account as a non-member and the bus drops the row. The owner's member + list shows that row as needing repair, naming the unknown right. I made + this per row rather than whole-file on purpose. A rollback to a build that + knows fewer rights should cut off the members it cannot read, not sign + every account on the instance out. +- Every write refuses an unknown right, an unknown role and a reserved right + before it changes anything. +- A caller that asks `checkOrgAccess` for a right that is not in the table + gets `unknown-right`. That is a code bug, and it refuses. A test pins the + right name at every call site. +- A bus verb with no `VERB_RIGHTS` entry refuses every member. A test pins + that every verb in `CONSOLE_VERBS`, `USER_VERBS`, `BOARD_VERBS` and the + task verbs is either mapped or listed as owner-only. + ### From a membership row to a grant -The nested `grant` is not a FED grant document. `covers` needs `business` -and the broker needs `user`. One adapter, `memberGrant(row, registry, -accounts)`, builds the only grant document that the Console and the bus -use for members: +`covers` needs `business` and the broker needs `user`. One adapter, +`memberGrant(row, registry, accounts)`, builds the only grant document the +Console and the bus use for members: ```js { id: `m-${row.org}-${row.user}`, user: row.user, business: row.org, - projects: row.grant.projects, instances: row.grant.instances, - level: row.grant.level, expires: row.grant.expires } + projects: row.scope.projects, instances: row.scope.instances, + expires: row.scope.expires, + level: row.rights.includes('thread.write') ? 'collaborator' : 'viewer', + rights: row.rights, rev: row.rev } ``` It returns nothing, so the row grants nothing, when any of these hold: @@ -467,9 +577,11 @@ It returns nothing, so the row grants nothing, when any of these hold: - The row's `(org, incarnation)` is not the registry entry's. - The account is missing or disabled. - The user is the org's business `human`. -- The grant fails the access.json grant rules +- A right or the role is unknown to this build. +- The scope fails the access.json scope rules (`packages/organization/src/access.mjs:121`) against the org's current projects and instances. +- `expires` has passed. ### The one check: `checkOrgAccess` @@ -478,51 +590,110 @@ Console org-scoped and cross-org read and write: ```js checkOrgAccess(ctx, { principal, account, org, need }) -// need = { action: 'discover' | 'read' | 'write' | 'decide' | 'admin' -// | 'lifecycle', project?, instance? } -// returns { org, role: 'owner' | 'member', grant | null, account } -// throws OrgError('org-unavailable') or OrgError('org-forbidden') +// need = { right, project?, instance? } +// returns { org, role: 'owner' | 'member', rights, scope, rev, account } +// throws OrgError('unknown-right'), OrgError('org-unavailable') +// or OrgError('org-forbidden') ``` It runs these steps in order and stops at the first refusal: -1. Mode. `ctx.mode` is `dev` or `accounts`, fixed at process start +1. Right. `need.right` must be in the table. Otherwise `unknown-right`. +2. Mode. `ctx.mode` is `dev` or `accounts`, fixed at process start (section 6). In `dev` the principal must be `DEV_OWNER` and there is no account. In `accounts` the principal must not be `DEV_OWNER` and `account` must be an active account re-read from accounts.json now, with the session's `authGen`. -2. Org. Read the registry. The org must exist. State `active` passes. State - `archived` passes only for an owner with `need.action === 'lifecycle'` - (restore, delete, show state). Anything else is `org-unavailable`. -3. Role. Read `owner.json` through `privateRead`. In accounts mode, - `ownsOrg` true means `owner`. In dev mode, a match with `DEV_OWNER` - means `owner`. -4. Membership. If not the owner, take `memberGrant` for `(org, - incarnation, account.id)`. None means `org-unavailable`, the same answer - as an org that does not exist. -5. Need. `admin`, `decide` and `lifecycle` need `owner`. For a member: - - `discover` passes with any live grant. It lets the org appear in - lists and the U1 read, and nothing else. - - `read` and `write` name a concrete target. They run `covers(grant, - {business: org, project, instance}, now, {level})` with the real - project and instance, at `viewer` for `read` and `collaborator` for - `write`. - - A target with a project and no instance, such as a task or a project - thread, follows the broker's convention at `broker.mjs:1653-1660`: the - instance is the grant's first instance. So a project-only target needs - the project covered and widens nothing. - - A member who fails this step gets `org-forbidden`, since the member - already knows the org exists. +3. Org. Read the registry. The org must exist. State `active` passes. State + `archived` passes only for an owner whose need is `org.lifecycle`. + Anything else is `org-unavailable`. +4. Owner. Read `owner.json` through `privateRead`. In accounts mode, + `ownsOrg` true means the owner, who holds every right, and the check + passes. In dev mode a match with `DEV_OWNER` does the same. +5. Member. Take `memberGrant` for `(org, incarnation, account.id)`. None + means `org-unavailable`, the same answer as an org that does not exist. +6. Held. `need.right` must be in the grant's `rights`. Otherwise + `org-forbidden`, since the member already knows the org exists. A + reserved right always ends here for a member, because no member row can + hold one. +7. Scope. Where the target sits decides the scope test: + - No target, as for `org.view` when listing orgs, passes. + - A target with a project runs `covers(grant, {business: org, project, + instance}, now, {level})`. The level is `collaborator` for + `thread.write` and `viewer` for every other right. A target with a + project and no instance takes the grant's first instance, the broker's + convention at `broker.mjs:1653-1660`. + - A target with no project needs a whole-org scope, `projects: ["*"]` + and `instances: ["*"]`. That covers the store's tasks, which have no + project (`packages/tasks/src/store.mjs:13-14`), the `agents`, `usage` + and `limits` reads, and a decision that names no project. A member + with a narrower scope gets `org-forbidden` for those. It reads accounts.json, the registry and `owner.json` on every call and -caches nothing across requests. A revoke counts on the next request. +caches nothing across requests. `org-service.mjs` keeps its own guard at the data layer. `authorize(ctx)` (`:19`) becomes: in `dev` mode, today's check; in `accounts` mode, the context carries an active account. `createOrg` is open to any active account. Update, archive, restore and delete still run the owner check in -`readCurrentUnlocked`, now through `ownsOrg`. So a bug in the HTTP layer -cannot let a member restructure an org. +`readCurrentUnlocked`, through `ownsOrg`. Those operations need reserved +rights, which only the owner holds, so the service's owner check is exactly +the right check. A bug in the HTTP layer cannot let a member restructure an +org. + +### Who may grant + +- Only the owner changes a member's rights or scope. The write needs + `members.manage`, which is reserved, so only the owner holds it. +- The rights granted must be a subset of the granter's own rights. + `canGrant(granterRights, rights)` runs inside the accounts lock with the + granter's rights read fresh. The owner holds every right, so today this + limits the owner to grantable rights. The check stays so that a granter + added later can never hand out more than they hold. +- `owner`, `members.manage`, `org.setup` and `org.lifecycle` are never + grantable. A request or invite naming one refuses `right-not-grantable`. +- The scope must be `"*"` or a subset of the org's current projects and + instances. +- A member cannot change their own row. Leaving is the only change a member + makes to it. +- Every change appends a receipt with the actor, the org, the user, the + rights and scope before and after, and the new `rev`. + +The route is `POST /api/orgs/:id/members/:user/rights` with +`{role?, add?, remove?, scope?, rev}`, behind the Origin and +`Sec-Fetch-Site` fence. It starts from the role's bundle when `role` is +given and from the current rights otherwise, adds `add`, removes `remove`, +and refuses a removal of `org.view`. `rev` must equal the row's current +`rev`, or the write refuses `member-changed` and the owner sees the current +row. It runs under the registry lock and then the accounts lock. + +### How a change reaches live sessions + +Nothing caches rights. `checkOrgAccess` re-reads accounts.json on every +Console request, and the org bus re-reads member grants on every call +through `memberGrant` (`packages/bus/src/runtime.mjs:693` is the existing +per-request reader). So: + +- A removed right refuses at the member's next Console request and next bus + call, inside a session that is already open. An added right works at the + next request. +- A rights change does not touch `authGen` and does not sign the member out. + Their other orgs, and their other rights in this org, keep working. +- If the change lands between the Console's check and its bus call, the bus + re-evaluates on the user and console transports and refuses. The human + transport carries only the owner, whose rights never change. +- Two-step actions bind to `rev`. The decide confirmation + (`packages/webui/src/decision-http.mjs:2-5`) is one-use and bound to the + session and the decision. For a member it also records the membership + `rev`. `/resolve` runs `checkOrgAccess` with `decide` again and refuses + `confirmation-required` if `decide` is gone or `rev` moved. Any later + two-step write follows the same rule. +- Streams and long polls re-check before each event and at least every 30 + seconds (section 5). +- Each org response carries the caller's rights so the page can hide + controls the caller lacks. That is a display aid. The server checks every + request whatever the page shows. A widened right shows on the next page + refresh. ### Reading the org document after the check @@ -532,100 +703,117 @@ would drop the registry and digest fences. So `readCurrentUnlocked` splits in two: - The owner compare, which stays for `showOrg` and the write paths. -- `readOrgSnapshot(ctx, id, {role})`, which does everything else +- `readOrgSnapshot(ctx, id, {role, scope})`, which does everything else `readCurrent` does today: the unchanged-registry retry loop (`org-service.mjs:138-151`), root and marker checks, the registry digest compare and the document schema check. It runs only after - `checkOrgAccess` has returned a role. + `checkOrgAccess` has returned. What it returns depends on the role: - Owner: the full document, as today. If the digest or schema check fails, the error carries `ownerVerified` and the list shows the org as broken, as today. -- Member: a public projection, `{id, label, theme, projects}`, where - `projects` holds only the projects the grant covers. If the digest or - schema check fails, the org is left out of the member's list with no - error detail. +- Member: a projection, `{id, label, theme, projects}`, where `projects` + holds only the projects the scope covers. If the digest or schema check + fails, the org is left out of the member's list with no error detail. ### Which transport carries which call -This table is the contract M3 and M4 build. The human transport is -`busCaller` (`packages/webui/src/bus.mjs:90`), the console transport is -`consoleCall` (`bus.mjs:75`), and the user transport is `userCaller` -(`bus.mjs:130`). +The human transport is `busCaller` (`packages/webui/src/bus.mjs:90`), the +console transport is `consoleCall` (`bus.mjs:75`), and the user transport +is `userCaller` (`bus.mjs:130`). The Console checks the right first. A +member who lacks it gets the refusal, and nothing goes to the bus. -| Call | Owner | Collaborator member | Viewer member | +| Call | Right | Owner | Member holding the right | | --- | --- | --- | --- | -| U1 `inbox`, `agents`, `thread.claims`, `tasks`, `usage`, `limits`, `decisions` | human | not sent, the section reads "not shared with members" | same as collaborator | -| U1 `chat.projects` | human | user, `project.list` | user, `project.list` | -| U1 `chat.threads` | human | user, `thread.list` | user, `thread.list` | -| Thread open, send, create, share | human | user, the thread verbs | user, `thread.messages` only | -| U4b task create, move, edit, archive | human | refused at the Console, nothing sent, until M8 | refused at the Console | -| Decide | console | refused | refused | -| Request status read | console | refused | refused | -| Chat `plugins` read | human | human, `plugins` only, as today (`console-bus.mjs:20-23`) | same | -| Org setup and lifecycle | org-service | refused | refused | +| U1 `chat.projects`, `names` | `org.view` | human | user, `project.list` and `names` | +| U1 `chat.threads`, thread messages | `thread.read` | human | user, `thread.list` and `thread.messages` | +| Thread open, create, send, share | `thread.write` | human | user, the thread verbs | +| U1 `inbox`, `agents`, `thread.claims`, `tasks`, `usage`, `limits`, `decisions` | `board.read` | human | user, the same board verbs, filtered to the scope by the bus | +| U4b task create, move, edit, archive | `task.write` | human | user, the task verbs | +| Decide | `decide` | console | console | +| Request status reads | `board.read` | console | console | +| Request intake controls | `request.write` | console | console | +| Chat `plugins` read | `thread.read` | human | human, `plugins` only, as today (`console-bus.mjs:20-23`) | +| Org setup, lifecycle, invites, member rights | reserved | org-service and Console | refused | -What each transport trusts: +A U1 section whose right the member lacks reads "not shared with you", and +its read is never sent. -- Human transport. The bus binds it to the business `human`, which is the - owner's account id, and trusts the Console process that holds the - socket, as it does today. The bus does not re-check the owner on these - calls. The Console's `checkOrgAccess` is the gate, and the Console is - already trusted with the human socket for the root business. -- Console transport. The bus checks the subject against that org's - `consoleOwners`, derived by the ownership rule. So a Console bug cannot - make a member decide. -- User transport. The bus checks `USER_VERBS`, `VIEWER_VERBS` and `covers` - against the member grants it loads from accounts.json through - `memberGrant`. So a Console bug cannot widen a member past the thread - verbs or past the grant's projects. +What the bus checks on each transport: -Member task reads and writes and member board reads need new user verbs on -the bus. That widens FED user authority beyond REQ-USER-3, which grants -threads. This design does not do it silently. It is slice M8, and it needs -an owner ruling first (open question 3). +- **Human transport.** The bus binds it to the business `human`, which is + the owner's account id, and trusts the Console process that holds the + socket, as it does today. The bus does not re-check the owner here. The + Console's `checkOrgAccess` is the gate, and the Console is already + trusted with the human socket for the root business. A member reaches + this transport only for the `plugins` read. +- **Console transport.** The Console sends the subject it verified at + sign-in. The org bus maps that subject to an account through + accounts.json, with the issuer from config. The account that owns the org + by the ownership rule passes every console verb. Any other account passes + a verb only when its `memberGrant` holds `VERB_RIGHTS[verb]` and the + target is in scope. This replaces the instance-wide `consoleOwners` list + on org buses. So a Console bug cannot let a member decide without + `decide`, or call a setup verb at all. +- **User transport.** On an org bus, a member's verb passes when its + `memberGrant` holds `VERB_RIGHTS[verb]` and `covers` passes at the right's + level. This replaces the fixed `USER_VERBS` gate for member grants on org + buses only. The root business's access.json users keep `USER_VERBS` and + `VIEWER_VERBS` exactly as today. A board verb answers a member with only + the rows in scope: rows whose project the scope covers, and rows with no + project only for a whole-org scope. +- **Task writes.** The task store admits the organization's roles as + callers today (`packages/tasks/src/store.mjs:8-10`). U4b admits the + owner's Console writes. This design also admits a user-transport caller + whose grant holds `task.write`, and records that user's id as the actor. + The store's field-writer and holder checks run unchanged after that. + +Board reads, task writes and decide for members are new bus authority. They +widen FED user authority past REQ-USER-3, which grants threads. Rulings 1 +and 3 settle the policy. The bus change still needs the lead's grant at +slice M5, and REQ-USER-3 needs a PRD amendment for org members. ### Callers **U1 cross-org read.** `admitted` in `organizations.mjs:10-18` becomes -`checkOrgAccess(..., {need: {action: 'discover'}})` followed by +`checkOrgAccess(..., {need: {right: 'org.view'}})` followed by `readOrgSnapshot`. `list`, `members` and `resolve` keep calling it, so `readWorkspace` keeps its one line, `organizations.members(session, {timeoutMs})` (`workspace-read.mjs:283`), and gets exactly the orgs the -session may discover. Each section's read then follows the transport table. -The refusal at `workspace-read.mjs:336` changes from `owner && session` to -any session with an account. The `org` query filter still applies after -membership, so a query naming a foreign org returns status 200 without it. +session may see. Each section then needs its right from the transport +table. The refusal at `workspace-read.mjs:336` changes from `owner && +session` to any session with an account. The `org` query filter still +applies after membership, so a query naming a foreign org returns status +200 without it. -`organizationConsole` stops being dev-only: `cli.mjs:156` builds it in +`organizationConsole` stops being dev-only. `cli.mjs:156` builds it in both modes, with `ctx.mode` set. **Per-org bus options.** The options builder at `cli.mjs:160-172` picks the -transport from the role `checkOrgAccess` returned, not from -`session.user`, and follows the table. +transport from the role and rights `checkOrgAccess` returned, not from +`session.user`, and follows the table. A member's options carry +`decisionWrite` only when they hold `decide`. **U4b task writes.** The board's write handler, for create, move, edit and -archive, calls `checkOrgAccess(..., {need: {action: 'write', project}})`. -Until M8 only an owner passes, because the handler refuses `member` before -it sends. The owner's write goes over the human transport as today. A +archive, calls `checkOrgAccess(..., {need: {right: 'task.write'}})`. A refusal sends nothing to any bus. A write names exactly one org and goes only to that org's bus. **Per-org decide.** The decide route at `serve.mjs:992-996` calls -`checkOrgAccess(..., {need: {action: 'decide'}})`. Only an owner passes, -and `decisionWrite` exists only on the owner's options (`cli.mjs:167`). +`checkOrgAccess(..., {need: {right: 'decide', project}})`, with the +decision's project when it names one. **Org admin routes.** The hooks at `serve.mjs:802-805` and the -`ORG_OWNER_WRITE` list (`:960-962`) call it with `admin`, or `lifecycle` -for archive, restore and delete. `POST /api/orgs` needs only an active -account. +`ORG_OWNER_WRITE` list (`:960-962`) need `org.setup`, or `org.lifecycle` for +archive, restore, delete and restart. Invite and member routes need +`members.manage`. `POST /api/orgs` needs only an active account. **The assistant.** Phase A's cross-org assistant reads "through the same membership-checked cross-org read the Console uses", which means -`organizations.members` and the transport table. It gets no path of its -own. +`organizations.members` and the transport table, with the user's rights. It +gets no path of its own. **The root business.** It keeps access.json as its grant source and its `console.sso` owners, through the explicit root options in section 2. @@ -647,9 +835,10 @@ OIDC session or an account. The rule: the Console decide route only. - `mosaic accounts ...` is the one local exception. It is a human verb run as the instance uid, the same trust as `mosaic access` today. Anyone who - can run it can already read every bus file, so it adds no authority. An - agent seat runs it only on a scratch instance it owns, never on a - deployed one. + can run it can already read every bus file, so it adds no authority. It + manages accounts, not org rights. Rights change only through the owner's + Console route. An agent seat runs it only on a scratch instance it owns, + never on a deployed one. - Dev mode keeps every CLI verb as it is. ### Locks @@ -671,10 +860,11 @@ holding a later one. - User removal: registry lock, then accounts lock. Inside both, scan every registry entry's `owner.json` with `ownsOrg` and refuse if the user owns one. -- Membership removal, leave and invite create or revoke: registry lock, - then accounts lock, so the org's state cannot change under them. +- Rights changes, membership removal, leave, and invite create or revoke: + registry lock, then accounts lock, so the org's state cannot change under + them. -`withRegistry` is not reentrant. M1 adds `readRegistryLocked(registry)` and +`withRegistry` is not reentrant. M2 adds `readRegistryLocked(registry)` and `withAccountsLocked(fn)`, helpers that take the already-held document instead of locking again. Every accounts write that depends on the registry re-checks the registry it holds just before the atomic replace. Any @@ -689,7 +879,9 @@ mismatch refuses and writes nothing. "id": "9b0e4c1d-...", "org": "acme", "incarnation": "5c1e0f3a9b7d2e4c8a6f1b3d5e7c9a0b", - "grant": { "projects": ["*"], "instances": ["*"], "level": "viewer" }, + "role": "member", + "rights": ["board.read", "org.view", "thread.read"], + "scope": { "projects": ["*"], "instances": ["*"] }, "bind": { "email": "pat@example.com" }, "tokenHash": "sha256 hex", "by": "u-3f9c2a71d04e", @@ -699,10 +891,11 @@ mismatch refuses and writes nothing. } ``` -`state` is `open`, `used`, `revoked` or `declined`. A past `expires` acts -as expired whatever the state says. The next write moves it to `expired`, -and rows that are not open leave the file after 30 days. Their receipts -stay. +`role`, `rights` and `scope` follow the membership rules in section 3, so +an accept copies them into the new row unchanged. `state` is `open`, +`used`, `revoked` or `declined`. A past `expires` acts as expired whatever +the state says. The next write moves it to `expired`, and rows that are not +open leave the file after 30 days. Their receipts stay. ### The token @@ -719,13 +912,14 @@ stay. ### Binding -Every invite carries exactly one binding. There is no bearer-only invite. +Every invite carries exactly one binding. There is no bearer-only invite, +and per ruling 2 of 2026-11-10 there is no email-domain binding. - `{email}`: the accepting ID token must carry `email` equal to it, compared case-insensitively, and `email_verified === true`. A provider that does not assert a verified email cannot accept an email invite. I have not confirmed that the bundled Pocket ID sends `email_verified`. - Slice M5 checks it first. If it does not, Pocket ID users get subject + Slice M6 checks it first. If it does not, Pocket ID users get subject bindings until it does. - `{provider, sub}`: for an existing account or a known subject. The accepting session's provider and `sub` must match exactly. @@ -735,14 +929,17 @@ The account record never stores the email. ### Create -`POST /api/orgs/:id/invites` with `{grant, bind, ttlHours}`. It needs -`checkOrgAccess` with `admin`, plus the Origin and `Sec-Fetch-Site` fence. -`ttlHours` defaults to 72 and must be between 1 and 168. The grant follows -the access.json grant rules (`packages/organization/src/access.mjs:121`) -against the org's projects and instances. The role is always member. The -request has no field that could make an owner. Caps: 32 open invites per -org and 256 per instance. A `{provider, sub}` binding that names a subject -of the owner account or of a current member refuses. +`POST /api/orgs/:id/invites` with `{role, add, remove, scope, bind, +ttlHours}`. It needs `checkOrgAccess` with `members.manage`, plus the +Origin and `Sec-Fetch-Site` fence. `role` defaults to `member`, so an +invite gives read only unless the owner chooses more. The rights are built +and checked exactly as the rights route in section 3 builds and checks +them: `canGrant` against the owner's rights, no reserved right, no unknown +name, a scope inside the org's projects and instances. `ttlHours` defaults +to 72 and must be between 1 and 168. The request has no field that could +make an owner. Caps: 32 open invites per org and 256 per instance. A +`{provider, sub}` binding that names a subject of the owner account or of a +current member refuses. ### Accept @@ -765,30 +962,34 @@ of the owner account or of a current member refuses. subject's account if one exists and its `authGen`. A subject with no account gets a pending session with no account, which is case 3 of "Who can sign in". It reaches only the accept page, decline and logout, and - `checkOrgAccess` refuses it at step 1. A binding mismatch refuses with + `checkOrgAccess` refuses it at step 2. A binding mismatch refuses with `invite-unavailable` and creates no session. A login record without `invite` gets no such exception, so an unknown subject still gets `subject-unknown`. -4. The accept page shows the org's label, the inviter's name and the grant - level. Its two buttons `POST` to `/api/invites/accept` or - `/api/invites/decline`, with an empty body and the same-origin fence. The - invite comes from the session, never from the request. +4. The accept page shows the org's label, the inviter's name, the role and + each right in plain words. Its two buttons `POST` to + `/api/invites/accept` or `/api/invites/decline`, with an empty body and + the same-origin fence. The invite comes from the session, never from the + request. 5. `accept` takes the registry lock and then the accounts lock. It re-checks the invite (open, unexpired, matching incarnation), the - binding, and that the registry entry is active. It refuses if the - accepting account owns the org or is already a member. If the subject - has no account, it creates one as `instanceRole: user`. It adds the - membership with the invite's grant and sets the invite `used`, with the - account and time. All of that is one atomic file replace. Then the - Console drops the pending session and mints a new session id for the - full session, so the id that existed before the account did never - carries the account. + binding, and that the registry entry is active. It checks the invite's + rights again against this build's table and against the inviting + owner's current rights, so an unknown or reserved right, or an inviter + who no longer owns the org, refuses with `invite-unavailable`. It + refuses if the accepting account owns the org or is already a member. If + the subject has no account, it creates one as `instanceRole: user`. It + adds the membership with the invite's role, rights and scope at `rev` 1, + and sets the invite `used`, with the account and time. All of that is one + atomic file replace. Then the Console drops the pending session and mints + a new session id for the full session, so the id that existed before the + account did never carries the account. 6. `decline` sets the invite `declined` and signs the pending session out. ### Revoke and expiry -`POST /api/orgs/:id/invites/:inviteId/revoke` needs `admin`. It sets -`revoked`. Revoking an invite that is not open refuses. +`POST /api/orgs/:id/invites/:inviteId/revoke` needs `members.manage`. It +sets `revoked`. Revoking an invite that is not open refuses. `GET /api/orgs/:id/invites` lists invites for the owner without hashes. Expiry needs no job. Every read compares `expires` with the clock, so an @@ -800,6 +1001,8 @@ own lifetime is 10 minutes. - An unknown, used, revoked, declined, expired or wrong-incarnation token gets the same `invite-unavailable`. +- An invite whose rights this build does not know, or which the inviter + could no longer grant, gets the same answer at accept. - If accounts.json refuses to load, every invite refuses, along with every account sign-in. - Accept holds the registry lock, so an archive or delete cannot commit @@ -835,7 +1038,8 @@ orphans whose incarnation is not in the registry. ### Removing a member -`POST /api/orgs/:id/members/:user/remove` needs `admin`. +`POST /api/orgs/:id/members/:user/remove` needs `members.manage`, which +only the owner holds. `POST /api/orgs/:id/leave` lets a member remove themselves. Both delete the row under the registry and accounts locks. Effects: @@ -854,6 +1058,15 @@ least every 30 seconds, and closes on a refusal. At BASE the Console has no event-stream route, so this is a rule for future routes, and the slice tests it through the workspace refresh. +### Changing a member's rights + +The owner changes a member's role, rights or scope through the rights route +in section 3. The change is one locked write that bumps the row's `rev`. +Nothing is cached, so the member's next Console request and next bus call +use the new rights, and the member stays signed in. A decide confirmation +minted before the change refuses at resolve. Narrowing a member to nothing +is a removal, not a rights change, because `org.view` cannot be removed. + ### Disabling or removing a user An operator disables a user with `mosaic accounts user disable`. The write @@ -926,7 +1139,7 @@ The executable boundary: this instance, and accounts.json loads. The Case 1 and Case 2 installers write `.deployed`. 5. **The unit renderers have no dev flag.** `webui-service.sh` and - `case2-unit.sh` accept no dev flag today (`webui-service.sh:98`). M2 adds + `case2-unit.sh` accept no dev flag today (`webui-service.sh:98`). M3 adds a test that pins it. The instance boundary, which also covers a checkout started by mistake on a @@ -950,7 +1163,7 @@ Inside the process: 10. **No OIDC path to the dev principal.** Its issuer is not https, and `discover` requires https (`sso.mjs:88`, `:108`). No provider can mint it. 11. **The LAN fake.** The `Sec-Fetch-Site` fake at `serve.mjs:855-858` runs - only in dev mode. M2 adds an assert that refuses the start if that path + only in dev mode. M3 adds an assert that refuses the start if that path is reachable while `ctx.mode` is `accounts`. The startup banner "DEV LOCAL OWNER MODE" (`cli.mjs:212`) stays. @@ -1000,6 +1213,11 @@ Rollback keeps OIDC. Nothing in it removes `--sso` or turns sign-in off. the org Console only in dev mode (`cli.mjs:156`). Their data, buses and memberships stay intact and come back on roll-forward. No supported step reaches them on BASE code. +- A rollback between two accounts builds whose rights tables differ is + safe. A row naming a right the older build does not know grants nothing + there, and the owner still reaches the org. If the owner applies a role + on the older build, that replaces the row's rights with a known bundle. + Rows the owner leaves alone come back unchanged on roll-forward. - Never roll back by removing accounts.json on a newer build. Section 2 makes a missing file refuse every account sign-in, which is the fail-closed answer, not a rollback. @@ -1008,25 +1226,32 @@ Rollback keeps OIDC. Nothing in it removes `--sso` or turns sign-in off. | Threat | Control | | --- | --- | -| Cross-org read by a non-member | Every Console org route, the U1 read and the assistant go through `checkOrgAccess`, which re-reads the registry, owner.json and accounts.json per call. A non-member gets the same `org-unavailable` as a missing org, so there is no existence oracle. The `org` query filter applies after membership. On the bus, console calls pass only for the owning account's subjects and user calls only with a covering `memberGrant`. Human-transport calls are trusted to the Console, as today, and the transport table limits them to the owner. Deleted-and-recreated ids do not match old rows because of the random incarnation. | -| Member reaching board data or task writes | The member transport is the user transport, which the bus limits to `USER_VERBS` and `VIEWER_VERBS`. Board reads and task writes are refused at the Console and would be refused `access-refused` at the bus. Widening that is M8, behind an owner ruling. | -| Invite token theft | The token is in the URL fragment, so it stays out of logs and Referer. The store holds only its hash. A stolen token without a matching verified email or exact subject cannot be accepted. Expiry is 72 hours by default and 168 at most. The owner can revoke. | +| Cross-org read by a non-member | Every Console org route, the U1 read and the assistant go through `checkOrgAccess`, which re-reads the registry, owner.json and accounts.json per call. A non-member gets the same `org-unavailable` as a missing org, so there is no existence oracle. The `org` query filter applies after membership. On the bus, console and user calls pass only for the owning account or a covering `memberGrant` that holds the verb's right. Human-transport calls are trusted to the Console, as today, and the transport table limits them to the owner. Deleted-and-recreated ids do not match old rows because of the random incarnation. | +| Member using a right they were not granted | The Console checks the right before it sends anything. The org bus checks it again on the user and console transports from the same `VERB_RIGHTS` table and the same accounts.json row. A verb with no entry refuses every member. A member never gets the human transport except for the `plugins` read. | +| Member granting rights to themselves or others | Changing rights, inviting and removing need `members.manage`, which is reserved and held only by the owner. The accounts write checks the actor's ownership inside the locks, not only at the HTTP layer. A member's change to their own row refuses. | +| Granting more than the granter holds, or a reserved right | `canGrant` requires a subset of the granter's fresh rights, inside the lock. Reserved rights and `owner` refuse `right-not-grantable` on the rights route, at invite create and again at accept. | +| A role bundle widened in code | A membership stores its expanded rights, never a live role reference, so a bundle change in a later build reaches no existing member. A test pins every bundle. | +| An unknown or future right name, from a rollback or a hand edit | That row grants nothing at the Console and the bus. Writes refuse unknown names. A call site asking for an unknown right refuses `unknown-right`. | +| Stale rights in a live session or a pending confirmation | Per-request re-reads at the Console and the bus. A decide confirmation records the member's `rev`, and resolve refuses if `decide` is gone or `rev` moved. | +| A rights change racing an in-flight call | The bus re-evaluates the member's rights on every user and console call, so a narrowing that lands after the Console's check still refuses at the bus. | +| A narrow scope reaching org-wide data | Targets with no project, such as store tasks, `agents`, `usage`, `limits` and decisions with no project, need a whole-org scope. Board verbs return only rows in scope. | +| Invite token theft | The token is in the URL fragment, so it stays out of logs and Referer. The store holds only its hash. A stolen token without a matching verified email or exact subject cannot be accepted. Expiry is 72 hours by default and 168 at most. The owner can revoke. There is no domain binding (ruling 2). | | Invite token replay | One use: `accept` sets `used` inside the same locked write that adds the membership. A second accept sees `used` and refuses. A replay against a recreated org fails on the incarnation. | | Invite guessing | 256 bits of randomness and a rate limit on `/api/invites/start`. | | Invite racing an archive or delete | Accept holds the registry lock across its check and its write, and lifecycle changes need the same lock. | -| Forced join, a victim tricked into joining an attacker's org | Accept needs an explicit `POST` from the accept page after sign-in. A link cannot accept. The page names the org and the inviter. | -| CSRF on membership writes | Every write is `POST`. It requires `Origin == publicOrigin` and `Sec-Fetch-Site: same-origin`, as `logout` and the org write fence already do (`sso.mjs:318-337`, `serve.mjs:964-969`). The cookie is `SameSite=Lax` with the `__Host-` prefix. Accept and decline take the invite from the session, not the body. The LAN fake for `Sec-Fetch-Site` cannot run in accounts mode. | +| Forced join, a victim tricked into joining an attacker's org | Accept needs an explicit `POST` from the accept page after sign-in. A link cannot accept. The page names the org, the inviter and the rights. | +| CSRF on membership and rights writes | Every write is `POST`. It requires `Origin == publicOrigin` and `Sec-Fetch-Site: same-origin`, as `logout` and the org write fence already do (`sso.mjs:318-337`, `serve.mjs:964-969`). The cookie is `SameSite=Lax` with the `__Host-` prefix. Accept and decline take the invite from the session, not the body. A rights change carries the expected `rev`. The LAN fake for `Sec-Fetch-Site` cannot run in accounts mode. | | Clickjacking the accept page | The CSP already sends `frame-ancestors 'none'` (`serve.mjs:834`). | | Session fixation | The session id is minted at `callback` (`sso.mjs:293-294`), never taken from the browser. Accept mints another id when an account is created. `__Host-` cookies cannot be planted from a subdomain. | | Stolen cookie after disable and re-enable | `authGen` goes up on every disable, enable, role change and subject change, and on `user signout`. A session with an older value is refused whether or not it made a request in between. | | Login CSRF | State, nonce and PKCE S256, with the provider taken from the server-side login record (`sso.mjs:215-246`). | -| Member to owner | The owner role comes only from `owner.json`, written once at create, matched by `ownsOrg`. No API or accounts.json field writes an owner. Invites make members only. Grant changes, invites and removals need `admin`, which needs owner. `org-service` repeats the owner check for update, archive, restore and delete. The bus repeats it for console calls through per-org `consoleOwners`. A member cannot edit their own row because every accounts write checks the actor's role inside the locks, not only at the HTTP layer. | +| Member to owner | The owner comes only from `owner.json`, written once at create, matched by `ownsOrg`. No API or accounts.json field writes an owner, and `owner` is not a grantable role. `org-service` repeats the owner check for update, archive, restore and delete. The bus passes setup verbs only for the owning account. | | A member bound as the org's human | Invite create, accept and `memberGrant` each refuse a member who is the org's `human`. | | Owner locked out by a second provider | `ownsOrg` matches any subject of the owning account, at the Console, the service and the bus alike. | | Stale access after removal | Per-request re-reads in the Console and the bus. Disabling an account kills all its sessions at their next request. | | Dev bypass on a deployed system | Section 6: a stamped build refuses the dev owner in code, an altered stamp refuses every start, and the instance checks refuse it on any instance with accounts, `console.sso` or `.deployed`. A hand-started checkout on a fresh named instance is the dev path and is not covered. | | Identity confusion across providers | Identity is `(provider, sub)` with the issuer from config. Email matches invites only. A subject belongs to one account. | -| Local CLI acting outside the check | In accounts mode `mosaic org` and `decide --org` refuse. `mosaic accounts` runs as the instance uid, which can already read every bus file. | +| Local CLI acting outside the check | In accounts mode `mosaic org` and `decide --org` refuse. `mosaic accounts` runs as the instance uid, which can already read every bus file, and has no rights verbs. | | Tampering with accounts.json on disk | The file must belong to the instance uid and not be group or other writable. Anyone who can write it already runs as the instance user and can read every bus. That is outside this design, as it is for access.json. | Not covered: a compromised identity provider, a stolen session cookie @@ -1038,21 +1263,51 @@ run `user signout` to cut off the second. The third is today's trust model. Each slice is one lane with its own review. Each lands green before the next starts. Schema and new-file grants are named per slice for the lead. -The order matters: no membership can exist before M5, and the member -transport and bus checks land in M4, before it. +The order matters. The rights table lands first, in M1, because every later +slice checks against it. No membership can exist before M6, and the member +transport and bus rights checks land in M5, before it. -### M1. Accounts store and lock helpers +### M1. The rights table + +New `packages/organization/src/org-rights.mjs`: the rights with their +`grantable` flags, the role bundles, `VERB_RIGHTS`, `normalizeRights`, +`canGrant` and the level for a right. Pure functions, no I/O, no caller yet. + +Acceptance tests: +- `owner` holds every right. `member` holds exactly `org.view`, + `thread.read` and `board.read`, so neither `decide` nor `task.write`. + `collaborator` and `approver` match section 3. Each bundle is pinned. +- `canGrant` refuses a reserved right, `owner`, an unknown name and any set + that is not a subset of the granter's rights. +- `normalizeRights` sorts, removes duplicates, adds `org.view`, and refuses + a removal of `org.view`. +- Every verb in `CONSOLE_VERBS`, `USER_VERBS`, `BOARD_VERBS` and the task + verbs is mapped in `VERB_RIGHTS` or listed as owner-only. A verb outside + the map resolves to no right. +- `thread.write` maps to the `collaborator` level and every other right to + `viewer`. + +Grant needed: the rights table is org authority policy. It changes only by +reviewed commit. + +### M2. Accounts store and lock helpers New `packages/organization/src/accounts.mjs`: loader, `withAccounts`, `withAccountsLocked`, receipts. `readRegistryLocked` in `org-registry.mjs`. New `mosaic accounts init | list | user add | user disable | user enable | -user signout | user remove`. No Console or bus change. +user signout | user remove`. The membership schema carries `role`, +`rights`, `scope` and `rev`, checked against M1. No Console or bus change. Acceptance tests: - The loader refuses a wrong uid, group or other write bit, a symlink, an unknown key, a duplicate subject, a `local-dev` subject, a reserved id, no - active operator, a bad `authGen` and a bad version. Each refusal is - whole-file. + active operator, a bad `authGen`, a bad version and a malformed membership + row. Each refusal is whole-file. +- A well-formed row naming an unknown right or role loads, and is reported + as needing repair. M4 tests that it grants nothing. +- A write naming an unknown right, an unknown role or a reserved right + refuses and changes nothing. +- A rights or scope write bumps `rev` by one. - An account id that is the `human` of a business file loads. - A write with a stale revision refuses and changes nothing. - Two concurrent writes serialize through the lock. @@ -1066,7 +1321,7 @@ Acceptance tests: Grant needed: the new file `/accounts.json` and its schema. -### M2. Sign-in through accounts and the deployed boundary +### M3. Sign-in through accounts and the deployed boundary `callback` records `account`, `user` and `rootOwner` separately. The session captures `authGen`. `session()` re-reads the account per request. Root @@ -1099,16 +1354,16 @@ Acceptance tests, against a fake OIDC provider on port 0: Grant needed: `stack-copy.sh` writes a new file into every copy, and the installers write `.deployed`. -### M3. `checkOrgAccess` and owner-only orgs on accounts instances +### M4. `checkOrgAccess` and owner-only orgs on accounts instances New `packages/organization/src/membership.mjs` with `ownsOrg`, -`memberGrant` and `checkOrgAccess`. `readOrgSnapshot` split out of -`readCurrentUnlocked`. The registry gains `incarnation`. -`organizationConsole` is built in both modes. `admitted` wraps the check. -`org-service` `authorize` gains accounts mode, and create and update use -the account id as `human`. The U1 read is open to any account session. No -member can exist yet, and the member branch of the options builder refuses -until M4. +`memberGrant` and `checkOrgAccess`, evaluating rights by M1. +`readOrgSnapshot` split out of `readCurrentUnlocked`. The registry gains +`incarnation`. `organizationConsole` is built in both modes. `admitted` +wraps the check. `org-service` `authorize` gains accounts mode, and create +and update use the account id as `human`. The U1 read is open to any +account session. The member branch of the options builder refuses until +M5, so no member reaches a bus yet. Acceptance tests: - Users A and B each create an org. A creates two orgs and updates each. @@ -1119,6 +1374,13 @@ Acceptance tests: missing org. - One account with two providers: create through the first, then read, update and archive through the second. A different account is refused. +- `checkOrgAccess` unit tests over seeded rows: the owner passes every + right. A `member` row passes `org.view`, `thread.read` and `board.read`, + and gets `org-forbidden` for `decide`, `task.write` and every reserved + right. An added right passes on the next call, and a removed one refuses. + An unknown right in the row gives `org-unavailable`. An unknown right + asked by the caller gives `unknown-right`. A project-scoped row is refused + an org-wide target and a project outside its scope. - Delete and recreate an org with the same id while stale rows remain: they grant nothing. - A registry published during a read is retried, and an invalid digest @@ -1130,54 +1392,69 @@ Acceptance tests: Grant needed: the `incarnation` field in `org-runtime.json`. -### M4. Member transport and bus checks +### M5. Member transport and bus rights -The options builder follows the transport table. Org buses derive -`consoleOwners` per call by the ownership rule, and load member grants from -accounts.json through `memberGrant`. Member list, resolve and U1 use the -public projection. M4 tests seed memberships through `withAccounts` -directly, since invites come in M5. +The options builder follows the transport table. On org buses, the console +transport maps the subject to an account and checks `VERB_RIGHTS`, which +replaces `consoleOwners` there. The user transport checks `VERB_RIGHTS` and +`covers` for member grants from accounts.json through `memberGrant`. Board +verbs filter to the scope. The task store admits a user caller holding +`task.write`. Member list, resolve and U1 use the projection. M5 tests seed +memberships through `withAccounts` directly, since invites come in M6. Acceptance tests: -- A collaborator member's U1 read shows the org with its projects and - threads populated, the other sections reading "not shared with members", - and only the covered projects listed. The same member's list and resolve - return the projection, not the document. -- A member with an explicit project and instance grant sees threads in that - project and is refused another project, at the Console and directly at - the bus. An expired grant and a disabled account each grant nothing, and - `memberGrant` is the document the broker reads. -- A collaborator sends in a covered thread. A viewer's send refuses at the - Console and directly at the bus. -- A member's task write and decide refuse at the Console, with nothing - sent. -- A console call carrying a member's subject straight to the bus refuses - `human-required`. A console call carrying the owner's second subject - passes. -- A user-transport call naming org B's business with a grant for org A +- A default `member` sees the org in U1 with projects, threads and every + board section populated for its scope. Its task write and decide refuse + at the Console with nothing sent, and the same calls sent straight to the + bus refuse. +- After the owner's row change adds `task.write`, the member's task write + passes through the Console and lands with the member's id as actor. After + `decide` is added, the member's decide passes over the console transport. + After each is removed, the next Console request and the next bus call + refuse, and the session stays signed in. +- A member scoped to one project sees only that project's threads, + decisions and tagged rows, gets "not shared with you" for `agents`, + `usage` and `limits`, and cannot write a store task. The same calls sent + straight to the bus refuse or return only rows in scope. +- A member holding every grantable right is refused every `org.setup` + console verb at the bus, and every reserved Console route. +- A console call with a member's subject naming another org refuses. A + user-transport call naming org B's business with a grant for org A refuses. -- Removing the member makes the next bus call refuse. -- Removing a subject from the owner account drops it from the next bus - console call. +- A verb with no `VERB_RIGHTS` entry refuses a member at the bus. +- A member's only human-transport call is the `plugins` read. +- Root business access.json users keep exactly today's `USER_VERBS` and + `VIEWER_VERBS` behavior. The FED suites stay green. +- Removing a subject from the owner account drops it from the next console + call. -Grant needed: org buses read accounts.json for console owners and member -grants. This changes the bus authority source but adds no verb. +Grant needed: a bus authority expansion on org buses. Member grants reach +board verbs, task writes and console verbs by right. Rulings 1 and 3 settle +the policy. REQ-USER-3 needs an amendment for org members. -### M5. Invites +### M6. Invites Create, list, revoke, the invite page, start, the callback exception, -accept and decline. A Console UI for the owner to invite and revoke. +accept and decline. A Console UI for the owner to invite with a role and +added or removed rights, and to revoke. Acceptance tests: - Happy path with an email binding and a fake IdP that asserts `email_verified`, for a subject the instance has never seen: callback creates a pending session, accept creates the account, and the - membership carries the chosen grant. + membership carries the invite's role, rights and scope at `rev` 1. +- An invite with no role chosen gives the `member` bundle, with no `decide` + and no `task.write`. +- An invite naming a reserved right or `owner` refuses at create with + `right-not-grantable`. +- An invite whose rights the table no longer knows, simulated with a test + table, refuses at accept with `invite-unavailable`. - An unknown subject with a login record that has no invite still gets `subject-unknown`. A pending session reaches no org data. - Each of these refuses with `invite-unavailable` and leaves no session or account: a wrong email, `email_verified: false`, a wrong subject, an expired invite, a revoked invite, a used invite, a recreated org. +- No route accepts a domain binding. - An invite naming the owner refuses at create. The owner accepting an invite to their own org refuses. - Two parallel accepts of one token: exactly one membership. @@ -1190,7 +1467,30 @@ Acceptance tests: - The 33rd open invite for one org refuses. - The rate limit answers 429. -### M6. Removal, leave, archive and delete cleanup +### M7. Rights changes + +The rights route, the owner's member page with role and per-right +controls, the rights list on org responses, and the `rev` binding on the +decide confirmation. + +Acceptance tests: +- The owner applies `collaborator`, adds `decide`, then removes + `board.read`. After each write, the member's next Console request and + next bus call follow the new rights, with no sign-in in between. +- A write with a stale `rev` refuses `member-changed` and changes nothing. +- A removal of `org.view` refuses. +- A member calling the rights route, on their own row or another's, + refuses, even when the member holds every grantable right. +- A request adding `members.manage`, `org.setup`, `org.lifecycle` or + `owner` refuses `right-not-grantable`. +- A decide confirmation minted before `decide` is removed refuses at + resolve. One minted before an unrelated change that moved `rev` refuses + too, and the member confirms again. +- A rights change racing a removal or a delete, under the lock order, ends + with one consistent row or none. +- Each change appends one receipt with before and after. + +### M8. Removal, leave, archive and delete cleanup Member remove and leave routes. Delete removes rows and invites under the registry lock. Orphan sweep. @@ -1203,14 +1503,16 @@ Acceptance tests: failure of the second write leaves rows that grant nothing. - Cleanup racing a new membership write for the same org: the write waits for the locks and then refuses on the missing registry entry. -- Archive then restore keeps the members. +- Archive then restore keeps the members, their rights and their `rev`. -### M7. Deployed end to end +### M9. Deployed end to end Installers write `.deployed`. Two signed-in users through the bundled -Pocket ID on a scratch instance run from a stamped copy: create, invite, -accept, U1 read as owner and as member, owner task write, decide, remove. -Then rollback to the earlier copy before any org exists, with sign-in still +Pocket ID on a scratch instance run from a stamped copy: create, invite as +`member`, accept, U1 read as owner and as member, member decide refused, +owner adds `decide` and `task.write`, member decides and writes a task, +owner removes both, member refused again, owner removes the member. Then +rollback to the earlier copy before any org exists, with sign-in still required. Then the dev instance runs the same U1 and org pages with no sign-in. @@ -1219,58 +1521,56 @@ flows through a scripted browser session, then the WebUI, before Jason walks it (ruling 4), with a receipt for each step. The org and decide CLI verbs are not part of the accounts flow. -### M8. Member board reads and task writes, after a ruling +## Owner rulings, 2026-11-10 -Only if the owner rules yes on open question 3. New user verbs on the bus -for board reads and task writes, each checked with `covers` against the -task's project at the level the ruling sets, and the transport table rows -for members changed to match. Root FED behavior and thread privacy stay as -they are. Its own design note and review come first. +Draft 2 left three questions open. Jason ruled on all three on 2026-11-10, +and draft 3 applies them. No question from draft 2 remains open. -Grant needed: a bus authority expansion, which changes `USER_VERBS` and -REQ-USER-3. +| Question | Ruling, verbatim | Where draft 3 applies it | +| --- | --- | --- | +| May a member decide on an org's decisions? | "This should be a grantable right with RBAC. Default is owner yes, member no." | The `decide` right, not in the `member` bundle. Section 3, slices M1, M5 and M7. | +| May an invite bind to an email domain? | "agreed" | No domain binding. Section 4 binding, test in M6. | +| May members read the board and write tasks? | "Similar to 1. grantable right via RBAC. Default owner R/W, member R" | The `board.read` and `task.write` rights. `member` holds `board.read` only. Section 3, slices M1, M5 and M7. | -## Open questions for the lead +### Assumptions for the lead to confirm -None block the build of M1 to M3. These need an owner ruling before the -named slice starts: +None blocks M1 to M4. -1. Before M4: should a collaborator member be able to decide on an org's - decisions? This design says no, matching today's code. -2. Before M5: should an invite also allow a binding to an email domain, so - an owner can invite a team in one link? This design says no, since a - domain binding is close to a bearer token. -3. Before M8: may members read an org's board and write its tasks within - their grant? REQ-USER-3 grants threads only, and the owner direction's - U4b names the writes without saying who may make them. Until a ruling, - members see projects and threads only. +1. "Member R" includes reading threads, not only the board. Draft 2's + default thread write is now a grantable right. +2. `members.manage`, `org.setup` and `org.lifecycle` stay owner-only and + are not grantable. Section 3 gives the reasons. +3. `request.write`, the owner's intake controls, is grantable and sits in + `approver`. Intake starts agent work, which spends budget, so an owner + may want it reserved instead. +4. REQ-USER-3 in `docs/prd/mosaic-stack.md` needs an amendment that lets + org member grants carry rights beyond threads. That is a PRD edit, not a + design change. -## Changes in draft 2 +## Changes in draft 3 -The luna review asked for 3 changes and the sol review for 10. Every one is -taken. +- Jason's three rulings of 2026-11-10 are recorded, and the open questions + are closed. +- Named rights, roles as bundles, and per-member rights the owner adds or + removes replace the fixed owner and member split. Defaults: the owner + holds every right, a member holds `org.view`, `thread.read` and + `board.read`. +- The membership record stores `role`, the expanded `rights`, `scope` and + `rev`. Draft 2's `grant.level` is gone, and the bus level comes from the + rights. +- `checkOrgAccess` takes a right and adds a held-right step and a scope rule + for targets with no project. +- Only the owner grants, never more than the owner holds, never a reserved + right. Unknown rights fail closed per row, per write, per call site and + per bus verb. +- Rights changes reach live sessions at the next request and bus call. + The decide confirmation binds to `rev`. +- The transport table is keyed by right. The org bus checks rights on the + user and console transports. +- Invites carry a role, rights and a scope, checked again at accept. +- Seven threat rows cover privilege escalation through grants. +- Slices: the rights table is M1. Draft 2's M8 is folded into M5. A new M7 + covers rights changes. The slices run M1 to M9. -- Account ids may be their own orgs' `human`. Create and update both use - the account id. Members can never be the org's `human`. (sol 1) -- A transport table per role and call, the honest trust statement for the - human transport, member reads limited to threads, and M8 behind a ruling. - (sol 2) -- `memberGrant` builds the full grant document. `discover` is separate from - concrete reads and writes. Project-only targets follow the broker's - convention. (sol 3) -- `readOrgSnapshot` keeps the verified read after the check, with a member - projection. Tests use `?org=`. (sol 4) -- `ownsOrg` matches any subject of the owning account at the Console, the - service and the bus. (sol 5) -- The session records `account`, `user` and `rootOwner` separately, and root - options come from explicit flags. (sol 6) -- The local CLI is a documented exception and refuses in accounts mode. - M7 drives HTTP flows. (sol 7) -- One lock order across lifecycle, registry and accounts, with helpers for - holders and interleaving tests. (sol 8) -- `authGen` ends old sessions across a disable and re-enable. (sol 9) -- Rollback keeps `--sso` and states what it cannot restore. (sol 10) -- The build stamp moves the dev-owner refusal into the executable, and the - claim is narrowed to what the code can check. (luna 1) -- The callback's invite exception is stated with its limits. (luna 2) -- A random incarnation id replaces the `created` timestamp. (luna 3) +Draft 2's change list, from the luna and sol reviews, is in the commit +history at `69af2fe94`. -- 2.54.0 From 0a75cc82f3fcddf0d0ff007a6a8e9bafda25b489 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 10 Nov 2026 13:02:37 -0600 Subject: [PATCH 2/3] docs(plans): accounts design draft 3, luna review fixes (#1873) Member task writes use the person verbs tasks.* instead of the agent task path. A member's console cap never carries the org's human, and only the decide handlers and request reads gain a member branch. VERB_RIGHTS pins every BOARD_VERBS entry. request.write is reserved, decide excludes credential mints, and the lead-confirm list becomes decided choices. --- docs/plans/2026-11-10_accounts-design.md | 174 ++++++++++++++++------- 1 file changed, 125 insertions(+), 49 deletions(-) diff --git a/docs/plans/2026-11-10_accounts-design.md b/docs/plans/2026-11-10_accounts-design.md index 520cf600d..57b56f6df 100644 --- a/docs/plans/2026-11-10_accounts-design.md +++ b/docs/plans/2026-11-10_accounts-design.md @@ -379,19 +379,19 @@ allows. | `org.view` | See the org in lists and the U1 read, with its label, theme and the projects in scope. Bus verbs `project.list` and `names`. | Comes with every membership and cannot be removed | | `thread.read` | Read threads. Bus verbs `thread.list` and `thread.messages`, and the chat's `plugins` read. | Yes | | `thread.write` | Open, create, send and share threads. Bus verbs `thread.open`, `thread.create`, `thread.send`, `thread.share`, `thread.unshare` and `thread.shares`, at the collaborator level the broker already uses (`broker.mjs:182-184`). | Yes | -| `board.read` | The U1 board sections `inbox`, `agents`, `thread.claims`, `tasks`, `usage`, `limits` and `decisions`, and the request reads `request.get.console`, `request.projects.console`, `request.artifact.console` and `request.workspace.console`. | Yes | -| `task.write` | The U4b task writes, create, move, edit and archive, through the task verbs (`packages/tasks/src/store.mjs:58-143`). | Yes | -| `decide` | `decision.preview.console`, `decision.resolve.console` and `prd.revoke.console`. | Yes | -| `request.write` | The owner's intake controls `request.answer.console`, `request.attach.console`, `request.cancel.console`, `request.mode.console` and `request.draft.console`. | Yes | +| `board.read` | The U1 board sections. Bus verbs `inbox`, `agents`, `thread.claims`, `tasks`, `decisions` and `usage` from `BOARD_VERBS`, and the request reads `request.get.console`, `request.projects.console`, `request.artifact.console` and `request.workspace.console`. The other five `BOARD_VERBS`, `trail`, `credentials`, `replies`, `messages` and `state` (`broker.mjs:187`), stay owner-only. U1 reads none of them. | Yes | +| `task.write` | The person's task-store writes, bus verbs `tasks.create`, `tasks.edit`, `tasks.archive` and `tasks.unarchive` (`broker.mjs:7939-7967`), with no change to `assignees`. `tasks.delete` and assignment stay with the owner. | Yes | +| `decide` | `decision.preview.console` and `decision.resolve.console` for decisions routed to the human, except credential mints. | Yes | +| `request.write` | The owner's intake controls `request.answer.console`, `request.attach.console`, `request.cancel.console`, `request.mode.console` and `request.draft.console`, plus `prd.revoke.console`. | No, owner only | | `members.manage` | Create, list and revoke invites, remove members, change a member's rights. | No, owner only | | `org.setup` | The org admin and setup routes (`serve.mjs:802-805`), `plugins.set`, `system-types.console` and `project.remote.get.console` and `.set.console`. | No, owner only | | `org.lifecycle` | Archive, restore, delete and restart the org. | No, owner only | The lead asked for decide, board read and task write plus whatever today's -owner-only operations need. `request.write` and the three reserved rights -are those operations. +owner-only operations need. `request.write` and the other three reserved +rights are those operations. -Three rights stay with the owner, and I think they should: +Four rights stay with the owner, and I think they should: - `members.manage`, because granting is the owner's alone. A member who could grant could widen themselves. @@ -400,6 +400,15 @@ Three rights stay with the owner, and I think they should: it would act with the owner's identity on the human transport. - `org.lifecycle`, because delete cannot be undone and removes every member. +- `request.write`, because the intake controls start and steer agent work, + which spends the owner's budget, and `prd.revoke.console` withdraws an + approved PRD. The rulings cover deciding, the board and tasks, not + intake. + +`decide` also stops short of credential mints. A decision whose action is +`credential.mint` hands a credential to an agent (`broker.mjs:2374-2380`). +Approving one widens what agents can reach, which no member right should +do, so those decisions stay the owner's. Making any of them grantable later is a separate owner decision. The table has a `grantable` flag per right, so that change is one reviewed line plus @@ -419,7 +428,7 @@ A role is a named bundle of rights, a constant in `org-rights.mjs`: | `owner` | Every right, reserved ones included. It comes only from `owner.json`. Nobody can be granted it. | | `member` | `org.view`, `thread.read`, `board.read`. The default for invites. | | `collaborator` | `member` plus `thread.write` and `task.write`. | -| `approver` | `collaborator` plus `decide` and `request.write`. | +| `approver` | `collaborator` plus `decide`. | So the defaults match the rulings. The owner has every right. A member reads the board and its threads, and cannot decide or write tasks. @@ -555,8 +564,9 @@ Four rules cover a right name the running code does not know: gets `unknown-right`. That is a code bug, and it refuses. A test pins the right name at every call site. - A bus verb with no `VERB_RIGHTS` entry refuses every member. A test pins - that every verb in `CONSOLE_VERBS`, `USER_VERBS`, `BOARD_VERBS` and the - task verbs is either mapped or listed as owner-only. + the exact assignment of every verb in `CONSOLE_VERBS`, `USER_VERBS`, + `BOARD_VERBS` and the person task verbs `tasks.*`, each to one right or + to owner-only, and fails when a verb is added without one. ### From a membership row to a grant @@ -650,8 +660,9 @@ org. granter's rights read fresh. The owner holds every right, so today this limits the owner to grantable rights. The check stays so that a granter added later can never hand out more than they hold. -- `owner`, `members.manage`, `org.setup` and `org.lifecycle` are never - grantable. A request or invite naming one refuses `right-not-grantable`. +- `owner`, `members.manage`, `org.setup`, `org.lifecycle` and + `request.write` are never grantable. A request or invite naming one + refuses `right-not-grantable`. - The scope must be `"*"` or a subset of the org's current projects and instances. - A member cannot change their own row. Leaving is the only change a member @@ -731,10 +742,10 @@ member who lacks it gets the refusal, and nothing goes to the bus. | U1 `chat.threads`, thread messages | `thread.read` | human | user, `thread.list` and `thread.messages` | | Thread open, create, send, share | `thread.write` | human | user, the thread verbs | | U1 `inbox`, `agents`, `thread.claims`, `tasks`, `usage`, `limits`, `decisions` | `board.read` | human | user, the same board verbs, filtered to the scope by the bus | -| U4b task create, move, edit, archive | `task.write` | human | user, the task verbs | +| U4b task create, move, edit, archive | `task.write` | human | user, `tasks.create`, `tasks.edit`, `tasks.archive`, `tasks.unarchive` | | Decide | `decide` | console | console | | Request status reads | `board.read` | console | console | -| Request intake controls | `request.write` | console | console | +| Request intake controls, PRD revoke | `request.write` | console | refused | | Chat `plugins` read | `thread.read` | human | human, `plugins` only, as today (`console-bus.mjs:20-23`) | | Org setup, lifecycle, invites, member rights | reserved | org-service and Console | refused | @@ -751,12 +762,31 @@ What the bus checks on each transport: this transport only for the `plugins` read. - **Console transport.** The Console sends the subject it verified at sign-in. The org bus maps that subject to an account through - accounts.json, with the issuer from config. The account that owns the org - by the ownership rule passes every console verb. Any other account passes - a verb only when its `memberGrant` holds `VERB_RIGHTS[verb]` and the - target is in scope. This replaces the instance-wide `consoleOwners` list - on org buses. So a Console bug cannot let a member decide without - `decide`, or call a setup verb at all. + accounts.json, with the issuer from config, which replaces the + instance-wide `consoleOwners` list (`principal.mjs:76`) on org buses. + Today a verified console cap always carries `human: b.human`, the org's + human (`broker.mjs:2201-2215`), and every console handler checks + `s.human === b.human`. A member must never get that shape, or the + handlers would treat the member as the owner. So the bus makes two cap + shapes: + - The owning account gets today's cap, and every handler runs unchanged. + - A member gets `{human: false, member: , console: subject}`. + Every existing `s.human` check, and `#human`, keep refusing it. M5 + adds a member branch to exactly two handlers. `decision.preview.console` + and `decision.resolve.console` (`broker.mjs:7173-7200`) pass a member + whose fresh `memberGrant` holds `decide` and whose scope covers the + decision's project, or is whole-org when it has none, and refuse + `decision-not-eligible` for a credential mint. `#requestAuthorize` + (`broker.mjs:1018-1030`) and the `request.workspace.console` handler + (`:5868-5869`) pass a member holding `board.read` for the read + operations `get`, `projects`, `artifactConsole` and the workspace read, + in scope. Every other console verb keeps its owner check and refuses. + A member's resolve records `by` as `user:`, `via: + 'console'`, and the member's subject in the `human.input` event, so the + record never names the owner for a member's act. + + So a Console bug cannot let a member decide without `decide`, or call a + setup or intake verb at all. - **User transport.** On an org bus, a member's verb passes when its `memberGrant` holds `VERB_RIGHTS[verb]` and `covers` passes at the right's level. This replaces the fixed `USER_VERBS` gate for member grants on org @@ -764,11 +794,20 @@ What the bus checks on each transport: `VIEWER_VERBS` exactly as today. A board verb answers a member with only the rows in scope: rows whose project the scope covers, and rows with no project only for a whole-org scope. -- **Task writes.** The task store admits the organization's roles as - callers today (`packages/tasks/src/store.mjs:8-10`). U4b admits the - owner's Console writes. This design also admits a user-transport caller - whose grant holds `task.write`, and records that user's id as the actor. - The store's field-writer and holder checks run unchanged after that. +- **Task writes.** Agent roles write through `requestTask` and + `storeTask`, which refuse a user session and require an agent role + (`broker.mjs:6744-6745`, `:4967`). Members do not use that path. The + person's writes are the bus verbs `tasks.create`, `tasks.edit`, + `tasks.archive`, `tasks.unarchive` and `tasks.delete`, gated today by + `#human` (`broker.mjs:7939-7945`). On an org bus, M5 lets a user session + pass that gate for the first four when its fresh `memberGrant` holds + `task.write` with a whole-org scope, since store tasks have no project. + A member's `tasks.edit` or `tasks.create` refuses a value for + `assignees`, because assigning hands work to an agent role, and that + stays the owner's in the MVP. `tasks.delete` keeps `#human` and refuses + members. The row's `by_human` comes from `#owner(s)`, which already + gives `user:` for a user session (`broker.mjs:1635-1637`), so the + store records the member, not the owner. Board reads, task writes and decide for members are new bus authority. They widen FED user authority past REQ-USER-3, which grants threads. Rulings 1 @@ -799,7 +838,8 @@ transport from the role and rights `checkOrgAccess` returned, not from **U4b task writes.** The board's write handler, for create, move, edit and archive, calls `checkOrgAccess(..., {need: {right: 'task.write'}})`. A refusal sends nothing to any bus. A write names exactly one org and goes -only to that org's bus. +only to that org's bus, as one of the person verbs `tasks.*`, over the +human transport for the owner and the user transport for a member. **Per-org decide.** The decide route at `serve.mjs:992-996` calls `checkOrgAccess(..., {need: {right: 'decide', project}})`, with the @@ -1228,6 +1268,8 @@ Rollback keeps OIDC. Nothing in it removes `--sso` or turns sign-in off. | --- | --- | | Cross-org read by a non-member | Every Console org route, the U1 read and the assistant go through `checkOrgAccess`, which re-reads the registry, owner.json and accounts.json per call. A non-member gets the same `org-unavailable` as a missing org, so there is no existence oracle. The `org` query filter applies after membership. On the bus, console and user calls pass only for the owning account or a covering `memberGrant` that holds the verb's right. Human-transport calls are trusted to the Console, as today, and the transport table limits them to the owner. Deleted-and-recreated ids do not match old rows because of the random incarnation. | | Member using a right they were not granted | The Console checks the right before it sends anything. The org bus checks it again on the user and console transports from the same `VERB_RIGHTS` table and the same accounts.json row. A verb with no entry refuses every member. A member never gets the human transport except for the `plugins` read. | +| A member's console call treated as the owner's | A member's console cap carries `human: false` and a `member` id, never the org's human, so every handler that checks `s.human === b.human` still refuses it. Only the decide handlers and the request reads have a member branch, and each re-checks the right and the scope. A member's act records the member, never the owner. | +| A member widening agents through a decision or a task | `decide` excludes `credential.mint` decisions. A member's task write cannot set `assignees`. The intake controls and PRD revoke sit in the reserved `request.write`. | | Member granting rights to themselves or others | Changing rights, inviting and removing need `members.manage`, which is reserved and held only by the owner. The accounts write checks the actor's ownership inside the locks, not only at the HTTP layer. A member's change to their own row refuses. | | Granting more than the granter holds, or a reserved right | `canGrant` requires a subset of the granter's fresh rights, inside the lock. Reserved rights and `owner` refuse `right-not-grantable` on the rights route, at invite create and again at accept. | | A role bundle widened in code | A membership stores its expanded rights, never a live role reference, so a bundle change in a later build reaches no existing member. A test pins every bundle. | @@ -1281,9 +1323,15 @@ Acceptance tests: that is not a subset of the granter's rights. - `normalizeRights` sorts, removes duplicates, adds `org.view`, and refuses a removal of `org.view`. -- Every verb in `CONSOLE_VERBS`, `USER_VERBS`, `BOARD_VERBS` and the task - verbs is mapped in `VERB_RIGHTS` or listed as owner-only. A verb outside - the map resolves to no right. +- `VERB_RIGHTS` is pinned exactly. Every verb in `CONSOLE_VERBS`, + `USER_VERBS`, `BOARD_VERBS` and the person task verbs `tasks.*` has one + reviewed assignment, a right or owner-only. In particular `trail`, + `credentials`, `replies`, `messages`, `state`, `tasks.delete`, + `prd.revoke.console` and the intake verbs are owner-only. A verb added to + any of those lists without an assignment fails the test, and a verb + outside the map resolves to no right. +- `request.write`, like the other reserved rights, is not grantable and is + in no bundle but `owner`. - `thread.write` maps to the `collaborator` level and every other right to `viewer`. @@ -1398,8 +1446,12 @@ The options builder follows the transport table. On org buses, the console transport maps the subject to an account and checks `VERB_RIGHTS`, which replaces `consoleOwners` there. The user transport checks `VERB_RIGHTS` and `covers` for member grants from accounts.json through `memberGrant`. Board -verbs filter to the scope. The task store admits a user caller holding -`task.write`. Member list, resolve and U1 use the projection. M5 tests seed +verbs filter to the scope. The org bus gives a member's console cap the +member shape from section 3, adds the member branches to the decide +handlers and the request reads, and lets a user session holding +`task.write` pass the `#human` gate for `tasks.create`, `tasks.edit`, +`tasks.archive` and `tasks.unarchive`. Member list, resolve and U1 use the +projection. M5 tests seed memberships through `withAccounts` directly, since invites come in M6. Acceptance tests: @@ -1407,11 +1459,25 @@ Acceptance tests: board section populated for its scope. Its task write and decide refuse at the Console with nothing sent, and the same calls sent straight to the bus refuse. -- After the owner's row change adds `task.write`, the member's task write - passes through the Console and lands with the member's id as actor. After - `decide` is added, the member's decide passes over the console transport. - After each is removed, the next Console request and the next bus call - refuse, and the session stays signed in. +- After the owner's row change adds `task.write`, the member's + `tasks.create` and `tasks.edit` pass, through the Console and sent + straight to the bus over the user transport, and the stored row's + `by_human` is `user:`. The same member's `tasks.delete` and + any write setting `assignees` refuse. +- After `decide` is added, the member's `decision.preview.console` and + `decision.resolve.console` pass on the real bus path, and the decision + record names the member as `by` with the member's subject. A + `credential.mint` decision refuses the member. A member without `decide` + is refused at both verbs. A confirmation minted before `decide` is + removed refuses at resolve. +- After each right is removed, the next Console request and the next bus + call refuse, and the session stays signed in. +- A member's console cap never passes an owner check. Every console verb + outside the decide and request-read branches refuses a member at the bus, + including `prd.revoke.console` and the intake verbs for a member holding + every grantable right. +- A member holding `board.read` is refused `trail`, `credentials`, + `replies`, `messages` and `state` at the bus. - A member scoped to one project sees only that project's threads, decisions and tagged rows, gets "not shared with you" for `agents`, `usage` and `limits`, and cannot write a store task. The same calls sent @@ -1481,8 +1547,8 @@ Acceptance tests: - A removal of `org.view` refuses. - A member calling the rights route, on their own row or another's, refuses, even when the member holds every grantable right. -- A request adding `members.manage`, `org.setup`, `org.lifecycle` or - `owner` refuses `right-not-grantable`. +- A request adding `members.manage`, `org.setup`, `org.lifecycle`, + `request.write` or `owner` refuses `right-not-grantable`. - A decide confirmation minted before `decide` is removed refuses at resolve. One minted before an unrelated change that moved `rev` refuses too, and the member confirms again. @@ -1532,20 +1598,24 @@ and draft 3 applies them. No question from draft 2 remains open. | May an invite bind to an email domain? | "agreed" | No domain binding. Section 4 binding, test in M6. | | May members read the board and write tasks? | "Similar to 1. grantable right via RBAC. Default owner R/W, member R" | The `board.read` and `task.write` rights. `member` holds `board.read` only. Section 3, slices M1, M5 and M7. | -### Assumptions for the lead to confirm +### Choices made under the rulings -None blocks M1 to M4. +These are decided in this draft, not open. Each one is a single reviewed +line in the rights table, plus its pinned test, if the owner later wants it +otherwise. 1. "Member R" includes reading threads, not only the board. Draft 2's default thread write is now a grantable right. -2. `members.manage`, `org.setup` and `org.lifecycle` stay owner-only and - are not grantable. Section 3 gives the reasons. -3. `request.write`, the owner's intake controls, is grantable and sits in - `approver`. Intake starts agent work, which spends budget, so an owner - may want it reserved instead. -4. REQ-USER-3 in `docs/prd/mosaic-stack.md` needs an amendment that lets - org member grants carry rights beyond threads. That is a PRD edit, not a - design change. +2. `members.manage`, `org.setup`, `org.lifecycle` and `request.write` are + reserved to the owner. `request.write` covers intake and PRD revoke, + which start, steer or withdraw agent work. The rulings granted deciding, + the board and tasks, not intake. Section 3 gives the reasons. +3. `decide` excludes `credential.mint` decisions, and a member's task write + cannot assign. Both would widen what agents can reach. + +One PRD edit follows, as a grant at slice M5 rather than a question: +REQ-USER-3 in `docs/prd/mosaic-stack.md` needs an amendment that lets org +member grants carry rights beyond threads. ## Changes in draft 3 @@ -1568,7 +1638,13 @@ None blocks M1 to M4. - The transport table is keyed by right. The org bus checks rights on the user and console transports. - Invites carry a role, rights and a scope, checked again at accept. -- Seven threat rows cover privilege escalation through grants. +- Nine threat rows cover privilege escalation through grants. +- A member's console cap never carries the org's human. Only the decide + handlers and the request reads get a member branch. Member task writes + use the person verbs `tasks.*`, not the agent task path. +- `request.write` is reserved, and `approver` is `collaborator` plus + `decide`. `decide` excludes credential mints, and member task writes + cannot assign. - Slices: the rights table is M1. Draft 2's M8 is folded into M5. A new M7 covers rights changes. The slices run M1 to M9. -- 2.54.0 From 01b79e1db4cf02db35c5ac93037e63bea2076d16 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 10 Nov 2026 13:03:07 -0600 Subject: [PATCH 3/3] docs(plans): accounts design draft 3, threat row count (#1873) --- docs/plans/2026-11-10_accounts-design.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/plans/2026-11-10_accounts-design.md b/docs/plans/2026-11-10_accounts-design.md index 57b56f6df..4107f4b21 100644 --- a/docs/plans/2026-11-10_accounts-design.md +++ b/docs/plans/2026-11-10_accounts-design.md @@ -1638,7 +1638,8 @@ member grants carry rights beyond threads. - The transport table is keyed by right. The org bus checks rights on the user and console transports. - Invites carry a role, rights and a scope, checked again at accept. -- Nine threat rows cover privilege escalation through grants. +- Ten new threat rows cover privilege escalation through grants, and the + CSRF and member-to-owner rows are updated. - A member's console cap never carries the org's human. Only the decide handlers and the request reads get a member branch. Member task writes use the person verbs `tasks.*`, not the agent task path. -- 2.54.0