Name the account agents run as on a node, and say whether it can become root

On the control node every agent ran as the operator's account, which has
passwordless sudo, so an agent could become root without a person (hq ADR
0266). A node now names an agent account at the controller's terminal only;
the agent's module declares it never to become root, the node-engine judges
that, and the self-check (DA) raises agent-can-become-root while it does not
hold, so ADR 0259's router can rest on it.

internal/catalogue/agent_account_test.go

@@ -0,0 +1,113 @@
+package catalogue
+
+import (
+	"testing"
+)
+
+// The account agents run as (novox/hq ADR 0266): a module names it as a machine fact — the agent account
+// where the node names one, the operator's otherwise — and asks the node-engine to judge it never to become
+// root only where it is the agents' own.
+
+func TestTheAgentAccountFactFallsBackToTheOperatorAndIsNeverRootOnlyWhenItsOwn(t *testing.T) {
+	facts := machineFacts(Resolution{Node: "anchor", Account: "ops"}, nil, "")
+	if facts["agent-account"] != "ops" || facts["agent-home"] != "/home/ops" || facts["agent-root"] != "" {
+		t.Errorf("with no agent account named, agents run as the operator: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", Account: "ops", AccountHome: "/srv/ops"}, nil, "")
+	if facts["agent-home"] != "/srv/ops" {
+		t.Errorf("the operator's stated home is the agent's home when they are one account: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", Account: "ops", AgentAccount: "agent"}, nil, "")
+	if facts["agent-account"] != "agent" || facts["agent-home"] != "/home/agent" || facts["agent-root"] != RootNever {
+		t.Errorf("a named agent account is the agents', never root: %v", facts)
+	}
+	if facts["account"] != "ops" {
+		t.Errorf("the operator account is still the operator's: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", AgentAccount: "agent", AgentAccountHome: "/var/lib/agent"}, nil, "")
+	if facts["agent-home"] != "/var/lib/agent" || facts["agent-root"] != RootNever {
+		t.Errorf("an agent account with a stated home on a machine with no operator: %v", facts)
+	}
+	if _, has := machineFacts(Resolution{Node: "anchor"}, nil, "")["agent-account"]; has {
+		t.Error("a machine with no account at all names an agent account")
+	}
+}
+
+// The agent's module, in the shape the catalogue's declares it: the account, never root where it is its
+// own; its directory under that home, owned by it.
+const agentModule = `{"module": "agent", "version": "1", "resources": [
+  {"id": "account", "type": "user", "name": "${machine:agent-account}", "root": "${machine:agent-root}"},
+  {"id": "home", "type": "directory", "path": "${machine:agent-home}/.agent", "mode": "0700",
+   "owner": "${machine:agent-account}"}
+]}`
+
+func TestTheAgentAccountIsDeclaredNeverRootOnlyToAnEngineThatJudgesIt(t *testing.T) {
+	m, err := ParseManifest([]byte(agentModule))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compose := func(r Resolution, with Rendering) (user, home map[string]any) {
+		t.Helper()
+		r.Node, r.Modules = "anchor", []Manifest{m}
+		out, err := r.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return fileNamed(out, "agent.account"), fileNamed(out, "agent.home")
+	}
+
+	user, home := compose(Resolution{Account: "ops", AgentAccount: "agent"}, Rendering{JudgesRoot: true})
+	if user["name"] != "agent" || user[RootField] != RootNever {
+		t.Errorf("an engine that judges root is sent the agent account never to become root: %v", user)
+	}
+	if home["path"] != "/home/agent/.agent" || home["owner"] != "agent" {
+		t.Errorf("the agent's directory is under its own home, its own: %v", home)
+	}
+
+	user, _ = compose(Resolution{Account: "ops", AgentAccount: "agent"}, Rendering{})
+	if _, sent := user[RootField]; sent || user["name"] != "agent" {
+		t.Errorf("an older engine, which parses strictly, is sent root: %v", user)
+	}
+
+	user, home = compose(Resolution{Account: "ops"}, Rendering{JudgesRoot: true})
+	if _, sent := user[RootField]; sent || user["name"] != "ops" {
+		t.Errorf("where agents run as the operator, root asserts nothing and is not sent: %v", user)
+	}
+	if home["path"] != "/home/ops/.agent" || home["owner"] != "ops" {
+		t.Errorf("with no agent account, the agent's directory is the operator's: %v", home)
+	}
+}
+
+func TestTheRuntimeIsToldTheAgentAccount(t *testing.T) {
+	with := Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}}
+	envOf := func(r Resolution) map[string]string {
+		t.Helper()
+		r.Node, r.Modules = "anchor", []Manifest{aToolsModule(t, "nftables", "tools/index.js"), theRuntime(t)}
+		out, err := r.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		process := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
+		if process == nil {
+			t.Fatal("no runtime process was composed")
+		}
+		return process["env"].(map[string]string)
+	}
+	env := envOf(Resolution{Account: "ops", AgentAccount: "agent"})
+	if env[RuntimeAgentAccount] != "agent" || env[RuntimeAgentHome] != "/home/agent" || env[RuntimeOperatorAccount] != "ops" {
+		t.Errorf("the runtime is not told whom agents run as: %v", env)
+	}
+	env = envOf(Resolution{Account: "ops"})
+	if env[RuntimeAgentAccount] != "ops" || env[RuntimeAgentHome] != "/home/ops" {
+		t.Errorf("with no agent account, agents run as the operator: %v", env)
+	}
+	env = envOf(Resolution{})
+	if _, set := env[RuntimeAgentAccount]; set {
+		t.Errorf("a machine with no account names an agent account: %v", env)
+	}
+	if problems := bundleEnvProblems("x", Artifact{Name: "b", Kind: ArtifactBundle, Loads: []string{"x"},
+		Env: map[string]string{RuntimeAgentAccount: "me"}}); len(problems) == 0 {
+		t.Error("a bundle may tell the runtime whom agents run as")
+	}
+}

