A module's own secret rotates when its definition says the module reads it at start (hq 180)

`secret rotate <node> <module> <name>` makes the secret anew the way the first mint did, seals it
to the machine and the operator, and sends the machine, so the module starts again on the new value
— said in the log with who asked and when, never the value. Only for a secret whose definition says
`"taken": "at-start"`: an own secret is now a path, or {path, taken}, and a definition that says
nothing of how a secret is taken is refused with the word to write, because a credential rotated
under software that never reads it again is worse than one left alone (issue 179). `applied` is
refused by name until the staged form ADR 0114 decided is built; a value given to the mesh is
refused as ADR 0113 says. `rotate` is a verb on the controller's seat with two shapes — a pair
credential by provision, an own secret by machine, module and name — so the console can ask.
Registered manifests keep their bytes: a path alone is written back as a path.

cmd/mesh-controller/modules_test.go

@@ -11,7 +11,7 @@ import (
 // A module that declares none is refused before the account exists, so the bus never carries an
 // account nothing reads (novox/hq 04-ISSUES/078).
 func TestAModuleWithNoBrokerSecretCannotBeIssued(t *testing.T) {
-	err := mayIssue(catalogue.Manifest{Module: "step-ca", OwnSecrets: map[string]string{"password": "/run/password"}})
+	err := mayIssue(catalogue.Manifest{Module: "step-ca", OwnSecrets: catalogue.OwnSecrets{"password": {Path: "/run/password"}}})
 	if err == nil {
 		t.Fatal("a module with no broker own secret was issued an account")
 	}
@@ -20,7 +20,7 @@ func TestAModuleWithNoBrokerSecretCannotBeIssued(t *testing.T) {
 			t.Errorf("the refusal does not say %q: %v", want, err)
 		}
 	}
-	if err := mayIssue(catalogue.Manifest{Module: "redis", OwnSecrets: map[string]string{"broker": "/run/broker"}}); err != nil {
+	if err := mayIssue(catalogue.Manifest{Module: "redis", OwnSecrets: catalogue.OwnSecrets{"broker": {Path: "/run/broker"}}}); err != nil {
 		t.Errorf("a module declaring its broker secret was refused: %v", err)
 	}
 }

cmd/mesh-controller/seatverbs.go

@@ -87,6 +87,20 @@ func argvFor(verb string, args map[string]any) ([]string, error) {
 			return []string{"push", n, "--wait", "0"}, nil
 		}
 		return []string{"push", "--behind", "--wait", "0"}, nil
+	case "rotate":
+		if p := str("provision"); p != "" {
+			argv := []string{"rotate", p}
+			if c := str("consumer"); c != "" {
+				argv = append(argv, "--consumer", c)
+			}
+			return argv, nil
+		}
+		if str("node") != "" && str("module") != "" && str("secret") != "" {
+			return []string{"secret", "rotate", str("node"), str("module"), str("secret")}, nil
+		}
+		// Half of either shape: the command says its usage, which names both shapes, and that is
+		// the answer the caller needs.
+		return []string{"rotate"}, nil
 	case "build":
 		if err := need("repository"); err != nil {
 			return nil, err

cmd/mesh-controller/seatverbs_test.go

@@ -56,6 +56,23 @@ func TestTheBuildToolTellsAForgePathFromAURL(t *testing.T) {
 	}
 }
 
+// `rotate` is one verb with two shapes (ADR 0114, issue 180): a pair credential by provision, or a
+// module's own secret by machine, module and name.
+func TestRotateTakesAProvisionOrAnOwnSecret(t *testing.T) {
+	argv, _ := argvFor("rotate", map[string]any{"provision": "postgres-database", "consumer": "ace"})
+	if strings.Join(argv, " ") != "rotate postgres-database --consumer ace" {
+		t.Fatalf("a pair credential: %v", argv)
+	}
+	argv, _ = argvFor("rotate", map[string]any{"node": "ace", "module": "nodered", "secret": "api-token"})
+	if strings.Join(argv, " ") != "secret rotate ace nodered api-token" {
+		t.Fatalf("an own secret: %v", argv)
+	}
+	argv, _ = argvFor("rotate", map[string]any{"node": "ace"})
+	if strings.Join(argv, " ") != "rotate" {
+		t.Fatalf("half an own secret falls to the command's usage: %v", argv)
+	}
+}
+
 // A required argument missing is refused in the verb's own words, before anything runs.
 func TestAVerbMissingWhatItNeedsIsRefused(t *testing.T) {
 	if _, err := argvFor("node", map[string]any{}); err == nil || !strings.Contains(err.Error(), `node needs "node"`) {

cmd/mesh-controller/secret.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"os"
 	"strings"
+	"time"
 
 	"github.com/novox/mesh-controller/internal/catalogue"
 	"github.com/novox/mesh-controller/internal/inventory"
@@ -38,6 +39,8 @@ func secretCommand(ctx context.Context, args []string) error {
 	}
 	switch args[0] {
 	case "accept":
+	case "rotate":
+		return secretRotate(ctx, args[1:])
 	case "recover":
 		return secretRecover(ctx, args[1:])
 	case "export":
@@ -101,7 +104,8 @@ func secretCommand(ctx context.Context, args []string) error {
 	return nil
 }
 
-const secretUsage = "secret accept <node> <module> <name> [--from <file>] [--provider <node> [--local <name>]]\n" +
+const secretUsage = "secret rotate <node> <module> <name>\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>]"
 
@@ -359,3 +363,46 @@ func valueFor(node, module, name, from string) (string, error) {
 		return line, nil
 	}
 }
+
+// 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.
+func secretRotate(ctx context.Context, args []string) error {
+	rest, _ := split(args)
+	if len(rest) != 3 {
+		return errors.New(secretUsage)
+	}
+	node, module, name := rest[0], rest[1], rest[2]
+	open, err := openStores(ctx)
+	if err != nil {
+		return err
+	}
+	defer open.Close()
+	if err := open.inventory.RotateModuleSecret(ctx, node, module, name); err != nil {
+		var refused inventory.ErrNotRotatable
+		if errors.As(err, &refused) {
+			return fmt.Errorf("not rotated: %s", refused.Why)
+		}
+		return err
+	}
+	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())
+	fmt.Printf("sending %s, so %s starts again on the new value:\n", node, module)
+	if err := sendTo(ctx, open, []string{node}); err != nil {
+		return fmt.Errorf("%w\n\nThe new value is sealed and not yet delivered; what runs keeps the old "+
+			"one until the machine next applies. Fix the cause and run `push %s`", err, node)
+	}
+	return nil
+}
+
+// whoAsked names the caller for the log: the account the command runs as, which for a tool call
+// through the console is the mesh's own.
+func whoAsked() string {
+	if u := os.Getenv("SUDO_USER"); u != "" {
+		return u
+	}
+	if u := os.Getenv("USER"); u != "" {
+		return u
+	}
+	return "the mesh"
+}