From 180a096a3e1542a3c12e7b4ccd2c5aa988862a94 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 18 Nov 2026 01:09:07 +0100 Subject: [PATCH] Follow ADR 0680 in design 20: a process's own secrets belong to the account it runs as MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR 0436 §1's ban on root and the operator account for a bus process ended, so design 20 now says whose own secrets are, the validator's two rules in their place and how each is checked; zfs-owns-zfs A-37 notes its premise ended. --- 03-DESIGN/01-to-be/20-writing-a-module.md | 38 ++++++++++++++++++- .../zfs-owns-zfs-lead-answers.md | 5 ++- 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/03-DESIGN/01-to-be/20-writing-a-module.md b/03-DESIGN/01-to-be/20-writing-a-module.md index 5a9c0362..31fccc18 100644 --- a/03-DESIGN/01-to-be/20-writing-a-module.md +++ b/03-DESIGN/01-to-be/20-writing-a-module.md @@ -8,8 +8,9 @@ code: - mesh-sdk go/catalogue (the manifest's shapes) - mesh-sdk go/declaration (the node-engine's resource vocabulary) - mesh-contracts -updated: 2026-11-12 +updated: 2026-11-18 decisions: + - "ADR 0680" - "ADR 0578" - "ADR 0595" - "ADR 0619" @@ -169,7 +170,7 @@ since a package is a build input and runs nowhere. |---|---|---| | **tools** | a `bundle` with `loads` naming what the runtime loads (for a Go bundle its `binary`), and the module's `tools` listing every tool it serves; `replaces` for the shell commands a tool replaces | the node's tool runner (ADR 0175); with `runs-as`, a **runtime of its own** under the module's account (below) | | **a long-running service of its own code** | a `process` resource: `artifact` (a bundle), `name` (what the unit is called), `run` (the command, relative to the unpacked bundle), `user`, `env` and `env-file`, `restart-on`, `health`, `yields`, `replaces` (the ids it takes over from) | the node-engine, as a unit that stays up | -| **its own bus account for a process** | the process's `bus`: the `emits`, `state`, `queues`, `invokes` and `asks` it is granted, a subset of what the manifest declares; an own secret holding the account, owned by the process's `user` (ADR 0436 §1) | the grants part composes the account from it | +| **its own bus account for a process** | the process's `bus`: the `emits`, `state`, `queues`, `invokes` and `asks` it is granted, a subset of what the manifest declares; an own secret holding the account, owned by the account the process runs as, whatever that account (ADR 0680 §1; *Whose a process's own secrets are*, below) | the grants part composes the account from it | | **a scheduled job** | a `process` or `container` resource with `schedule`, a five-field cron; never with `run-once`; a process with no `restart-on`, `replaces` or `witness`; a scheduled container may name `while-stopped` (below) | the node-engine, again on each fire (ADR 0053) | | **a one-time step** (a seed, a first-start step, a validator of a file) | a `process` or `container` resource with `run-once` true: a **run-once step**, which gates every resource after it; `restart-on` makes it run again when what it names changes (ADR 0052, ADR 0099) | the node-engine, to completion | | **a migration of its own state before a new version runs** | `prepares` true, and a `container` or `process` that stays up running an artifact the module built: the mesh runs that program in its preparation mode (ADR 0135); never a run-once step written by hand for it | the node-engine, before the new version starts | @@ -178,6 +179,39 @@ since a package is a build input and runs nowhere. | **a host program from the operating system** | a `package` resource (`package`, `absent`) and a `service` resource per unit it ships (`unit`, `state`, `boot`, `scope`, `restart-on`, `reload-on`, `health`); never an `action` | the node's package manager and service manager | | **files** | `file` and `directory` resources (a directory by `place` or `path`), an `archive` resource unpacking an `archive` artifact, template files in the module's `templates` directory | the node-engine and the provisioner client | +**Whose a process's own secrets are** (ADR 0680). *Amended 2026-11-18.* Every own secret a process reads, its bus +credential first, is owned by the account that process runs as, whatever that account is: an account the module +makes (a `user` resource of that name), the operator account (`${machine:account}`), or root (ADR 0680 §1). The +manifest names it, as the secret's `owner` or the module's `secrets-owner`, and the process runs as it (its `user`) +or as root, as the second rule below holds; the node-engine writes the secret owned by it at mode 0600 (ADR 0680 §1). An account the module makes stays +the usual case, not a rule; a process that declares `bus` still names the account it runs as. ADR 0436 §1's "never +root and never the operator account" no longer holds for a process that declares `bus`, and the manifest validator's +two rules that refused them (as an own secret's owner and as a `bus` process's account) are gone (ADR 0680 §2). The +manifest validator holds two rules instead: + +- **Every account named is one the mesh knows.** An own secret's `owner`, a `secrets-owner` and the account of a + process that declares `bus` are each the operator account, root or an account the module makes; any other is + refused, and so is a `bus` process naming no account (ADR 0680 §2). +- **A process can read every own secret it names.** A process resource that names an own secret (its path in the + process's `run` or `env`) and runs as neither that secret's resolved owner (its `owner`, else `secrets-owner`) nor + root is refused (ADR 0680 §3). A container module is excepted, since a container reads its secrets as its own + account, and a process account's secret needs no such rule, since it is delivered owned by the process's account + (ADR 0436 §2). + +A secret owned by the operator account is as private as what runs as that account on its node: the node's tool +runner, and through it every agent session there (ADR 0436 §9). That exposure is accepted (ADR 0680 §1); what bounds +a process account's credential is its grants, which answer no tool and no seat's verb (ADR 0436 §3). A module's +`runs-as` is unchanged: it names an account the module makes (ADR 0259 §8, below). + +*How it is checked:* the node-engine's tests write an own secret owned by the account its manifest names, at mode +0600, for an account the module makes, for the operator account and for root; the manifest validator's tests, run on +every change of the validator and over every manifest a change of mesh-catalog touches, accept an own secret owned by +`${machine:account}` or root, a `bus` process running as either, a process running as the resolved owner of the own +secret it names (also through `secrets-owner`), a process running as root, and a container module naming another +account's own secret, and refuse a `bus` process naming no account or one the module does not make, and a process +naming another account's own secret; the controller's grant test still finds no process account able to answer a +call (ADR 0680 §4). + **A runtime of its own.** A module that says `runs-as` names an account it makes (a `user` resource of that name, never root nor the operator's); its tools bundle is then served by a runtime of its own, as that account, on a bus account of its own (ADR 0259 §8), whose readiness is the manifest's `runtime-health` (ADR 0366). Its secrets belong to diff --git a/03-DESIGN/01-to-be/42-milestones/zfs-owns-zfs-lead-answers.md b/03-DESIGN/01-to-be/42-milestones/zfs-owns-zfs-lead-answers.md index 60c161d8..9330b992 100644 --- a/03-DESIGN/01-to-be/42-milestones/zfs-owns-zfs-lead-answers.md +++ b/03-DESIGN/01-to-be/42-milestones/zfs-owns-zfs-lead-answers.md @@ -3,9 +3,10 @@ layer: to-be status: in-progress design: 42 milestone: zfs-owns-zfs -updated: 2026-11-13 +updated: 2026-11-18 decisions: - "ADR 0679" + - "ADR 0680" --- # 42, milestone zfs-owns-zfs — the lead's answers to the prepare's questions @@ -136,6 +137,8 @@ settles it (`00-META/principles.md`), cited as "design 42 zfs-owns-zfs A-n". The calls: emit an event, put or delete a key of those states, and invoke one of those three. The root processes say everything they say on the bus through it; with the keeper not answering they act as with the bus down (A-8), and warn. The module's tools keep their own account as today. + *Amended 2026-11-18:* ADR 0680 §1 ends ADR 0436 §1's "never root" for a process that declares `bus`, so this + answer's premise no longer holds; the keeper stands as the milestone builds it, a choice the records no longer force. - **A-38** (A-37, §25, §26, met in develop; ADR 0436 §1, ADR 0595 §1, §2; the operator's "a case the delivery cannot handle is a gap in the build and delivery system") A process's `bus` today is judged and granted only against the module-level `emits` and `state`, which ADR 0595 replaced by what a module asks for in `requires`. In this