Replace a value given by hand like one the mesh made (hq ADR 0228)

A given own secret the module reads at start is held by nobody but that
module, so the mesh need not read it to replace it: secret rotate now
works on it, and a value given through secret accept is replaced on its
own after the module's first good start under the mesh. Only a value an
outside party issues (own-secrets "issued-by": "outside") or one the
module applies stays as given, refused with the reason.

cmd/mesh-controller/given.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// A value given by hand lives only until the module's first good start (novox/hq ADR 0228).
+//
+// The serving controller hears every report; a clean one about the declaration a machine was last
+// sent is the signal the store asks about (inventory.ReplaceGivenAfterStart). What it replaced is
+// sent at once, said in the log and stated on the bus as the controller seat's `secret-replaced`,
+// so a replacement is never silent. **Not in the hand-act log**: nobody acted by hand, and that log
+// is read as the count of repairs a healer is wanted for.
+
+// SecretReplaced is the controller seat's fact that a value given by hand was replaced
+// (link.KeySecretReplaced). Never the value: neither the old one, which the mesh cannot read,
+// nor the new one, sealed to the machine as it was made.
+type SecretReplaced struct {
+	Node   string    `json:"node"`
+	Module string    `json:"module"`
+	Name   string    `json:"name"`
+	Given  time.Time `json:"given"`
+	// Sent are the machines sent so the module starts again on the new value; Unsent says why
+	// they could not be, in which case the next push carries it.
+	Sent   []string `json:"sent"`
+	Unsent string   `json:"unsent,omitempty"`
+	Why    string   `json:"why"`
+}
+
+// givenEvents is where the serving controller states it; nil in a command.
+var givenEvents link.Bus
+
+// replacing keeps one replacement per machine at a time: two reports arriving together find the
+// same rows, and the store's claim makes one of them the replacer, but the sends need not race.
+var replacing sync.Map
+
+// startedWell says a report is a machine's clean account of a declaration: everything applied,
+// nothing failed or refused. Whether it is the declaration last sent is the store's to answer.
+func startedWell(report link.Report) bool {
+	return report.Declared != "" && report.Refused == "" && len(report.Failed) == 0 && report.Applied != nil
+}
+
+const givenWhy = "a value given by hand lives only until its module's first good start under the mesh (novox/hq ADR 0228)"
+
+// replaceGiven replaces what the report makes due, sends the machines, and says so.
+func replaceGiven(ctx context.Context, open *stores, report link.Report) {
+	if _, busy := replacing.LoadOrStore(report.Node, true); busy {
+		return
+	}
+	defer replacing.Delete(report.Node)
+	replaced, err := open.inventory.ReplaceGivenAfterStart(ctx, report.Node, report.Declared)
+	if err != nil {
+		log.Printf("a value given by hand on %s could not be replaced after its module started: %v", report.Node, err)
+	}
+	for _, r := range replaced {
+		said := SecretReplaced{Node: report.Node, Module: r.Module, Name: r.Name, Given: r.Given.UTC(),
+			Sent: r.Machines, Why: givenWhy}
+		log.Printf("replaced %q of %s on %s, given %s, with a value the mesh made: %s; sending %s",
+			r.Name, r.Module, report.Node, r.Given.UTC().Format(time.RFC3339), givenWhy, strings.Join(r.Machines, ", "))
+		if err := sendTo(ctx, open, r.Machines); err != nil {
+			said.Sent, said.Unsent = nil, err.Error()
+			log.Printf("the new %q of %s is sealed and not yet delivered to %s — the next push carries it: %v",
+				r.Name, r.Module, strings.Join(r.Machines, ", "), err)
+		}
+		stateReplaced(ctx, said)
+	}
+}
+
+func stateReplaced(ctx context.Context, said SecretReplaced) {
+	if givenEvents == nil {
+		return
+	}
+	body, err := json.Marshal(said)
+	if err != nil {
+		log.Printf("could not say that %s's %q was replaced: %v", said.Module, said.Name, err)
+		return
+	}
+	stating, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	if err := givenEvents.PublishSeatEvent(stating, link.MeshControllerSeat, link.KeySecretReplaced, body); err != nil {
+		log.Printf("could not say that %s's %q was replaced: %v", said.Module, said.Name, err)
+	}
+}

