Serve a trusted holder from a runtime of its own account, refuse it in the machine's runtime, and say while an agent can become root where it runs (hq ADR 0259 §8)

internal/catalogue/declaration.go

@@ -1101,9 +1101,23 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 		}
 		owner[fmt.Sprint(process["id"])] = RuntimeModule
 		out = append(out, process)
-		// What each module's bundles are given is read as the account the runtime runs as.
+		// And a runtime of its own for each module of its own account, after it (novox/hq ADR 0259 §8).
+		owns, err := r.ownRuntimes(with)
+		if err != nil {
+			return nil, err
+		}
+		for _, p := range owns {
+			id := fmt.Sprint(p["id"])
+			owner[id] = strings.TrimSuffix(id, "."+OwnRuntimeID())
+			out = append(out, p)
+		}
+		// What each module's bundles are given is read as the account the runtime runs as — not what a
+		// module of its own account is given, which its own account reads.
 		words := map[string]map[string]string{}
 		for _, m := range r.Modules {
+			if m.RunsAs != "" {
+				continue
+			}
 			w, err := bundleWords(m, with)
 			if err != nil {
 				return nil, err

internal/catalogue/kinded_test.go

@@ -8,7 +8,7 @@ import (
 // The router of novox/hq ADR 0259: it declares the operator's seat and the two kinded benches.
 func router() Manifest {
 	return Manifest{Module: "messenger", Tools: []string{"open", "history", "notify"},
-		State: []StateDeclaration{{Name: "asks"}},
+		State: []StateDeclaration{{Name: "asks"}}, RunsAs: "messenger", SecretsOwner: "messenger",
 		DefinesSeats: []SeatDeclaration{
 			{Name: "operator-channel", Scope: ScopeMesh, Accepts: []string{"ask", "cancel"}, Emits: []string{"decided"},
 				ByCaller: []string{"ask", "cancel", "decided"}, Records: []string{"asks"},
@@ -98,6 +98,7 @@ func TestEachKindIsItsOwnHolderWhenResolved(t *testing.T) {
 func TestCapabilitiesAreTheVocabularysAndOnlyOnAKindedClaim(t *testing.T) {
 	good := aChannel("telegram", "telegram")
 	good.Claims[0].Capabilities = []string{"deliver", "choice", "verified-sender", "max-length:4096"}
+	good.RunsAs = "telegram"
 	if got := problemsFor(t, Shelf{"messenger": router(), "telegram": good}); got != "" {
 		t.Fatalf("the vocabulary was refused: %s", got)
 	}
@@ -114,3 +115,47 @@ func TestCapabilitiesAreTheVocabularysAndOnlyOnAKindedClaim(t *testing.T) {
 		t.Errorf("capabilities on a seat that is not kinded stood: %s", got)
 	}
 }
+
+// novox/hq ADR 0259 §8: a module saying warrants, or speaking for a kind that proves its sender, runs as an
+// account of its own — never carried by the machine's runtime, which runs as the operator's account.
+func TestATrustedHolderMustRunAsAnAccountOfItsOwn(t *testing.T) {
+	r := router()
+	r.RunsAs = ""
+	if got := problemsFor(t, Shelf{"messenger": r}); !strings.Contains(got, "messenger must run as an account of its own") {
+		t.Errorf("a router on the machine's runtime stood: %s", got)
+	}
+	tg := aChannel("telegram", "telegram")
+	tg.Claims[0].Capabilities = []string{"choice", "verified-sender"}
+	if got := problemsFor(t, Shelf{"messenger": router(), "telegram": tg}); !strings.Contains(got, "telegram must run as an account of its own") {
+		t.Errorf("a verified channel on the machine's runtime stood: %s", got)
+	}
+	desk := aChannel("desk-channel", "desktop")
+	desk.Claims[0].Capabilities = []string{"choice"}
+	if got := problemsFor(t, Shelf{"messenger": router(), "desk-channel": desk}); got != "" {
+		t.Errorf("a channel proving nothing was held to it: %s", got)
+	}
+}
+
+func TestRunsAsIsAnAccountOfTheModulesOwn(t *testing.T) {
+	ok := Manifest{Module: "telegram", RunsAs: "telegram", SecretsOwner: "telegram",
+		OwnSecrets: OwnSecrets{"broker": {Path: "/var/lib/telegram/broker"}},
+		Resources:  []map[string]any{{"id": "account", "type": "user", "name": "telegram"}}}
+	if got := RunsAsProblems(ok); len(got) != 0 {
+		t.Fatalf("a sound runs-as was refused: %v", got)
+	}
+	for want, change := range map[string]func(*Manifest){
+		"never root":                 func(m *Manifest) { m.RunsAs, m.SecretsOwner = "root", "root" },
+		"not an account name":        func(m *Manifest) { m.RunsAs = "${machine:account}" },
+		"which it does not make":     func(m *Manifest) { m.Resources = nil },
+		"declares no own secret":     func(m *Manifest) { m.OwnSecrets = nil },
+		"they are the account's own": func(m *Manifest) { m.SecretsOwner = "" },
+	} {
+		m := ok
+		m.Resources = append([]map[string]any(nil), ok.Resources...)
+		m.OwnSecrets = OwnSecrets{"broker": {Path: "/x"}}
+		change(&m)
+		if got := strings.Join(RunsAsProblems(m), "; "); !strings.Contains(got, want) {
+			t.Errorf("want %q, got %q", want, got)
+		}
+	}
+}

internal/catalogue/manifest.go

@@ -647,6 +647,13 @@ type Manifest struct {
 	// cannot use.
 	SecretsOwner string `json:"secrets-owner,omitempty"`
 
+	// RunsAs is the account this module's tools bundle runs as, in a runtime of its own on a bus account of
+	// its own (novox/hq ADR 0259 §8): never the machine's runtime, which runs as the operator's account and
+	// carries every module on the machine. The account is one the module makes (a `user` resource of that
+	// name), owns its secrets (`secrets-owner`), and is neither root nor the operator's. Required of a module
+	// that says a warrant, or speaks for a channel kind that proves its sender.
+	RunsAs string `json:"runs-as,omitempty"`
+
 	// Keeps is where this module wants every operator-sealed secret in the mesh written — the
 	// vault's field, and so far nobody else's (novox/hq ADR 0085, amended).
 	//
@@ -1627,6 +1634,7 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	// prefix. Whether a seat anybody names exists, and whether a holder answers for it, are
 	// facts about the catalogue and are checked at registration (CatalogueProblems).
 	problems = append(problems, declaredSeatProblems(m)...)
+	problems = append(problems, RunsAsProblems(m)...)
 	if m.Computed != "" && len(m.Resources) > 0 {
 		// One or the other. A module that both ships files and has them computed would leave
 		// nobody able to say where a given file came from.

internal/catalogue/runtime.go

@@ -170,6 +170,10 @@ func (r Resolution) runtimeProcess(with Rendering) (map[string]any, error) {
 		if with.Adopted && m.Filtering != nil {
 			continue
 		}
+		if m.RunsAs != "" {
+			// Served by a runtime of its own, on its own account (ownRuntimes): never the machine's.
+			continue
+		}
 		words, err := bundleWords(m, with)
 		if err != nil {
 			return nil, err
@@ -232,6 +236,84 @@ func (r Resolution) runtimeProcess(with Rendering) (map[string]any, error) {
 	return process, nil
 }
 
+// OwnRuntimeID names the process a module of its own account is served by (novox/hq ADR 0259 §8).
+func OwnRuntimeID() string { return "own-runtime" }
+
+// ownRuntimes are the processes the modules of their own account are served by (novox/hq ADR 0259 §8): each
+// the machine's runtime program — the same build, run from the same source — serving that one module alone,
+// as the module's own account, on the module's own bus credential. Never the machine's runtime, which runs
+// as the operator's account and carries every module on the machine.
+func (r Resolution) ownRuntimes(with Rendering) ([]map[string]any, error) {
+	var own []Manifest
+	for _, m := range r.Modules {
+		if m.RunsAs != "" && !(with.Adopted && m.Filtering != nil) {
+			own = append(own, m)
+		}
+	}
+	if len(own) == 0 {
+		return nil, nil
+	}
+	var runtime *Manifest
+	for i := range r.Modules {
+		if r.Modules[i].Module == RuntimeModule {
+			runtime = &r.Modules[i]
+		}
+	}
+	if runtime == nil || len(runtime.Bundles) != 1 || runtime.Bundles[0].Binary == "" {
+		return nil, fmt.Errorf("%s runs as its own account in a runtime of its own, and %s is not here to run it "+
+			"from: assign %s to %s first (novox/hq ADR 0259)", own[0].Module, RuntimeModule, RuntimeModule, r.Node)
+	}
+	program := runtime.Bundles[0]
+	var out []map[string]any
+	for _, m := range own {
+		credential, declared := m.OwnSecrets["broker"]
+		if !declared {
+			return nil, fmt.Errorf("%s runs as its own account and declares no own secret broker", m.Module)
+		}
+		var served, restartOn []string
+		for _, b := range m.Bundles {
+			for _, load := range b.Loads {
+				if launcher, has := b.Launchers[load]; has {
+					load = launcher
+				}
+				served = append(served, m.Module+"="+BundlePath(m.Module, b.Name)+"/"+load)
+			}
+			if len(b.Loads) > 0 {
+				restartOn = append(restartOn, m.Module+"."+BundleID(b.Name))
+			}
+		}
+		if len(served) == 0 {
+			return nil, fmt.Errorf("%s runs as its own account and its build produced no bundle to serve", m.Module)
+		}
+		sort.Strings(served)
+		restartOn = append(restartOn, m.Module+"."+NeedID("broker"))
+		sort.Strings(restartOn)
+		env := map[string]string{RuntimeToolModules: strings.Join(served, ","), RuntimeBrokerFile: credential.Path}
+		words, err := bundleWords(m, with)
+		if err != nil {
+			return nil, err
+		}
+		if len(words) > 0 {
+			body, err := json.Marshal(map[string]map[string]string{m.Module: words})
+			if err != nil {
+				return nil, err
+			}
+			env[RuntimeToolEnv] = string(body)
+		}
+		process := map[string]any{
+			"id": m.Module + "." + OwnRuntimeID(), "type": "process", "name": m.Module + "-runtime",
+			"source": program.Source, "digest": program.Digest,
+			"run": []any{"./" + program.Binary}, "env": env, "restart-on": toAny(restartOn),
+			"user": m.RunsAs,
+		}
+		if err := artifactsInto(process, RuntimeModule, with); err != nil {
+			return nil, err
+		}
+		out = append(out, process)
+	}
+	return out, nil
+}
+
 func toAny(in []string) []any {
 	out := make([]any, 0, len(in))
 	for _, s := range in {

internal/catalogue/runtime_test.go

@@ -457,3 +457,49 @@ func TestAGoToolsBundleIsServedByItsBinary(t *testing.T) {
 		t.Error("a Go bundle loading a file it does not contain was admitted")
 	}
 }
+
+// novox/hq ADR 0259 §8: a module of its own account is served by a runtime of its own — the machine's
+// runtime program, as that account, on that module's own credential — and never by the machine's runtime,
+// which runs as the operator's account and is given none of its words.
+func TestAModuleOfItsOwnAccountIsServedByARuntimeOfItsOwn(t *testing.T) {
+	with := Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}, "telegram": {"broker": "own"}}}
+	goRuntime := Manifest{Module: RuntimeModule, Version: "1",
+		OwnSecrets: OwnSecrets{"broker": {Path: "/var/lib/mesh/" + RuntimeModule + "/broker"}},
+		Build: &Build{Artifacts: []Artifact{{Name: "runtime", Kind: ArtifactBundle, Language: "go",
+			System: "arch", From: "cmd/node-tools"}}}}
+	goRuntime, err := goRuntime.Resolve([]Built{{Name: "runtime", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + RuntimeModule + "/runtime/blobs/" + bundleDigest, Digest: bundleDigest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	telegram := aToolsModule(t, "telegram", "tools/index.js")
+	telegram.RunsAs, telegram.SecretsOwner = "telegram", "telegram"
+	telegram.OwnSecrets = OwnSecrets{"broker": {Path: "/var/lib/telegram/broker"}}
+	out, err := Resolution{Node: "anchor", Account: "ops",
+		Modules: []Manifest{aToolsModule(t, "nftables", "tools/index.js"), telegram, goRuntime}}.Declaration(with)
+	if err != nil {
+		t.Fatal(err)
+	}
+	machine := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
+	if served := machine["env"].(map[string]string)[RuntimeToolModules]; strings.Contains(served, "telegram") || !strings.Contains(served, "nftables") {
+		t.Errorf("the machine's runtime serves %q", served)
+	}
+	own := fileNamed(out, "telegram."+OwnRuntimeID())
+	if own == nil {
+		t.Fatalf("telegram has no runtime of its own: %v", ids(out))
+	}
+	env := own["env"].(map[string]string)
+	if own["user"] != "telegram" || fmt.Sprint(own["run"]) != "[./node-tools]" ||
+		env[RuntimeBrokerFile] != "/var/lib/telegram/broker" ||
+		env[RuntimeToolModules] != "telegram="+BundleRoot+"/telegram/tools/tools/index.js" {
+		t.Errorf("its own runtime: user %v run %v env %v", own["user"], own["run"], env)
+	}
+	if _, told := env[RuntimeOperatorAccount]; told {
+		t.Error("a runtime of a module's own account is told the operator's account")
+	}
+	// Without the machine's runtime to run it from, it is refused in words.
+	if _, err := (Resolution{Node: "anchor", Modules: []Manifest{telegram}}).ownRuntimes(with); err == nil {
+		t.Error("a module of its own account composed without a runtime program")
+	}
+}

internal/catalogue/seats_declared.go

@@ -321,6 +321,16 @@ func CatalogueProblems(shelf Shelf) []string {
 			}
 		}
 	}
+	// **A trusted holder runs as its own account** (novox/hq ADR 0259 §8): a module saying warrants, or
+	// speaking for a kind that proves its sender, is never carried by a machine's runtime.
+	for _, module := range shelfOrder(shelf) {
+		m := shelf[module]
+		if why := TrustedHolding(m, declared); why != "" && m.RunsAs == "" {
+			problems = append(problems, fmt.Sprintf(
+				"%s must run as an account of its own (runs-as): %s, and the machine's runtime runs as the "+
+					"operator's account, which every agent runs as (novox/hq ADR 0259)", module, why))
+		}
+	}
 	// A read of a module's state that module does not keep (novox/hq ADR 0201) — said only where the
 	// owner is on the shelf, as a consumer may be installed before its emitter.
 	var manifests []Manifest
@@ -416,3 +426,65 @@ func shelfOrder(shelf Shelf) []string {
 	sort.Strings(out)
 	return out
 }
+
+var accountName = regexp.MustCompile(`^[a-z_][a-z0-9_-]{0,30}$`)
+
+// RunsAsProblems is what one manifest's `runs-as` is held to (novox/hq ADR 0259 §8): an account of the
+// module's own making — a `user` resource of that name — that owns its secrets, with a bus account of its own,
+// and that is neither root nor the operator's.
+func RunsAsProblems(m Manifest) []string {
+	if m.RunsAs == "" {
+		return nil
+	}
+	var problems []string
+	say := func(format string, a ...any) { problems = append(problems, fmt.Sprintf(format, a...)) }
+	switch {
+	case !accountName.MatchString(m.RunsAs):
+		say("%s runs as %q, which is not an account name of the module's own", m.Module, m.RunsAs)
+		return problems
+	case m.RunsAs == "root":
+		say("%s runs as root; a module of its own account runs as an account it makes, never root", m.Module)
+	}
+	made := false
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "user" && fmt.Sprint(r["name"]) == m.RunsAs {
+			made = true
+		}
+	}
+	if !made {
+		say("%s runs as %s, which it does not make: a user resource named %s", m.Module, m.RunsAs, m.RunsAs)
+	}
+	if _, has := m.OwnSecrets["broker"]; !has {
+		say("%s runs as its own account and declares no own secret broker: its runtime reaches the bus on an "+
+			"account of its own", m.Module)
+	}
+	if m.SecretsOwner != m.RunsAs {
+		say("%s runs as %s, and its secrets belong to %q: they are the account's own", m.Module, m.RunsAs, m.SecretsOwner)
+	}
+	return problems
+}
+
+// TrustedHolding is why a module must run as its own account (novox/hq ADR 0259 §8), or "": it holds a seat
+// whose events it says to one caller each (a warrant), or speaks for a kind of a kinded bench that proves
+// its sender. Neither may be carried by the machine's runtime, which runs as the operator's account.
+func TrustedHolding(m Manifest, declared map[string]SeatDeclaration) string {
+	for _, c := range m.Claims {
+		s, ok := declared[c.Name]
+		if !ok {
+			continue
+		}
+		for _, e := range s.Emits {
+			if s.NamedByCaller(e) {
+				return fmt.Sprintf("it holds %s, whose %s it says to one caller each", c.Name, e)
+			}
+		}
+		if s.Kinded {
+			for _, capability := range c.Capabilities {
+				if capability == "verified-sender" {
+					return fmt.Sprintf("it holds %s of kind %s, which proves its sender", c.Name, c.Kind)
+				}
+			}
+		}
+	}
+	return ""
+}