A read-write access grants the path's own group, and the path is never changed (hq ADR 0312, issue 537) #86

Merged
mesh-admin merged 2 commits from feat/537-a-read-write-access-grants-the-paths-group into main 2026-10-12 11:22:57 +00:00
Contributor

Why (ADR 0312, accepted 2026-10-12 with the operator's Approve; issue 537). A read-write access (ADR 0051) gave no actual write permission: nothing tied an access to a permission, so a module could write a shared path only where its identity happened to be allowed (issue 535: nzbget could not remove its filed download's folder). The media-importer is to file into the operator's libraries through accesses. ADR 0312: the module's identity joins the path's own group; the path is never changed.

What changes (the node-engine)

  • Declaration: an access takes grant {containers, account} (strict; refused on a read access; a container the declaration lacks refused; account names ^[A-Za-z0-9_.][A-Za-z0-9_.-]*\$?$). Sent only by a controller to an engine stating contract 4 (link.GrantContract).
  • Apply (internal/apply/grants.go): reads the path's group (gid, name, group-writable) once per apply, never changes the path. Refused: gid 0, any gid equal to a root-granting group's number (/etc/group and getent), a root group's name (accounts.RootGroups, now with kmem and shadow), a gid with no name. A group that cannot write grants nothing (and takes back an earlier grant), said with the operator's remedy. Containers get --group-add <gid> (in the spec, so recreated when it changes; run-once and scheduled steps too); the account is put in the group, the grant recorded and taken back when no access or user resource asks for it, never a group held before; a removed asker hands a still-asked group to the remaining one.
  • Health: a resource kind access stated on every look, the path read outside the judge's lock within 5 s (one hung read per path at most, "its path does not answer"); unhealthy when the group cannot write or is never granted; no path in any reason. Granted accounts go to the account judge, so the operator's own session says relogin needed there and only there.

Checked: merge-check.sh green (gofmt, vet, every test under race; bus tests skipped without nats-server). Two independent reviews (the second approved c433e76 after six findings were fixed: root groups judged by number, the look bounded and off the lock, no grant without write, account-name rule, hand-over on removal, refused paths skipped by the scheduler). Follow-up: the getent lookup fails open for a minute on a name-service error (issue opened).

Rollout effects (the operator was told and said deliver now): every container mounting a read-write access is recreated once (on ace: radarr, sonarr, lidarr, bazarr, bookshelf, nzbget, qbittorrent, n8n; Plex reads only); a shared folder whose group cannot write becomes an unhealthy module condition; a newly granted group shows relogin needed where the operator's own session runs; kmem/shadow now count as root for ADR 0266's agent-account judge.

Order: this merges and delivers first; the controller half (mesh-controller, same branch name) is re-pinned to this merge commit before it merges.