cmd/mesh-controller/given_test.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// A rotation asked through the seat carries why to the command, which records it in the hand-act
+// log (novox/hq ADR 0228); why with a provision is refused as passed over, not dropped.
+func TestARotationThroughTheSeatCarriesWhy(t *testing.T) {
+	argv, err := argvFor("rotate", map[string]any{"node": "anchor", "module": "letta",
+		"secret": "server-password", "why": "leaked into logs", "cause": "leaked"})
+	if err != nil || strings.Join(argv, " ") != "secret rotate anchor letta server-password --why leaked into logs --cause leaked" {
+		t.Fatalf("%v %v", argv, err)
+	}
+	argv, err = argvFor("rotate", map[string]any{"node": "anchor", "module": "letta", "secret": "server-password"})
+	if err != nil || strings.Join(argv, " ") != "secret rotate anchor letta server-password" {
+		t.Fatalf("without why: %v %v", argv, err)
+	}
+	if argv, err := argvFor("rotate", map[string]any{"provision": "postgres-database", "why": "leaked"}); err == nil {
+		t.Fatalf("why beside a provision was passed over: %v", argv)
+	}
+}
+
+// Only a clean account of a declaration is a good start; a refusal, a failure or a bare word that
+// the machine is there is not (novox/hq ADR 0228).
+func TestAGoodStartIsACleanAccountOfADeclaration(t *testing.T) {
+	for _, c := range []struct {
+		report link.Report
+		good   bool
+	}{
+		{link.Report{Node: "anchor", Declared: "d", Applied: []string{"container:letta"}}, true},
+		{link.Report{Node: "anchor", Declared: "d", Applied: []string{}}, true},
+		{link.Report{Node: "anchor"}, false},
+		{link.Report{Node: "anchor", Applied: []string{"x"}}, false},
+		{link.Report{Node: "anchor", Declared: "d", Applied: []string{"x"}, Failed: map[string]string{"y": "no"}}, false},
+		{link.Report{Node: "anchor", Declared: "d", Refused: "older"}, false},
+	} {
+		if got := startedWell(c.report); got != c.good {
+			t.Errorf("%+v: a good start = %v, want %v", c.report, got, c.good)
+		}
+	}
+}

cmd/mesh-controller/push.go