internal/catalogue/build.go

@@ -399,7 +399,7 @@ func versionOf(digest string) string {
 // telling the runtime what it is, which is the mesh's to say (novox/hq ADR 0192).
 var bundleEnvWords = map[string]bool{
 	RuntimeToolModules: true, RuntimeBrokerFile: true, RuntimeOperatorAccount: true,
-	RuntimeOperatorHome: true, RuntimeToolEnv: true,
+	RuntimeOperatorHome: true, RuntimeToolEnv: true, RuntimeAgentAccount: true, RuntimeAgentHome: true,
 }
 
 // bundleEnvProblems says what is wrong with what a bundle says it is given (novox/hq ADR 0192):

internal/catalogue/declaration.go

@@ -241,6 +241,31 @@ type Rendering struct {
 	// refuses a field it does not know, whole — so to it the field is not sent, and what it runs is
 	// judged by liveness alone.
 	ReadsHealth bool
+
+	// JudgesRoot says this machine's node-engine judges a user's declared `root` (novox/hq ADR 0266: its
+	// statement's contract is link.RootContract or later). To an older, strict engine the field is not
+	// sent, and the account it names is not judged — which the self-check says, as not judged.
+	JudgesRoot bool
+}
+
+// RootField is a user resource's field saying the account must never become root without a person
+// (novox/hq ADR 0266).
+const RootField = "root"
+
+// rootInto composes a user's `root` for the node-engine: taken away when it asserts nothing (empty — a
+// machine where agents run as the operator) or when the engine is older than the field and parses
+// strictly; kept as "never" otherwise.
+func rootInto(resource map[string]any, with Rendering) {
+	if resource["type"] != "user" {
+		return
+	}
+	value, has := resource[RootField]
+	if !has {
+		return
+	}
+	if s, _ := value.(string); s == "" || !with.JudgesRoot {
+		delete(resource, RootField)
+	}
 }
 
 // machinePort is where a module's port lives on this machine, or the port itself when the mesh has
@@ -981,6 +1006,9 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			// How it is ready, in the node-engine's words: its endpoint as the port this machine
 			// published it on — or not sent at all to an engine older than the field (ADR 0240).
 			healthInto(copied, m, with)
+			// And a user's `root` (novox/hq ADR 0266): sent only when it asserts something, to an engine
+			// that judges it.
+			rootInto(copied, with)
 			// The account's environment and every module's shell code, where this module holds the
 			// seat that places them (novox/hq ADR 0203, ADR 0204). Gathered from every module on
 			// the node, as the jails are, and **last of every placeholder pass**: shell code is a

internal/catalogue/machine_into_files.go

@@ -78,9 +78,47 @@ func machineFacts(r Resolution, names map[string]string, meshRange string) map[s
 		out["account"] = r.Account
 		out["account-home"] = accountHomeOf(r.Account, r.AccountHome)
 	}
+	// The account agents run as here, and whether it must never become root (novox/hq ADR 0266). The agent
+	// account where the node names one; the operator account otherwise, so a module writing the agent's
+	// home names one fact on every machine. `agent-root` is "never" only for an account of the agents' own:
+	// the user resource naming it then asks the node-engine to judge it, and on a machine where agents run
+	// as the operator it is empty, asserting nothing — the operator's account may become root there.
+	if agent, home := r.agentAccount(); agent != "" {
+		out["agent-account"] = agent
+		out["agent-home"] = home
+		out["agent-root"] = ""
+		if r.AgentAccount != "" {
+			out["agent-root"] = RootNever
+		}
+	}
 	return out
 }
 