**Why** (ADR 0312, accepted 2026-10-12 with the operator's Approve; issue 537). A `read-write` access (ADR 0051) gave no actual write permission: nothing tied an access to a permission, so a module could write a shared path only where its identity happened to be allowed (issue 535: nzbget could not remove its filed download's folder). The media-importer is to file into the operator's libraries through accesses. ADR 0312: the module's identity joins the path's own group; the path is never changed. **What changes** (the node-engine) - Declaration: an `access` takes `grant {containers, account}` (strict; refused on a read access; a container the declaration lacks refused; account names `^[A-Za-z0-9_.][A-Za-z0-9_.-]*\$?$`). Sent only by a controller to an engine stating contract 4 (`link.GrantContract`). - Apply (`internal/apply/grants.go`): reads the path's group (gid, name, group-writable) once per apply, **never changes the path**. Refused: gid 0, any gid equal to a root-granting group's number (`/etc/group` and `getent`), a root group's name (`accounts.RootGroups`, now with kmem and shadow), a gid with no name. A group that cannot write grants nothing (and takes back an earlier grant), said with the operator's remedy. Containers get `--group-add <gid>` (in the spec, so recreated when it changes; run-once and scheduled steps too); the account is put in the group, the grant recorded and taken back when no access or user resource asks for it, never a group held before; a removed asker hands a still-asked group to the remaining one. - Health: a resource kind `access` stated on every look, the path read outside the judge's lock within 5 s (one hung read per path at most, "its path does not answer"); unhealthy when the group cannot write or is never granted; no path in any reason. Granted accounts go to the account judge, so the operator's own session says *relogin needed* there and only there. **Checked**: `merge-check.sh` green (gofmt, vet, every test under race; bus tests skipped without nats-server). Two independent reviews (the second approved c433e76 after six findings were fixed: root groups judged by number, the look bounded and off the lock, no grant without write, account-name rule, hand-over on removal, refused paths skipped by the scheduler). Follow-up: the getent lookup fails open for a minute on a name-service error (issue opened). **Rollout effects** (the operator was told and said deliver now): every container mounting a read-write access is recreated once (on ace: radarr, sonarr, lidarr, bazarr, bookshelf, nzbget, qbittorrent, n8n; Plex reads only); a shared folder whose group cannot write becomes an unhealthy module condition; a newly granted group shows *relogin needed* where the operator's own session runs; kmem/shadow now count as root for ADR 0266's agent-account judge. **Order**: this merges and delivers first; the controller half (mesh-controller, same branch name) is re-pinned to this merge commit before it merges.
mesh-admin added 2 commits 2026-10-12 11:17:39 +00:00
The engine reads the group owning the accessed path at apply and gives it to the
containers and the tools' account an access's new `grant` names: --group-add for a
container (recreated with it), an account group for the account (recorded, taken
back as ADR 0252 takes back). The path is never changed; an access whose group
cannot write is stated unhealthy for the operator to decide; group 0 and the
root-granting groups are refused by name. The tool runner restarts through the
restart-on the controller gives it, because the access reports updated exactly
when the account's groups moved. Health says GrantContract (4), which tells the
controller it may send `grant`.
Judge a granted group by number, grant nothing a group cannot write, and keep the look bounded (hq ADR 0312, issue 537 review)
mesh/merge-gate pass: builds mesh-host → ace, g14, novox, shanks; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed
mesh/delivery delivered
c433e76de2
The engine is built without cgo, so a check by name missed a root group a name
service holds or one number carrying another name: the root groups are resolved
to numbers (now with kmem and shadow) and a number named nothing is refused for
containers too. A group without write is granted nothing (§2). The look reads
each path off the lock within five seconds, so a dead network mount cannot stop
every health statement. A grant's account may not start with a dash. A group a
record leaves for another asker is handed to it, so it is still taken back when
the last asker goes (§5). The scheduler skips paths issue 339's guard refuses.
Author
Contributor

Delivery novox/mesh-host@c433e76de229 — delivered since 2026-10-12T11:29:35Z

Delivery plan — builds mesh-host → ace, g14, novox, shanks; no bus step

  • tier 0: mesh-host
  • ace: receives mesh-host
  • g14: receives mesh-host
  • novox: receives mesh-host
  • shanks: receives mesh-host
  • grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before mesh-host is judged on its first machine

Machines

  • mesh-host on ace: passed — healthy 3 times over 2m49s
  • mesh-host on the rest running it: sent

