From cf566498454b1a34a5b229bda586cdd49af1b645 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:00:46 +0200 Subject: [PATCH 1/6] Design 41: every file on a node is managed through node-files (WP9, ADR 0394, issue 900) --- ...-the-shell-and-the-accounts-environment.md | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index 2a5c8705..f5b9c46d 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -2,8 +2,9 @@ layer: to-be status: in-progress code: [mesh-host, mesh-controller, mesh-catalog] -updated: 2026-10-12 +updated: 2026-10-16 decisions: + - "ADR 0394" - "ADR 0310" - "ADR 0268" - "ADR 0252" @@ -90,6 +91,7 @@ WP5 assign and prove (operator-gated) needs WP WP6 a module puts the account in a group (mesh-host, mesh-controller, mesh-catalog) issue 247 WP7 the control-node withholds execute (mesh-controller, mesh-catalog) ADR 0268 WP8 a node's files and accounts are read (mesh-sdk, mesh-catalog, mesh-controller) ADR 0310, issue 418 +WP9 every file on a node is managed (mesh-tools, mesh-controller) ADR 0394, issue 900 ``` WP1, WP2 and WP4 are independent, and are built in parallel on one feature branch per repository @@ -366,3 +368,32 @@ under the same issue. `mesh-sdk` test of the content rule and one in each of its users; `mesh_search` for `cat`, `grep` and `getent passwd` finding the verbs. Live, the kernel's RAID status file is read through the seat on the home server, and the agent's credentials file on the laptop is refused. + +## WP9 — Every file on a node is managed through `node-files` + +*`mesh-tools`, `mesh-controller`. ADR 0394; tracked by issue 900.* + +`node-reads` only reads, and as an account that cannot open a person's home, so nothing in the mesh could copy, +move, write or delete a file, and a cleanup needed a shell on the machine. Most files belong to no module: homes, +project folders, downloads, logs, scratch. + +- **A node seat, `node-files`, on every node**, held by the tool runner, with a verb for each file action: list, + stat, read, search, write, copy, move, delete, make a folder, change mode, change owner, and the trash's list and + restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `cat`, `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, + `chown`, and `ssh cp` for a copy between nodes. +- **It may touch every file.** It runs with full rights and keeps each file's owner and modes as well as it + can: a copy or a move keeps them, a new file takes its folder's owner. Which files to touch is the caller's + responsibility; this first version judges no permission. +- **Nothing is lost at once.** A file deleted or overwritten goes to the node's trash with who asked and why, is + restorable for 7 days, and is emptied after. +- **A path a module owns is refused**, naming the module and its tool, unless the call says `override` with a + reason; an override is recorded and said to the operator. +- **No Approve is asked**; every act is recorded with its caller. Read and search never return the content + of a known credential file or a secret place (the mesh never prints a token); copying or moving one is + allowed. + +**Proof.** The tool runner's tests: each verb against a temporary tree keeps owner and modes, a new file takes its +folder's owner, a delete is restorable from the trash and gone after 7 days, an owned path is refused and an +override recorded, a credential file's content is never returned. Live: the operator's `~/.claude` on shanks is listed, and a file copied from one node to another +arrives with its owner and modes. + From 330d3416185af878acda8d37e3c5c66459afd5e5 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:01:43 +0200 Subject: [PATCH 2/6] Design 41 WP9: node-files is held by a module of its own, mesh-files, beside mesh-reads --- .../41-the-shell-and-the-accounts-environment.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index f5b9c46d..9681c8a6 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -91,7 +91,7 @@ WP5 assign and prove (operator-gated) needs WP WP6 a module puts the account in a group (mesh-host, mesh-controller, mesh-catalog) issue 247 WP7 the control-node withholds execute (mesh-controller, mesh-catalog) ADR 0268 WP8 a node's files and accounts are read (mesh-sdk, mesh-catalog, mesh-controller) ADR 0310, issue 418 -WP9 every file on a node is managed (mesh-tools, mesh-controller) ADR 0394, issue 900 +WP9 every file on a node is managed (mesh-catalog, mesh-controller) ADR 0394, issue 900 ``` WP1, WP2 and WP4 are independent, and are built in parallel on one feature branch per repository @@ -371,13 +371,14 @@ server, and the agent's credentials file on the laptop is refused. ## WP9 — Every file on a node is managed through `node-files` -*`mesh-tools`, `mesh-controller`. ADR 0394; tracked by issue 900.* +*`mesh-catalog`, `mesh-controller`. ADR 0394; tracked by issue 900.* `node-reads` only reads, and as an account that cannot open a person's home, so nothing in the mesh could copy, move, write or delete a file, and a cleanup needed a shell on the machine. Most files belong to no module: homes, project folders, downloads, logs, scratch. -- **A node seat, `node-files`, on every node**, held by the tool runner, with a verb for each file action: list, +- **A node seat, `node-files`, on every node**, held by a module of its own, `mesh-files`, beside `mesh-reads` + in the catalogue; the controller holds the seat's definition beside the other node seats. It has a verb for each file action: list, stat, read, search, write, copy, move, delete, make a folder, change mode, change owner, and the trash's list and restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `cat`, `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `chown`, and `ssh cp` for a copy between nodes. @@ -392,7 +393,7 @@ project folders, downloads, logs, scratch. of a known credential file or a secret place (the mesh never prints a token); copying or moving one is allowed. -**Proof.** The tool runner's tests: each verb against a temporary tree keeps owner and modes, a new file takes its +**Proof.** The module's tests: each verb against a temporary tree keeps owner and modes, a new file takes its folder's owner, a delete is restorable from the trash and gone after 7 days, an owned path is refused and an override recorded, a credential file's content is never returned. Live: the operator's `~/.claude` on shanks is listed, and a file copied from one node to another arrives with its owner and modes. From 7ac5194bcbdc06c66c956b6d069afd7eee592ab8 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:06:32 +0200 Subject: [PATCH 3/6] Design 41 WP9: mesh-files runs as the operator account with sudo where needed, and replaces node-reads (ADR 0394) --- .../41-the-shell-and-the-accounts-environment.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index 9681c8a6..4c542a86 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -382,19 +382,22 @@ project folders, downloads, logs, scratch. stat, read, search, write, copy, move, delete, make a folder, change mode, change owner, and the trash's list and restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `cat`, `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `chown`, and `ssh cp` for a copy between nodes. -- **It may touch every file.** It runs with full rights and keeps each file's owner and modes as well as it - can: a copy or a move keeps them, a new file takes its folder's owner. Which files to touch is the caller's - responsibility; this first version judges no permission. +- **It may touch every file.** It declares no account of its own: the tool runner starts it as the node's + operator account, which has sudo without a password, and it uses `sudo -n` only where that account's own rights + do not reach. It keeps each file's owner and modes as well as it can: a copy or a move keeps them, a new file + takes its folder's owner. Which files to touch is the caller's responsibility; it judges no permission. - **Nothing is lost at once.** A file deleted or overwritten goes to the node's trash with who asked and why, is restorable for 7 days, and is emptied after. - **A path a module owns is refused**, naming the module and its tool, unless the call says `override` with a reason; an override is recorded and said to the operator. +- **It replaces `node-reads`.** Its reads keep WP8's bounds, content rule and kernel reads; `node-reads` and + `mesh-reads` are removed in the delivery that brings it. - **No Approve is asked**; every act is recorded with its caller. Read and search never return the content of a known credential file or a secret place (the mesh never prints a token); copying or moving one is allowed. **Proof.** The module's tests: each verb against a temporary tree keeps owner and modes, a new file takes its folder's owner, a delete is restorable from the trash and gone after 7 days, an owned path is refused and an -override recorded, a credential file's content is never returned. Live: the operator's `~/.claude` on shanks is listed, and a file copied from one node to another +override recorded, a credential file's content is never returned. Live: the operator's `~/.claude` on a workstation is listed, a file in `/etc` is read through sudo, and a file copied from one node to another arrives with its owner and modes. From 1f5a12e07e42fcf6ff474a82b61e538b83bee7a8 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:11:53 +0200 Subject: [PATCH 4/6] Design 41: WP8's node-reads is replaced by WP9's node-files (ADR 0394 supersedes ADR 0310) --- .../01-to-be/41-the-shell-and-the-accounts-environment.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index 4c542a86..aa92b0b8 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -343,6 +343,9 @@ out, the control-node's value is set to `withhold` and zsh is pushed to it. Then *`mesh-sdk`, `mesh-catalog`, `mesh-controller`. ADR 0310, extending ADR 0268; tracked by issue 418.* +**Replaced by WP9.** ADR 0394 supersedes ADR 0310: `node-files` takes over every read below, with the same +bounds, content rule and refusal of secret places, and `node-reads` is removed in the delivery that brings it. + ADR 0268 §5 has narrow read tools take the common reads over from `execute`, so that an approval is asked for an act and not for a read, and ADR 0286 §44 sets the approval mark on `execute` only once those reads have a tool on every node. Two had none: reading or searching a file, and looking up an account or a group. From 26073f30b0dea3395d1287ad9adbd1b288ef6f52 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:14:01 +0200 Subject: [PATCH 5/6] =?UTF-8?q?Design=2041:=20node-reads=20goes=20in=20the?= =?UTF-8?q?=20delivery=20after=20node-files=20is=20held=20on=20every=20nod?= =?UTF-8?q?e=20(ADR=200394=20=C2=A79)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../01-to-be/41-the-shell-and-the-accounts-environment.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index aa92b0b8..5a2556ad 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -344,7 +344,8 @@ out, the control-node's value is set to `withhold` and zsh is pushed to it. Then *`mesh-sdk`, `mesh-catalog`, `mesh-controller`. ADR 0310, extending ADR 0268; tracked by issue 418.* **Replaced by WP9.** ADR 0394 supersedes ADR 0310: `node-files` takes over every read below, with the same -bounds, content rule and refusal of secret places, and `node-reads` is removed in the delivery that brings it. +bounds, content rule and refusal of secret places; once `node-files` is held on every node, the next delivery +removes `node-reads` and `mesh-reads`. ADR 0268 §5 has narrow read tools take the common reads over from `execute`, so that an approval is asked for an act and not for a read, and ADR 0286 §44 sets the approval mark on `execute` only once those reads have a tool on @@ -393,8 +394,9 @@ project folders, downloads, logs, scratch. restorable for 7 days, and is emptied after. - **A path a module owns is refused**, naming the module and its tool, unless the call says `override` with a reason; an override is recorded and said to the operator. -- **It replaces `node-reads`.** Its reads keep WP8's bounds, content rule and kernel reads; `node-reads` and - `mesh-reads` are removed in the delivery that brings it. +- **It replaces `node-reads`.** Its reads keep WP8's bounds, content rule and kernel reads. Every node is + assigned `mesh-reads`, so `node-reads` and `mesh-reads` are removed by the next delivery, once `mesh-files` + holds `node-files` on every node. - **No Approve is asked**; every act is recorded with its caller. Read and search never return the content of a known credential file or a secret place (the mesh never prints a token); copying or moving one is allowed. From 300be928144ee5b24c1f9b58e6b250945d26b8b2 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 13:31:45 +0200 Subject: [PATCH 6/6] =?UTF-8?q?Design=2041=20WP9:=20readlink=20and=20the?= =?UTF-8?q?=20account=20and=20group=20lookup=20are=20node-files=20verbs=20?= =?UTF-8?q?too=20(ADR=200394=20=C2=A71;=20review)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../01-to-be/41-the-shell-and-the-accounts-environment.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md index 5a2556ad..c71ec4d8 100644 --- a/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md +++ b/03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md @@ -383,9 +383,10 @@ project folders, downloads, logs, scratch. - **A node seat, `node-files`, on every node**, held by a module of its own, `mesh-files`, beside `mesh-reads` in the catalogue; the controller holds the seat's definition beside the other node seats. It has a verb for each file action: list, - stat, read, search, write, copy, move, delete, make a folder, change mode, change owner, and the trash's list and - restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `cat`, `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, - `chown`, and `ssh cp` for a copy between nodes. + stat, readlink, read, search, write, copy, move, delete, make a folder, change mode, change owner, account and group + lookup, and the trash's list and restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `readlink`, `cat`, + `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `chown`, `getent passwd`, `getent group`, `id`, and `ssh cp` for a + copy between nodes. - **It may touch every file.** It declares no account of its own: the tool runner starts it as the node's operator account, which has sudo without a password, and it uses `sudo -n` only where that account's own rights do not reach. It keeps each file's owner and modes as well as it can: a copy or a move keeps them, a new file