+// RootNever is what a user resource's `root` says of an account that must never become root without a
+// person (novox/hq ADR 0266); the node-engine judges it.
+const RootNever = "never"
+
+// agentAccount is the account agents run as on this machine and its home: the agent account when the node
+// names one (novox/hq ADR 0266), else the operator account; empty when neither is known.
+func (r Resolution) agentAccount() (string, string) {
+	if r.AgentAccount != "" {
+		return r.AgentAccount, agentHomeOf(r.AgentAccount, r.AgentAccountHome)
+	}
+	if r.Account != "" {
+		return r.Account, accountHomeOf(r.Account, r.AccountHome)
+	}
+	return "", ""
+}
+
+// agentHomeOf is where the agent account's home is: what was stored, or /home/<account>. Never /root: the
+// agent account is never root.
+func agentHomeOf(account, home string) string {
+	if home != "" {
+		return home
+	}
+	return "/home/" + account
+}
+
 // accountHomeOf is where an account's home is: what was stored, or the derived default — /root for
 // root, /home/<account> otherwise. The one place the default is written, so a fact and the store
 // cannot disagree about it.
@@ -105,8 +143,10 @@ func machineInto(resource map[string]any, facts map[string]string, module string
 	// (novox/hq to-be 29), the same reason its content names ${machine:address}. And the name a
 	// `user` shape sets the login shell of, and the user a user-scoped unit or a process runs as:
 	// the shell module makes the operator's account its holder's login shell, and the desktop's
-	// watchers run as that account (novox/hq ADR 0176, ADR 0177) — neither can name the person.
-	for _, field := range []string{"path", "owner", "content", "name", "user"} {
+	// watchers run as that account (novox/hq ADR 0176, ADR 0177) — neither can name the person. And a
+	// user's `root`: the agent's module declares the account agents run as with ${machine:agent-root},
+	// "never" only where that account is the agents' own (novox/hq ADR 0266).
+	for _, field := range []string{"path", "owner", "content", "name", "user", "root"} {
 		s, ok := resource[field].(string)
 		if !ok {
 			continue

internal/catalogue/resolve.go

@@ -32,6 +32,11 @@ type Node struct {
 	// to-be 29). What a home-scoped file is owned by and what ${machine:account} resolves to.
 	Account     string
 	AccountHome string
+	// AgentAccount is the login agents run as here when it is not the operator's, AgentAccountHome its
+	// home when not derived (novox/hq ADR 0266). What ${machine:agent-account} resolves to; empty means
+	// agents run as the operator account.
+	AgentAccount     string
+	AgentAccountHome string
 }
 
 // World is what the rest of the mesh already has.
@@ -134,6 +139,10 @@ type Resolution struct {
 	// here without a store lookup.
 	Account     string
 	AccountHome string
+	// AgentAccount and AgentAccountHome are the account agents run as here when it is not the
+	// operator's, and its home (novox/hq ADR 0266); empty when agents run as the operator account.
+	AgentAccount     string
+	AgentAccountHome string
 	// Capabilities are the machine's, as its profile reported them, carried from the node so a
 	// contribution placed only where the machine has something (`if-capability`, novox/hq ADR 0255)
 	// is decided here without a store lookup.
@@ -703,7 +712,8 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 	}
 
 	resolution := Resolution{Node: node.Name, At: node.At, PublicDomain: node.PublicDomain,
-		Account: node.Account, AccountHome: node.AccountHome, Capabilities: node.Capabilities,
+		Account: node.Account, AccountHome: node.AccountHome, AgentAccount: node.AgentAccount,
+		AgentAccountHome: node.AgentAccountHome, Capabilities: node.Capabilities,
 		Because: because, Needs: needs, Unhostable: unhostable, Kept: kept}
 	for _, n := range providersFirst(order, catalogue) {
 		resolution.Modules = append(resolution.Modules, catalogue[n])

internal/catalogue/runtime.go

@@ -83,6 +83,11 @@ const (
 	RuntimeBrokerFile      = "MESH_BROKER_FILE"
 	RuntimeOperatorAccount = "MESH_OPERATOR_ACCOUNT"
 	RuntimeOperatorHome    = "MESH_OPERATOR_HOME"
+	// RuntimeAgentAccount and RuntimeAgentHome are the account agents run as on the machine and its home
+	// (novox/hq ADR 0266): the agent account where the node names one, the operator account otherwise.
+	// The agent's module writes the agent's home from them; absent where neither account is known.
+	RuntimeAgentAccount = "MESH_AGENT_ACCOUNT"
+	RuntimeAgentHome    = "MESH_AGENT_HOME"
 	// RuntimeToolEnv is every served module's composed environment, as JSON (novox/hq ADR 0192):
 	// {"<module>": {"<word>": "<value>"}}. The runtime takes it at start, removes it from its own
 	// environment and hands each module's words to that module's bundles alone. In the unit, so a
@@ -215,6 +220,10 @@ func (r Resolution) runtimeProcess(with Rendering) (map[string]any, error) {
 		env[RuntimeOperatorHome] = accountHomeOf(r.Account, r.AccountHome)
 		process["user"] = r.Account
 	}
+	if agent, home := r.agentAccount(); agent != "" {
+		env[RuntimeAgentAccount] = agent
+		env[RuntimeAgentHome] = home
+	}
 	// Routed through the artifact store as this network reaches it now, like everything the mesh
 	// built; refused with the same words when there is no store to route through.
 	if err := artifactsInto(process, RuntimeModule, with); err != nil {