@@ -109,7 +109,7 @@ func serve(ctx context.Context) error {
 	// `status` from a summary kept current here (novox/hq to-be 45 Phase 0): a machine saying
 	// something new is one thing that moves it, so the listener nudges it.
 	statusFrom = newStatusSummary(composeStatus(open))
-	server, err := connectLink(ctx, inv, work, nudgingListener{work, statusFrom})
+	server, err := connectLink(ctx, inv, work, nudgingListener{Enrolment: work, summary: statusFrom, open: open})
 	if err != nil {
 		return err
 	}
@@ -166,6 +166,8 @@ func serve(ctx context.Context) error {
 	}
 	// The hand-act log is counted for `status` on this connection rather than a new one a minute.
 	handActConn = bus.Conn
+	// And says when it replaced a value given by hand (novox/hq ADR 0228).
+	givenEvents = bus
 	// Composed now and kept current, before the verb that answers from it is served.
 	go statusFrom.keep(ctx)
 	// A call that outlasts its caller's patience is followed by `calls` (novox/hq issue 265).

cmd/mesh-controller/seatverbs.go

@@ -482,7 +482,15 @@ func (a *verbArguments) commandLine() ([]string, error) {
 			if err := need("node", "module", "secret"); err != nil {
 				return nil, fmt.Errorf("%w: a module's own secret is named by node, module and secret together", err)
 			}
-			return []string{"secret", "rotate", str("node"), str("module"), str("secret")}, nil
+			argv := []string{"secret", "rotate", str("node"), str("module"), str("secret")}
+			// Why, recorded in the hand-act log (novox/hq ADR 0228); a cause only beside a why.
+			if w := str("why"); w != "" {
+				argv = append(argv, "--why", w)
+				if c := str("cause"); c != "" {
+					argv = append(argv, "--cause", c)
+				}
+			}
+			return argv, nil
 		}
 		// Neither shape: the command says its usage, which names both, and that is the answer the
 		// caller needs.

cmd/mesh-controller/secret.go

@@ -93,18 +93,31 @@ func secretCommand(ctx context.Context, args []string) error {
 		fmt.Printf("  run `push %s` and `push %s` to send it\n", *provider, node)
 		return nil
 	}
-	if err := open.inventory.AcceptSecretForModule(ctx, node, module, name, value); err != nil {
+	untilStart, err := open.inventory.AcceptGivenSecret(ctx, node, module, name, value)
+	if err != nil {
 		return err
 	}
 	// Not printed back, and there is nowhere it could be printed from: it is sealed to that
 	// machine and the mesh cannot read it again.
 	fmt.Printf("%s on %s now holds %q, sealed to that machine.\n", module, node, name)
-	fmt.Printf("  the mesh cannot read it back, and will not replace it with one of its own\n")
+	if untilStart {
+		// Accepted, and said what it is for (novox/hq ADR 0228): a value given by hand adopts
+		// something that already holds it, and lives only until the module has started on it.
+		fmt.Printf("  it lives until %s next starts well under the mesh on it, and is then replaced with a value\n"+
+			"  the mesh makes, sealed and sent (ADR 0228): a value given by hand is for adopting something\n"+
+			"  already running that holds it\n", module)
+		if record, err := open.inventory.NodeByName(ctx, node); err == nil && !record.Adopted {
+			fmt.Printf("  %s is not an adopted machine: if %s is installed fresh there, it needs no given value —\n"+
+				"  the mesh makes one at the first push\n", node, module)
+		}
+	} else {
+		fmt.Printf("  the mesh cannot read it back, and will not replace it with one of its own\n")
+	}
 	fmt.Printf("  run `push %s` to send it\n", node)
 	return nil
 }
 
-const secretUsage = "secret rotate <node> <module> <name>\n" +
+const secretUsage = "secret rotate <node> <module> <name> [--why <text> [--cause <word>]]\n" +
 	"secret accept <node> <module> <name> [--from <file>] [--provider <node> [--local <name>]]\n" +
 	"secret recover <node> <module> <name> --key <operator-key> [--out <file>] [--from-export <file>] [--provider <node>]\n" +
 	"secret export [--out <file>]"
@@ -367,9 +380,20 @@ func valueFor(node, module, name, from string) (string, error) {
 // secretRotate makes a module's own secret anew and sends the machine, so the module starts again on
 // the new value (novox/hq ADR 0114, issue 180). A pair credential rotates with `rotate <provision>`;
 // this is the secret with one party. Said in the log with who asked and when, never the value.
+//
+// **A value given to the mesh rotates the same way** (novox/hq ADR 0228): what a module reads at start
+// is held by nobody else, so the old value is not needed to replace it. Refused for a value an
+// outside party issued, which no value of the mesh's would replace. Why it was rotated is recorded in
+// the hand-act log when given — a rotation asked by a person is an act by hand, and a leak is a cause
+// worth counting.
 func secretRotate(ctx context.Context, args []string) error {
-	rest, _ := split(args)
-	if len(rest) != 3 {
+	rest, flags := split(args)
+	set := flag.NewFlagSet("secret rotate", flag.ContinueOnError)
+	why := addHandActFlags(set)
+	if err := set.Parse(flags); err != nil {
+		return err
+	}
+	if len(rest) != 3 || set.NArg() != 0 {
 		return errors.New(secretUsage)
 	}
 	node, module, name := rest[0], rest[1], rest[2]
@@ -378,6 +402,10 @@ func secretRotate(ctx context.Context, args []string) error {
 		return err
 	}
 	defer open.Close()
+	origin, given, err := open.inventory.OwnSecretOrigin(ctx, node, module, name)
+	if err != nil {
+		return err
+	}
 	if err := open.inventory.RotateModuleSecret(ctx, node, module, name); err != nil {
 		var refused inventory.ErrNotRotatable
 		if errors.As(err, &refused) {
@@ -385,8 +413,13 @@ func secretRotate(ctx context.Context, args []string) error {
 		}
 		return err
 	}
+	why.record(ctx, "secret rotate", []string{node, module, name})
 	fmt.Printf("rotated %q of %s on %s at %s, asked by %s; the value is sealed and not shown\n",
 		name, module, node, time.Now().UTC().Format(time.RFC3339), whoAsked())
+	if origin == inventory.OriginAccepted {
+		fmt.Printf("  it replaces the value given to the mesh on %s: the mesh made this one, so `secret rotate` "+
+			"replaces it again whenever asked (ADR 0228)\n", given.UTC().Format("2006-01-02"))
+	}
 	// A shared credential (ADR 0158) has as many holders as the provision has consumers, and all
 	// of them are sent in one act, so no machine is left reading a value the provider no longer takes.
 	machines, err := open.inventory.SharedHolders(ctx, node, module, name)

cmd/mesh-controller/status_summary.go

@@ -178,6 +178,9 @@ var readingVerbs = map[string]bool{
 type nudgingListener struct {
 	link.Enrolment
 	summary *statusSummary
+	// open is the serving controller's stores, for replacing a given value after a module's first
+	// good start (novox/hq ADR 0228).
+	open *stores
 }
 
 func (l nudgingListener) Heard(ctx context.Context, report link.Report) (bool, error) {
@@ -189,5 +192,10 @@ func (l nudgingListener) Heard(ctx context.Context, report link.Report) (bool, e
 	if news {
 		l.summary.nudge()
 	}
+	if err == nil && l.open != nil && startedWell(report) {
+		// Off the report's path: replacing a given value sends the machine, and a report waits for
+		// nothing it caused (novox/hq ADR 0228).
+		go replaceGiven(context.WithoutCancel(ctx), l.open, report)
+	}
 	return news, err
 }