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.

internal/catalogue/declaration.go

@@ -465,7 +465,7 @@ func (r Resolution) compose(with Rendering, owner map[string]string) ([]map[stri
 					"%s needs a secret called %q and none was made for it", m.Module, name)
 			}
 			first = append(first, ownedBy(m.SecretsOwner, map[string]any{
-				"id": NeedID(name), "type": "file", "path": m.OwnSecrets[name], "sealed": sealed,
+				"id": NeedID(name), "type": "file", "path": m.OwnSecrets[name].Path, "sealed": sealed,
 			}))
 		}
 		// Operator-owned paths this module is granted use of (novox/hq ADR 0051). Written before

internal/catalogue/dir_into.go

@@ -161,8 +161,16 @@ func placedManifest(m Manifest, with Rendering) (Manifest, error) {
 	if m.Secrets, err = fillMap(m.Secrets); err != nil {
 		return m, err
 	}
-	if m.OwnSecrets, err = fillMap(m.OwnSecrets); err != nil {
-		return m, err
+	if len(m.OwnSecrets) > 0 {
+		own := make(OwnSecrets, len(m.OwnSecrets))
+		for name, s := range m.OwnSecrets {
+			filled, err := dirFill(s.Path, dirs, m.Module)
+			if err != nil {
+				return m, err
+			}
+			own[name] = OwnSecret{Path: filled, Taken: s.Taken}
+		}
+		m.OwnSecrets = own
 	}
 	if m.Grants, err = fillMap(m.Grants); err != nil {
 		return m, err
@@ -335,7 +343,7 @@ func (m Manifest) unknownDirRefs() []string {
 	}
 	maps := map[string]map[string]string{
 		"receives": m.Receives, "binds": m.Binds, "secrets": m.Secrets,
-		"own-secrets": m.OwnSecrets, "grants": m.Grants,
+		"own-secrets": m.OwnSecrets.Paths(), "grants": m.Grants,
 	}
 	for field, entries := range maps {
 		for _, value := range entries {

internal/catalogue/dir_into_test.go

@@ -164,7 +164,7 @@ func TestTheManifestsMapsArePlaced(t *testing.T) {
 		},
 		Binds:      map[string]string{"route": "${dir:state}/route.json"},
 		Secrets:    map[string]string{"mongodb-database": "${dir:state}/database.secret"},
-		OwnSecrets: map[string]string{"admin-key": "${dir:state}/admin-key.secret"},
+		OwnSecrets: OwnSecrets{"admin-key": {Path: "${dir:state}/admin-key.secret"}},
 		Receives:   map[string]string{"route": "${dir:state}/grants/mesh.json"},
 	}
 	placed, err := placedManifest(m, Rendering{})
@@ -177,7 +177,7 @@ func TestTheManifestsMapsArePlaced(t *testing.T) {
 	if placed.Secrets["mongodb-database"] != "/var/lib/photos/database.secret" {
 		t.Fatalf("secrets are placed; got %v", placed.Secrets)
 	}
-	if placed.OwnSecrets["admin-key"] != "/var/lib/photos/admin-key.secret" {
+	if placed.OwnSecrets["admin-key"].Path != "/var/lib/photos/admin-key.secret" {
 		t.Fatalf("own-secrets are placed; got %v", placed.OwnSecrets)
 	}
 	if placed.Receives["route"] != "/var/lib/photos/grants/mesh.json" {
@@ -231,7 +231,7 @@ func TestTheMeshsDirectoryForAModuleIsAPlace(t *testing.T) {
 			{"id": "server", "type": "container", "image": "x@sha256:aa",
 				"volumes": []any{"${dir:mesh-state}/broker:/run/secrets/broker:ro"}},
 		},
-		OwnSecrets: map[string]string{"broker": "${dir:mesh-state}/broker"},
+		OwnSecrets: OwnSecrets{"broker": {Path: "${dir:mesh-state}/broker"}},
 		Binds:      map[string]string{"route": "${dir:state}/route.json"},
 	}
 	if got := m.unknownDirRefs(); len(got) != 0 {
@@ -249,7 +249,7 @@ func TestTheMeshsDirectoryForAModuleIsAPlace(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if placed.OwnSecrets["broker"] != "/var/lib/mesh/umami/broker" {
+	if placed.OwnSecrets["broker"].Path != "/var/lib/mesh/umami/broker" {
 		t.Fatalf("own-secrets are placed under the mesh's directory; got %v", placed.OwnSecrets)
 	}
 	container := shallowCopy(m.Resources[2])

internal/catalogue/filtering_test.go

@@ -419,7 +419,7 @@ func TestWhatTheMeshComputesIsAppliedBeforeWhatTheModuleDeclared(t *testing.T) {
 func TestAComputedModuleStillGetsWhatTheMeshMadeForIt(t *testing.T) {
 	r := Resolution{Modules: []Manifest{{
 		Module: "networking", Computed: "mesh-network",
-		OwnSecrets: map[string]string{"key": "/var/lib/mesh/key"},
+		OwnSecrets: OwnSecrets{"key": {Path: "/var/lib/mesh/key"}},
 	}}}
 	out, err := r.Declaration(Rendering{
 		Needed:     map[string]map[string]string{"networking": {"key": "sealed"}},

internal/catalogue/manifest.go

@@ -390,7 +390,16 @@ type Manifest struct {
 	// module running on three machines has three passwords and the mesh can read none of them. A
 	// manifest carrying one instead would put the same secret on every machine that ever runs the
 	// module, in a file anybody can read, for ever.
-	OwnSecrets map[string]string `json:"own-secrets,omitempty"`
+	//
+	// **And how the module takes it** (novox/hq ADR 0114, issue 180): `"admin": "<path>"` says
+	// where and nothing else; `"admin": {"path": "<path>", "taken": "at-start"}` says the module
+	// reads the file when it starts, so the mesh may rotate it by making a new value and starting
+	// the module again; `"taken": "applied"` says the module's own code applies it to a backend
+	// that takes it only once, so a rotation must be staged beside the current value — the form the
+	// mesh does not build yet, and refuses by name. A secret that says neither is not rotated by
+	// the mesh: the one fault worse than an unrotated credential is a rotated one the software
+	// never saw.
+	OwnSecrets OwnSecrets `json:"own-secrets,omitempty"`
 
 	// SecretsOwner is who the files holding this module's secrets belong to on the machine —
 	// `uid:gid`, or a name — when its process is not root.
@@ -1419,14 +1428,20 @@ func ParseManifest(raw []byte) (Manifest, error) {
 			}
 		}
 	}
-	for name, where := range m.OwnSecrets {
-		if !placedOrAbsolute(where) {
+	for name, own := range m.OwnSecrets {
+		if !placedOrAbsolute(own.Path) {
 			problems = append(problems, fmt.Sprintf(
-				"%s needs %q at %q, which is neither an absolute path nor a placed one", m.Module, name, where))
+				"%s needs %q at %q, which is neither an absolute path nor a placed one", m.Module, name, own.Path))
 		}
 		if name == "" {
 			problems = append(problems, m.Module+" needs a secret with no name")
 		}
+		if own.Taken != "" && own.Taken != TakenAtStart && own.Taken != TakenApplied {
+			problems = append(problems, fmt.Sprintf(
+				"%s says its secret %q is taken %q; a secret is taken %q (read when the module starts) "+
+					"or %q (applied by the module's own code to a backend that takes it once)",
+				m.Module, name, own.Taken, TakenAtStart, TakenApplied))
+		}
 	}
 	localOf := map[string]string{}
 	for _, to := range m.SecretRequirements() {
@@ -1690,8 +1705,8 @@ func (m Manifest) undeclaredMounts() []string {
 			claim(fmt.Sprint(r["path"]))
 		}
 	}
-	for _, where := range m.OwnSecrets {
-		claim(where)
+	for _, own := range m.OwnSecrets {
+		claim(own.Path)
 	}
 	for _, to := range m.SecretRequirements() {
 		for _, f := range m.SecretFiles(to) {
@@ -1826,3 +1841,69 @@ func invokeProblems(m Manifest) []string {
 	}
 	return problems
 }
+
+// How a module takes one of its own secrets (ADR 0114): read from the file when it starts, or
+// applied by its own code to a backend that takes it once.
+const (
+	TakenAtStart = "at-start"
+	TakenApplied = "applied"
+)
+
+// OwnSecret is where one of a module's own secrets lands, and how the module takes it.
+type OwnSecret struct {
+	Path  string
+	Taken string
+}
+
+// OwnSecrets is a module's own secrets by name. On the wire each is a path, or an object naming
+// the path and how it is taken; written back the way it was read, so a manifest the mesh holds
+// keeps its bytes.
+type OwnSecrets map[string]OwnSecret
+
+func (o *OwnSecrets) UnmarshalJSON(raw []byte) error {
+	var entries map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &entries); err != nil {
+		return err
+	}
+	out := make(OwnSecrets, len(entries))
+	for name, body := range entries {
+		var path string
+		if err := json.Unmarshal(body, &path); err == nil {
+			out[name] = OwnSecret{Path: path}
+			continue
+		}
+		var long struct {
+			Path  string `json:"path"`
+			Taken string `json:"taken,omitempty"`
+		}
+		dec := json.NewDecoder(bytes.NewReader(body))
+		dec.DisallowUnknownFields()
+		if err := dec.Decode(&long); err != nil {
+			return fmt.Errorf("own-secrets.%s: a path, or {\"path\", \"taken\"}: %w", name, err)
+		}
+		out[name] = OwnSecret{Path: long.Path, Taken: long.Taken}
+	}
+	*o = out
+	return nil
+}
+
+func (o OwnSecrets) MarshalJSON() ([]byte, error) {
+	entries := make(map[string]any, len(o))
+	for name, s := range o {
+		if s.Taken == "" {
+			entries[name] = s.Path
+			continue
+		}
+		entries[name] = map[string]string{"path": s.Path, "taken": s.Taken}
+	}
+	return json.Marshal(entries)
+}
+
+// Paths is each own secret's path by name — the shape every placement and file walk reads.
+func (o OwnSecrets) Paths() map[string]string {
+	out := make(map[string]string, len(o))
+	for name, s := range o {
+		out[name] = s.Path
+	}
+	return out
+}

internal/catalogue/needs_test.go

@@ -14,7 +14,7 @@ import (
 func needy() Manifest {
 	return Manifest{
 		Module: "postgres", Version: "1",
-		OwnSecrets: map[string]string{"superuser": "/var/lib/mesh/postgres/superuser"},
+		OwnSecrets: OwnSecrets{"superuser": {Path: "/var/lib/mesh/postgres/superuser"}},
 		Resources: []map[string]any{
 			{"id": "store", "type": "container", "name": "mesh-postgres", "image": "postgres@sha256:x"},
 		},
@@ -74,7 +74,7 @@ func TestANeedIsAnAbsolutePath(t *testing.T) {
 func TestAModuleMayNeedSeveralThings(t *testing.T) {
 	// A password and a token, say. Telling them apart is the module's business, not the mesh's.
 	m := needy()
-	m.OwnSecrets["replication"] = "/var/lib/mesh/postgres/replication"
+	m.OwnSecrets["replication"] = OwnSecret{Path: "/var/lib/mesh/postgres/replication"}
 	got, _ := Resolve(shelf(m), []string{"postgres"}, reachable(), World{})
 	out, err := got.Declaration(Rendering{Needed: map[string]map[string]string{
 		"postgres": {"superuser": "b25l", "replication": "dHdv"},

internal/catalogue/own_secret_taken_test.go

@@ -0,0 +1,54 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// An own secret says how the module takes it (novox/hq ADR 0114, issue 180): a path alone says
+// nothing of it, an object says `at-start` or `applied`, and the bytes the mesh holds are the bytes
+// it was given either way.
+func TestAnOwnSecretSaysHowItIsTaken(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"idp","version":"1","own-secrets":{
+		"broker":"/var/lib/mesh/idp/broker",
+		"admin":{"path":"/var/lib/idp/admin.secret","taken":"applied"},
+		"session":{"path":"/var/lib/idp/session.secret","taken":"at-start"}}}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m.OwnSecrets["broker"] != (OwnSecret{Path: "/var/lib/mesh/idp/broker"}) {
+		t.Fatalf("a path alone is a path and nothing more: %+v", m.OwnSecrets["broker"])
+	}
+	if m.OwnSecrets["admin"].Taken != TakenApplied || m.OwnSecrets["session"].Taken != TakenAtStart {
+		t.Fatalf("the word was not kept: %+v", m.OwnSecrets)
+	}
+	// Written back the way it was read, so a registered manifest keeps its bytes.
+	out, err := json.Marshal(m.OwnSecrets)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var again OwnSecrets
+	if err := json.Unmarshal(out, &again); err != nil {
+		t.Fatal(err)
+	}
+	if len(again) != 3 || again["admin"].Taken != TakenApplied || again["broker"].Taken != "" {
+		t.Fatalf("the round trip changed the secrets: %s", out)
+	}
+	if !strings.Contains(string(out), `"broker":"/var/lib/mesh/idp/broker"`) {
+		t.Fatalf("a path alone is written back as a path: %s", out)
+	}
+}
+
+func TestAnOwnSecretTakenSomeOtherWayIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"idp","version":"1","own-secrets":{
+		"admin":{"path":"/var/lib/idp/admin.secret","taken":"sometimes"}}}`))
+	if err == nil || !strings.Contains(err.Error(), `taken "sometimes"`) {
+		t.Fatalf("an unknown word for how a secret is taken was accepted: %v", err)
+	}
+	_, err = ParseManifest([]byte(`{"module":"idp","version":"1","own-secrets":{
+		"admin":{"path":"/var/lib/idp/admin.secret","rotate":"yes"}}}`))
+	if err == nil {
+		t.Fatal("an unknown field on an own secret was accepted")
+	}
+}

internal/catalogue/secrets_in_environment_test.go

@@ -15,7 +15,7 @@ func aModuleWithAnEnvFileSecret(exception string) Manifest {
 	}
 	return Manifest{
 		Module: "app", Version: "1",
-		OwnSecrets: map[string]string{"token": "/var/lib/app/token.secret"},
+		OwnSecrets: OwnSecrets{"token": {Path: "/var/lib/app/token.secret"}},
 		Resources: []map[string]any{
 			{"id": "env", "type": "file", "path": "/var/lib/app/server.env", "mode": "0600",
 				"content": "APP_TOKEN=${secret:token}\n"},

internal/catalogue/secrets_into_files_test.go

@@ -25,7 +25,7 @@ func fileNamed(out []map[string]any, id string) map[string]any {
 func TestAFileGetsTheSecretItsContentAsksFor(t *testing.T) {
 	r := Resolution{Node: "anchor", Modules: []Manifest{{
 		Module:     "gitea",
-		OwnSecrets: map[string]string{"admin": "/var/lib/gitea/admin.env"},
+		OwnSecrets: OwnSecrets{"admin": {Path: "/var/lib/gitea/admin.env"}},
 		Resources: []map[string]any{{
 			"id": "conf", "type": "file", "path": "/etc/gitea/app.ini",
 			"content": "[security]\nSECRET_KEY = ${secret:admin}\n",
@@ -130,7 +130,7 @@ func TestTwoConsumersOfOneProvisionEachGetTheirOwnInAPlaceholderFile(t *testing.
 func TestAFileNamingASecretTheModuleDoesNotHaveIsRefused(t *testing.T) {
 	r := Resolution{Node: "anchor", Modules: []Manifest{{
 		Module:     "gitea",
-		OwnSecrets: map[string]string{"admin": "/var/lib/gitea/admin.env"},
+		OwnSecrets: OwnSecrets{"admin": {Path: "/var/lib/gitea/admin.env"}},
 		Resources: []map[string]any{{
 			"id": "conf", "type": "file", "path": "/etc/gitea/app.ini",
 			"content": "SECRET_KEY = ${secret:adnim}\n",
@@ -151,7 +151,7 @@ func TestAFileNamingASecretTheModuleDoesNotHaveIsRefused(t *testing.T) {
 // One module may not read another's credential by guessing its name.
 func TestAFileCannotNameAnotherModulesSecret(t *testing.T) {
 	r := Resolution{Node: "anchor", Modules: []Manifest{
-		{Module: "postgres", OwnSecrets: map[string]string{"superuser": "/var/lib/postgres/su.env"}},
+		{Module: "postgres", OwnSecrets: OwnSecrets{"superuser": {Path: "/var/lib/postgres/su.env"}}},
 		{Module: "gitea", Resources: []map[string]any{{
 			"id": "conf", "type": "file", "path": "/etc/gitea/app.ini",
 			"content": "PASSWORD=${secret:superuser}\n",
@@ -174,7 +174,7 @@ func TestAFileCannotNameAnotherModulesSecret(t *testing.T) {
 func TestASettingThatCarriesAPlaceholderIsStillFilled(t *testing.T) {
 	r := Resolution{Node: "workstation", Modules: []Manifest{{
 		Module:     "chat",
-		OwnSecrets: map[string]string{"api-token": "/home/operator/.config/chat/token"},
+		OwnSecrets: OwnSecrets{"api-token": {Path: "/home/operator/.config/chat/token"}},
 		Resources: []map[string]any{{
 			"id": "settings", "type": "file", "merge": "json",
 			"path": "/home/operator/.config/chat/settings.json", "content": "{}",
@@ -207,7 +207,7 @@ func TestANameMeaningTwoThingsIsRefused(t *testing.T) {
 		Node: "anchor",
 		Modules: []Manifest{{
 			Module:     "thing",
-			OwnSecrets: map[string]string{"store": "/var/lib/thing/own.env"},
+			OwnSecrets: OwnSecrets{"store": {Path: "/var/lib/thing/own.env"}},
 			Secrets:    map[string]string{"store": "/var/lib/thing/granted.env"},
 		}},
 		Needs: []Needed{{Name: "store", From: "anchor", Sealed: "sealed-granted"}},
@@ -225,7 +225,7 @@ func TestANameMeaningTwoThingsIsRefused(t *testing.T) {
 func TestAFileWithNoPlaceholderIsLeftAlone(t *testing.T) {
 	r := Resolution{Node: "anchor", Modules: []Manifest{{
 		Module:     "gitea",
-		OwnSecrets: map[string]string{"admin": "/var/lib/gitea/admin.env"},
+		OwnSecrets: OwnSecrets{"admin": {Path: "/var/lib/gitea/admin.env"}},
 		Resources: []map[string]any{{
 			"id": "conf", "type": "file", "path": "/etc/gitea/app.ini", "content": "RUN_MODE=prod\n",
 		}},

internal/catalogue/verbs.go

@@ -99,6 +99,17 @@ var ControllerVerbs = []Verb{
 		Input: schema(map[string]string{"node": "the machine's name", "module": "the module's name"}, []string{"node", "module"})},
 	{Name: "push", Description: "Send a machine everything it should be — or every machine that is behind, when no machine is named.",
 		Input: schema(map[string]string{"node": "the machine's name; every machine behind when absent"}, nil)},
+	{Name: "rotate", Description: "Replace a credential. A pair credential, by provision (and a consuming machine, " +
+		"else every holder): both ends are re-sent together. Or a module's own secret, by machine, module and " +
+		"name: made anew and the machine sent, so the module starts again on it — only for a secret its " +
+		"definition says it reads at start; a value given to the mesh, or one the module applies to a backend, is refused with the reason.",
+		Input: schema(map[string]string{
+			"provision": "a pair credential: the provision whose credential to replace",
+			"consumer":  "with provision: only the holder on this machine (optional)",
+			"node":      "an own secret: the machine",
+			"module":    "an own secret: the module",
+			"secret":    "an own secret: its name in the module's definition",
+		}, nil)},
 	{Name: "build", Description: "Have the build machine build a repository. Answers at once with the build's id: " +
 		"`builds` with that id follows it line by line, and the module is registered when the outcome comes.",
 		Input: schema(map[string]string{