57/V1: mesh-vault in Go, holding secrets sealed and answering get sealed to the asker (issue 674) #286
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: novox/mesh-catalog#286
Reference in New Issue
Block a user
What changed
modules/mesh-vaultis rewritten in Go (cmd/mesh-vault, one bundle served through the Go SDK, mesh-sdk pinned to the integration branch's head c8b07242a009 forgo/seal). The TypeScript sources are removed.storedirectory (0700, files 0600, class valuable). A file store, not a database: the vault is installed before any other module (ADR 0113 §14) and a database login is itself a secret the vault makes; everything stored is ciphertext anyway. Nostate(no bucket) is declared.${dir:state}/vault-key.json.operator-keyof the export the controller already writes to the vault's root (keeps), i.e. whatoperator key setrecorded. V3 moves it into the vault with the secrets.mesh-vault.get(seat verb;name,public_key): the secret sealed to the asker's SPKI PEM key, only to an asker theAskersrule allows, the asker being the bus user the runtime proved (stdio.CallerOf), never an argument. The running vault allows nobody (NoAsker); tests set a stand-inAllowList. The real rule (a node's provisioner client for what its declaration names; a module under its own account) goes behindAskersin V4/P3.secret-changed:name,by,at,generation— never a value or a sealed copy.PutandMintexist in the code for V2/V3/V5; no verb writes a secret yet, so until V3 the store is empty.The key formats — settled (V4 needs this)
box.OpenAnonymous), sealing key raw X25519 in base64 (mesh-hostinternal/identity/sealing.go). The controller seals declarations and the operator copies in that box.mesh-sdk/go/seal): X25519 + HKDF-SHA256 + AES-256-GCM, keys as SPKI/PKCS #8 PEM.TestANodesSealingKeyOpensTheAnswer). For the core's credentials carried in the declaration (ADR 0349 §16), V4 adds opening the ADR 0206 box with the same key to the node-engine.secret recover --from-exportopens them unchanged.All of this is in the module's README.
What the TypeScript vault offered, kept or dropped
secret_export,secret_holders,secret_verify: kept, same answers (tests).create/removeover the contributions file): kept as a pass every minute, same JSON files read as they are, sameprovisioned/rotated/deprovisionedevents by fingerprint.index.tsconsumed its own three events only to print an audit line; the pass prints that line itself, so the manifest'sconsumesis gone.capabilities: container-runtimeis dropped: the Go bundle runs no container.Depends on
mesh-controller#317 must merge first: the
mesh-vaultseat must promisegetbefore this claim names it (with the integration branch's controller: "mesh-vault claims mesh-vault and says it serves get, which that seat's protocol does not promise"; with #317's controller:mesh-vault: ok).How it is proven
cmd/mesh-vault/vault_test.go— ADR 0349's vault list as far as V1 goes (all failed before: the package did not exist):TestNoBucketHoldsASecret(manifest declares no state, code opens no bucket, nothing published carries a value or a sealed copy),TestEverySecretIsEncryptedAtRestTestNoPrivateKeyIsAcceptedTestEverySecretHasAnOperatorSealedCopy,TestNoOperatorKeyKeepsNothingTestGetAnswersOnlyAnAllowedAskerSealedToItsKey,TestTheRunningVaultAnswersNobodyYet,TestANodesSealingKeyOpensTheAnswer,TestTheGetVerbTakesItsCallerFromTheRuntimeTestSecretChangedCarriesNoValue,TestTheSameValueAgainIsNoChange,TestASecretsNameIsNotAPath,TestTheVaultsOwnKeyIsMadeOnceledger_test.goports the five TypeScript ledger tests, plusTestALedgerTheTypeScriptVaultWroteIsReadandTestTheCustodyPass;tools_test.gocovers the three tools andTestTheManifestNamesWhatTheBundleServes.Left for later packages
V2:
secret accept,secret-ask,issued,rotateas the vault's verbs. V3: the controller's secrets and operator key copied in. V4/P3: who may ask (Askers), the node-engine opening the ADR 0206 box, removingOptionalfrom the seat'sget. V5: pair credentials minted here.Reviewer's checklist
getsealed to the asker,secret-changedwithout value, no secret in a bucket, no private key; the TS tools kept. ✓serves: ["get"]is accepted by the controller only with mesh-controller#317, which merges first;tools,storeand the Go build artifact are fields the controller already reads (module check: ok). ✓gofmt -lempty,go vet ./...clean,go test -race ./...passes;sh merge-check.shexit 0 withMESH_GATE= a controller built from mesh-controller#317,MESH_CHECK_BASE=feat/57-config-and-provisioning,MESH_CHECK_CHANGED=modules/mesh-vault/module.json(words, agent home, secrets, paths, module check "66, as kept", mesh-vault tests). ✓Delivery
novox/mesh-catalog@c0d55ee27dae— delivered since 2026-10-14T18:28:00ZDelivery plan — builds nothing: the change touches no module of the mesh's graph
Group
pkg/57-v1-vault-in-go, in order: novox/mesh-catalog@c0d55ee27d → novox/mesh-controller@661918f4e4Transitions
b807b1d211(it was rejected against trunk8aa37e8b83)The commit's note under
refs/notes/mesh-plankeeps every transition:git log --notes=mesh-plan.Merge check at
84d8198fJudged: head
84d8198f1540merged into trunk8aa37e8b835d; read beside it: mesh-controllerdf9e5728a925, mesh-controller-maindf9e5728a925, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791939556296183644(builds --log build-1791939556296183644).Verdict: CHANGES at
84d8198f15Independent review of issue 674 (package V1, the vault in Go), reviewed as security code against ADR 0349 clauses 7 to 11, ADR 0113 §1, §2 and §22, and ADR 0201 §13.
What I ran on
84d8198f15, in modules/mesh-vault:gofmt -l(empty),go vet ./...(clean),go test -race ./...(pass). I also ransh merge-check.shwith MESH_GATE set to a controller built from mesh-controller#317's head, MESH_CHECK_BASE set to the integration branch and MESH_CHECK_CHANGED set to the files this pull request changes. It exited 0: the words, agent-home, secrets and paths checks passed, the health count stayed at "66, as kept", and the mesh-vault tests ran. The integration branch's controller refuses the manifest (serves get, which that seat's protocol does not promise), so #317 must merge first.What the forge shows: mesh/merge-gate is a success ("the change touches no module of the mesh's graph"). mesh/repo-check is a failure: it was judged with the controller the mesh runs, which does not promise
getyet. mesh/delivery and mesh/delivery-group are rejected. Ask for a recheck once #317 is delivered.What holds:
secret-changedcarries name, by, at and generation only.PUBLIC KEYcannot carry a private key, and anything containing "PRIVATE KEY" is refused...segment, and names are path-escaped.secrets.Open(cmd/mesh-controller/secret.go:260) opens.Must change:
givenlist (or"given": null), or one written for anotherrequirement, reads as "nobody is asked for". The next Pass then withdraws every holder. The SDK harness the TypeScript vault ran on (mesh-sdk src/provisioner/index.ts, readContributions) treats such a file as unusable and withdraws nothing. TestTheCustodyPass'swrite()with no arguments writes"given": nulland expects the withdrawal, so the test pins the wrong behaviour. Refuse a missing or nullgivenand a mismatchedrequirement, the same way an unreadable file is refused.deprovisionedis said. The TypeScript vault never deleted a ledger entry. Under ADR 0230 the harness retires only after 5 passes and 10 minutes, bounded by a person, and callsremoveonly on a person's provisioner_delete, which the vault never registered. This change alters a running module's custody record (data class valuable) on a single transient file. Keep the entry and mark it retired, or port ADR 0230's stability window and bound, and add a test for both.Should change. These may follow, but must land before V3 puts a secret in the store:
4. cmd/mesh-vault/keys.go:44. OwnKey makes a new key whenever vault-key.json is missing, even when store/secrets holds records. After a partial restore, every at-rest copy then fails to open, and
getfails one name at a time. Refuse loudly (Broken) when the store is not empty.5. cmd/mesh-vault/store.go:164 and keys.go:52. Neither the temporary file nor the directory is synced before the rename or link. After a power loss, vault-key.json can be empty, the vault is broken, and its key is lost. Call fsync on the file, then on the directory.
6. Encryption at rest. The vault's private key lies in plaintext in ${dir:state}, and that directory is backed up together with ${dir:store} (both are data.own valuable). The at-rest seal therefore only protects a copy of the store taken without the state directory. That is acceptable, but the README should say the real protection is the 0700/0600 modes and how backups are handled.
7. keys.go:96, README.md:29 and the pull request body claim the vault "refuses a private key as the operator key". It does not: a raw 32-byte base64 private key, the exact format
operator key makewrites its private half in (mesh-controller internal/secrets/seal.go Keypair), passes checkOperatorKey. Check that the export'sfingerprint(secrets.Fingerprint of the public key) matches, or drop the claim.8. README.md:49 says the operator's recovery opens the copies "with the key and the command it already has". The box is right, but the command cannot find them.
secret recoverlooks a copy up only by node, module and name, in the controller's inventory or in asecret exportfile (keptFromExport, secret.go:368). A vault store record is keyed by name and lives under ${dir:store}, so neither source reaches it, and secret_export lists only the controller's export. Those copies also sit only on the vault's own disk. Before V3: export the vault's operator copies in the KeptExport shape (or giverecovera way to read a vault record), and reword the README.9. cmd/mesh-vault/vault.go:174. Who was handed which secret is written only to stderr. That is acceptable in V1, since nobody is allowed. Before V4 allows an asker, record each hand-out in the vault's store: the caller as the bus named it, the name, the generation and the time, as ADR 0349 §9 carries ADR 0277 §25's record of every ask.
Merge check at
2000c025Judged: head
2000c02559d8merged into trunk8aa37e8b835d; read beside it: mesh-controllerdf9e5728a925, mesh-controller-maindf9e5728a925, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791940749414857221(builds --log build-1791940749414857221).Merge check at
b67fe1ffJudged: head
b67fe1ffb16emerged into trunk8aa37e8b835d; read beside it: mesh-controllerdf9e5728a925, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791940780995293143(builds --log build-1791940780995293143).Merge check at
da889d42Judged: head
da889d421d71merged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791940869157411801(builds --log build-1791940869157411801).Merge check at
39c38f37Judged: head
39c38f37459amerged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791940909788082682(builds --log build-1791940909788082682).Merge check at
c63f7d6eJudged: head
c63f7d6e5ceamerged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on shanks as
build-1791940979807621881(builds --log build-1791940979807621881).Verdict: CHANGES at
c63f7d6e5cSecond independent review of issue 674 (package V1, the vault in Go), against review 250's nine findings, ADR 0230 (retirement of a consumer the mesh stops asking for) and ADR 0349, and the whole vault re-read as security code.
What I ran on
c63f7d6e5c, in modules/mesh-vault:gofmt -l(empty),go vet ./...(clean),go test -race -count=1 ./...(pass).sh merge-check.shwith MESH_GATE set to a controller built from mesh-controller's feat/57-config-and-provisioning at dc36536 (#317 merged), MESH_CHECK_BASE=feat/57-config-and-provisioning and MESH_CHECK_CHANGED set to the files this pull request changes: exit 0 (words, agent home, secrets, paths, "66, as kept", mesh-vault tests).What the forge shows at
c63f7d6: mesh/merge-gate success ("touches no module of the mesh's graph"); mesh/repo-check failure. Its description quotes the last line of the log, but the refusal behind it, in every merge-check comment up to39c38f3, is the running controller's "mesh-vault claims mesh-vault and says it serves get, which that seat's protocol does not promise". That is expected until a controller with #317 runs. mesh/delivery is rejected as a result.I reverted each fix locally and ran the tests:
given, and accepting anotherrequirement, each fail TestAFileThatSaysNothingRetiresNobody. Right and tested.Must change:
provisioner.retirementevent has noprovider-node, and itsconsumersis a list of strings. The controller's link.ReadRetirement (internal/link/retirement.go) decodesconsumersinto []RetiredConsumer objects and refuses a word that names no machine. It logs "ignored", so no urgent condition is raised forwaiting(§18, §38).provisioner_retirementanswersactiveandwaiting.consumersas strings. The controller's RetirementState wantsheld,bound,retires_by("mark-only"),resourceandnode, with consumers as objects. Todayretire approve,retire rejectandcleanup listtherefore fail to read the vault.provisioner_retire_approveandprovisioner_retire_rejectignore theconsumersthe controller sends, so they cannot "refuse any other set" (§20).provisioner_deleteignoresconfirm,byandvia. It recordsbyas the bus caller, and the controller's AskModuleToolOn names none, sobyreads "unproven".Speak the SDK harness's shapes (mesh-sdk src/provisioner/index.ts:547) and test them by decoding into the controller's types.
getappends a line, and with NoAsker every call is refused. Thenameis the caller's raw argument, written before validName (any length, any text). Nothing rotates the file, caps it or reports its size, and Handed reads the whole file into memory. Validate the name before recording it. Then bound the file (for example, roll it at a size and keep N files) or say its size where a person sees it, and test it. It holds no secret value: I checked the code and the test.Should change. These can follow:
3. ledger_test.go:215 and 272. Changing the five passes to one survives, because the ten minutes cover it. The test uses 4 of 5, so removing either the "more than three" bound or the "more than half" bound survives. Add a case for each: 4 of 10, and 2 of 3.
4. ledger.go:478-500. Removing either Delete refusal (not retired, still asked for) survives, because each covers the other in the test.
c.readis set and never read. A Delete before the first pass has read the file findsaskedempty. Refuse until a pass has read it.5. vault_test.go:541-575. The retry runs through Reseal. In production, while the export holds a key, the minute calls SetOperatorKey with that key, and putting back
if current == raw { return }survives. Retry through SetOperatorKey with the same key, or through adoptOperatorKey.6. vault.go:185-187. Refusing to hand out a secret when its record cannot be written is right, but no test pins it. Add a failing RecordHanding to a test.
7. vault.go:257-262 and main.go:348. A copy that keeps failing to re-seal, and an export key that is refused, are said only on stderr each minute. Before V3 they should reach a condition (a health check).
8. README.md:129-131 says the TypeScript vault "withdrew a holder on the first pass that missed it". It ran on the SDK harness, which retired by ADR 0230 and never deleted. Reword it.
9. tools.go:214.
fingerprintis empty. Fill it in as secrets.Fingerprint does, so the export reads like the controller's.Merge check at
6ab38066Judged: head
6ab38066c910merged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791941791498355602(builds --log build-1791941791498355602).Merge check at
b71e6969Judged: head
b71e696993b3merged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791941859281065504(builds --log build-1791941859281065504).Merge check at
958018e6Judged: head
958018e696e4merged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791941924368935273(builds --log build-1791941924368935273).Merge check at
8c5d70a1Judged: head
8c5d70a18677merged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on ace as
build-1791941986919097684(builds --log build-1791941986919097684).Merge check at
dadf824cJudged: head
dadf824c3e33merged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on novox as
build-1791942018513461671(builds --log build-1791942018513461671).Merge check at
c0d55ee2Judged: head
c0d55ee27daemerged into trunk8aa37e8b835d; read beside it: mesh-controller2959c8143536, mesh-controller-main2959c8143536, mesh-host1a2677882380, mesh-tools954e1a53eef9mesh/merge-gate: PASS — the change touches no module of the mesh's graphmesh/repo-check: FAIL — its merge-check.sh failed: files asking for a setting without saying whether it is trusted: 25Run by the build seat on novox as
build-1791942086204066659(builds --log build-1791942086204066659).Verdict: APPROVE at
c0d55ee27dThird independent review of issue 674 (package V1, the vault in Go), against review 255's findings and ADR 0230 (retirement of a consumer the mesh stops asking for).
What I ran on
c0d55ee27d, in modules/mesh-vault:gofmt -l(empty),go vet ./...(clean),go test -race -count=1 ./...(pass).sh merge-check.shwith MESH_GATE built from mesh-controller's feat/57-config-and-provisioning at dc36536 (#317 merged), MESH_CHECK_BASE=feat/57-config-and-provisioning and MESH_CHECK_CHANGED set to the files this pull request changes: exit 0.Must-fix 1 (ADR 0230 words): done.
Must-fix 2 (handed.jsonl): done. Rolled at 1 MiB, 3 kept, a loud log on a roll, the caller's shape and the name checked before any refusal is recorded.
Mutations (each reverted, tests run): killed by a test are no roll, rolled not counted, Handed reading only the current file, name or caller unchecked before recording, one pass, no ten minutes, each bound, each of the six delete refusals, approve/reject with any set, no provider-node, no retires_by, the SetOperatorKey early return (should-fix 5), a hand-out without its record (should-fix 6), and re-enable dropped. Should-fixes 3, 4, 5, 6 and 8 are done and tested.
The deferred item (a failing re-seal raises no controller condition) is acceptable for V1. Until V3 the store is empty, so there is nothing to re-seal. vault_status shows it, and the note is on issue 676, the package that first puts secrets in.
Should change. These can follow, in V2 at the latest:
by,via,confirmorconsumersin the tool layer survives every test: only Custody is tested. Add one test that calls the four retirement tools with the controller's arguments.ok) have no test; an empty fingerprint survives.byis taken from the arguments as given, unproven. When it differs from the caller the runtime proved, record both.Note for the merge: mesh/repo-check is red at this head. Its log shows the running controller's "mesh-vault claims mesh-vault and says it serves get, which that seat's protocol does not promise", which is gone with #317 (my run above). Merge only after a recheck is green.