Transitions

  • 2026-10-12 11:18 (new) → proposed (announced): novox/mesh-host#86's head announced
  • 2026-10-12 11:22 proposed → checked (checked): the verdict names this commit
  • 2026-10-12 11:22 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-12 11:25 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-12 11:25 published → delivering (go): its walk started: let go by this owner in its group's order, by a person, or on the controller's own path — not a failed walk that carried a later commit for it, after which it waits for a walk of its own commit
  • 2026-10-12 11:29 delivering → delivered (done): its walk is done, carrying its own commit: every machine of its deploy plan passed, or was left as its policy says

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/mesh-host@c433e76de229` — **delivered** since 2026-10-12T11:29:35Z **Delivery plan** — builds mesh-host → ace, g14, novox, shanks; no bus step - tier 0: mesh-host - ace: receives mesh-host - g14: receives mesh-host - novox: receives mesh-host - shanks: receives mesh-host - grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before mesh-host is judged on its first machine **Machines** - mesh-host on ace: passed — healthy 3 times over 2m49s - mesh-host on the rest running it: sent **Transitions** - 2026-10-12 11:18 (new) → proposed (announced): novox/mesh-host#86's head announced - 2026-10-12 11:22 proposed → checked (checked): the verdict names this commit - 2026-10-12 11:22 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-12 11:25 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-12 11:25 published → delivering (go): its walk started: let go by this owner in its group's order, by a person, or on the controller's own path — not a failed walk that carried a later commit for it, after which it waits for a walk of its own commit - 2026-10-12 11:29 delivering → delivered (done): its walk is done, carrying its own commit: every machine of its deploy plan passed, or was left as its policy says The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
Author
Contributor

Merge check at c433e76d

  • mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: mesh-host)
  • mesh/repo-check: PASS — its merge-check.sh passed

Delivery plan — builds mesh-host → ace, g14, novox, shanks; no bus step

  • tier 0: mesh-host
  • ace: receives mesh-host
  • g14: receives mesh-host
  • novox: receives mesh-host
  • shanks: receives mesh-host
  • grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before mesh-host is judged on its first machine
  • read by no module's build: cmd/mesh-host/grants_test.go, cmd/mesh-host/units_test.go, internal/apply/grants_test.go, internal/apply/mesh_names_test.go, internal/apply/reads_test.go, internal/apply/vocabulary_test.go

Run by the build seat on shanks as build-1791803881089798241 (builds --log build-1791803881089798241).

--- the gate: mesh-host
mesh-host: ok
long-running resources without health: 0
files asking for a setting without saying whether it is trusted: 0
1 manifest(s) checked. Judged against the seats this binary carries; a claim on one of the mesh's own seats is judged fully at registration, and a seat declared by a module not given here reads as unknown. Identities judged on a 6-character machine name, against the bounds of the providers given here
judging 0 module(s) changed against 4 machine(s), as the snapshot of 2026-10-12T11:13:09Z says they run
composing every machine as the mesh is
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
composing every machine with the change
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
merge gate: PASS — every machine composes with the change as it did without (4 of 4 compose)
judged by controller development build against the facts of 2026-10-12T11:13:09Z

machines:
  - a machine (f35): composes
  - holds mesh-dns-resolver (idt): composes
  - holds git, holds mesh-artifact-store, holds mesh-broker, holds mesh-catalog, holds mesh-delivery, holds mesh-dns-resolver, holds mesh-store, holds mesh-vault, holds npm-package-registry, the control node, the hub (ygcyr): composes
  - a machine (yvbpsm): composes

a merge would rebuild 1 module(s) in 1 tier(s): mesh-host

notes:
  - cmd/mesh-host/grants_test.go, cmd/mesh-host/units_test.go, internal/apply/grants_test.go, internal/apply/mesh_names_test.go, internal/apply/reads_test.go and internal/apply/vocabulary_test.go read by no module's build, and rebuild nothing (issue 280)
--- its merge-check.sh (go toolchain)
ok  	github.com/novox/mesh-host/cmd/mesh-bootstrap	1.016s
ok  	github.com/novox/mesh-host/cmd/mesh-host	5.600s
ok  	github.com/novox/mesh-host/examples	1.019s
ok  	github.com/novox/mesh-host/internal/accounts	1.494s
ok  	github.com/novox/mesh-host/internal/apply	5.083s
ok  	github.com/novox/mesh-host/internal/bootstrap	1.662s
ok  	github.com/novox/mesh-host/internal/bundle	1.041s
ok  	github.com/novox/mesh-host/internal/declaration	1.087s
ok  	github.com/novox/mesh-host/internal/firewall	1.898s
ok  	github.com/novox/mesh-host/internal/identity	1.175s
ok  	github.com/novox/mesh-host/internal/image	1.044s
ok  	github.com/novox/mesh-host/internal/inventory	1.070s
ok  	github.com/novox/mesh-host/internal/link	10.508s
ok  	github.com/novox/mesh-host/internal/liveness	2.165s
ok  	github.com/novox/mesh-host/internal/meshcli	1.583s
ok  	github.com/novox/mesh-host/internal/network	1.098s
ok  	github.com/novox/mesh-host/internal/outward	1.058s
ok  	github.com/novox/mesh-host/internal/profile	1.541s
ok  	github.com/novox/mesh-host/internal/reachable	1.047s
ok  	github.com/novox/mesh-host/internal/store	1.277s
ok  	github.com/novox/mesh-host/internal/system	1.084s
ok  	github.com/novox/mesh-host/internal/tunnel	1.055s
ok  	github.com/novox/mesh-host/internal/units	1.044s
ok  	github.com/novox/mesh-host/internal/upgrade	1.213s
ok  	github.com/novox/mesh-host/internal/witness	5.020s
ok  	github.com/novox/mesh-host/packaging	1.036s
?   	github.com/novox/mesh-host/rootsearch	[no test files]
ok  	github.com/novox/mesh-host/validate	1.047s
**Merge check** at `c433e76d` - `mesh/merge-gate`: **PASS** — every machine composes with the change as it did without (4 of 4 compose) (modules: mesh-host) - `mesh/repo-check`: **PASS** — its merge-check.sh passed **Delivery plan** — builds mesh-host → ace, g14, novox, shanks; no bus step - tier 0: mesh-host - ace: receives mesh-host - g14: receives mesh-host - novox: receives mesh-host - shanks: receives mesh-host - grants step: if this changes what the bus's user list says (a new tool, subject or user), novox is sent that list alone, every build there kept, before mesh-host is judged on its first machine - read by no module's build: cmd/mesh-host/grants_test.go, cmd/mesh-host/units_test.go, internal/apply/grants_test.go, internal/apply/mesh_names_test.go, internal/apply/reads_test.go, internal/apply/vocabulary_test.go Run by the build seat on shanks as `build-1791803881089798241` (`builds --log build-1791803881089798241`). ``` --- the gate: mesh-host mesh-host: ok long-running resources without health: 0 files asking for a setting without saying whether it is trusted: 0 1 manifest(s) checked. Judged against the seats this binary carries; a claim on one of the mesh's own seats is judged fully at registration, and a seat declared by a module not given here reads as unknown. Identities judged on a 6-character machine name, against the bounds of the providers given here judging 0 module(s) changed against 4 machine(s), as the snapshot of 2026-10-12T11:13:09Z says they run composing every machine as the mesh is the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued composing every machine with the change the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued merge gate: PASS — every machine composes with the change as it did without (4 of 4 compose) judged by controller development build against the facts of 2026-10-12T11:13:09Z machines: - a machine (f35): composes - holds mesh-dns-resolver (idt): composes - holds git, holds mesh-artifact-store, holds mesh-broker, holds mesh-catalog, holds mesh-delivery, holds mesh-dns-resolver, holds mesh-store, holds mesh-vault, holds npm-package-registry, the control node, the hub (ygcyr): composes - a machine (yvbpsm): composes a merge would rebuild 1 module(s) in 1 tier(s): mesh-host notes: - cmd/mesh-host/grants_test.go, cmd/mesh-host/units_test.go, internal/apply/grants_test.go, internal/apply/mesh_names_test.go, internal/apply/reads_test.go and internal/apply/vocabulary_test.go read by no module's build, and rebuild nothing (issue 280) --- its merge-check.sh (go toolchain) ok github.com/novox/mesh-host/cmd/mesh-bootstrap 1.016s ok github.com/novox/mesh-host/cmd/mesh-host 5.600s ok github.com/novox/mesh-host/examples 1.019s ok github.com/novox/mesh-host/internal/accounts 1.494s ok github.com/novox/mesh-host/internal/apply 5.083s ok github.com/novox/mesh-host/internal/bootstrap 1.662s ok github.com/novox/mesh-host/internal/bundle 1.041s ok github.com/novox/mesh-host/internal/declaration 1.087s ok github.com/novox/mesh-host/internal/firewall 1.898s ok github.com/novox/mesh-host/internal/identity 1.175s ok github.com/novox/mesh-host/internal/image 1.044s ok github.com/novox/mesh-host/internal/inventory 1.070s ok github.com/novox/mesh-host/internal/link 10.508s ok github.com/novox/mesh-host/internal/liveness 2.165s ok github.com/novox/mesh-host/internal/meshcli 1.583s ok github.com/novox/mesh-host/internal/network 1.098s ok github.com/novox/mesh-host/internal/outward 1.058s ok github.com/novox/mesh-host/internal/profile 1.541s ok github.com/novox/mesh-host/internal/reachable 1.047s ok github.com/novox/mesh-host/internal/store 1.277s ok github.com/novox/mesh-host/internal/system 1.084s ok github.com/novox/mesh-host/internal/tunnel 1.055s ok github.com/novox/mesh-host/internal/units 1.044s ok github.com/novox/mesh-host/internal/upgrade 1.213s ok github.com/novox/mesh-host/internal/witness 5.020s ok github.com/novox/mesh-host/packaging 1.036s ? github.com/novox/mesh-host/rootsearch [no test files] ok github.com/novox/mesh-host/validate 1.047s ```
mesh-admin merged commit 3f7f797168 into main 2026-10-12 11:22:57 +00:00
mesh-admin deleted branch feat/537-a-read-write-access-grants-the-paths-group 2026-10-12 11:22:57 +00:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/mesh-host#86