feat(edgesync): spoke registry with encrypted-at-rest secrets (#569 PRs 6+7/9)

[xe-nvdk]

Combines PRs 6 and 7 of nine for edge sync — see #569. Follows #570, #571, #572, #573, #574, #575.

PR 6 was already merged. Spoke namespacing, the 409-never-overwrite rule, and spoke-ID validation shipped in #574/#575 because the receive and reconcile endpoints could not be correct without them. What remained — the per-spoke secret binding — lives here, so opening a thin PR to re-test merged code would have added process without safety. Reasoning on the issue.

This makes the hub usable

Until now it rejected every request for want of a way to register a spoke.

curl -X POST https://hub/api/v1/sync-spokes/ -H "Authorization: Bearer $TOKEN" \
  -d '{"spoke_id": "rocket-01", "name": "Rocket 07 Telemetry"}'
# → 201 {"secret": "5db508a4…", "warning": "shown once and cannot be retrieved"}

Plus rotate, enable/disable (reversible, keeping history), delete (which deliberately keeps received files), and list.

Two design decisions

§8.1's secret_hash cannot work. HMAC verification recomputes the MAC from the secret, so the hub needs the plaintext at request time — unlike an API token, only ever checked against a presented value. Secrets are AES-256-GCM encrypted under ARC_ENCRYPTION_KEY, the same mechanism MQTT uses for broker passwords. A hub enabled without that key refuses to start. The column is named secret_encrypted so the storage model cannot be misread from the schema.

The hub generates the secret, returned once. Spoke carries no secret field, so metadata paths cannot leak it by construction. Generating rather than accepting one removes the weak/reused-secret failure mode.

Two blockers — both in claims I made and did not properly check

My "verified, not assumed" middleware comment was false. I tested the route nesting with the sync group registered first; main.go registers admin first, and under that order the sync middleware does not run on admin routes. Worse, it flips on reordering two lines — after which a registration whose JSON exceeds the sync body limit gets a 413 from the wrong group before auth runs. Admin routes moved to /api/v1/sync-spokes so isolation is structural rather than order-dependent.

The cipher guard did not guard. mqtt.NewPasswordEncryptor returns a non-nil pass-through for an empty key, which satisfies the interface — so a caller that forgot to check the key would store every secret in plaintext while construction reported success. NewRegistry now round-trips a canary and refuses a cipher that does not encrypt.

Three mutations survived because my tests used one spoke

RecordActivity updating every row, List dropping its ORDER BY, and a scan always reporting enabled are all invisible with a single registration. Multi-spoke tests now catch each; List also gained a stable tiebreaker so bulk provisioning cannot produce arbitrary order.

Other findings fixed

• Spoke names bounded and control-character-free — a 1MB name was accepted, and an embedded newline let a registration forge log lines.
• Decrypt failure now logs at Warn, not Debug — it is a hub misconfiguration affecting every spoke, not the scan noise an unknown ID is.
• Startup verifies the key still decrypts what is stored. A changed ARC_ENCRYPTION_KEY was otherwise invisible: admin endpoints keep answering 200 while nothing authenticates, and on an edge deployment the first failure might be a missed contact window away.
• Count instead of len(List(...)), bounded startup context, distinct logger component, generic 404 message.

The auth question I put to the reviewer

With auth.enabled=false the admin routes are unauthenticated — anyone reaching the port can mint write credentials. Its recommendation, which I took: keep the pattern (consistent across all 16 Arc admin handlers; mqtt.go manages encrypted credentials identically) and make the posture visible. Startup now warns explicitly, and the docs carry a callout.

Configuration matrix

Configuration	Reaches new code?	Preconditions established?
enabled=false (default)	No — nothing constructed	n/a
enabled=true, no ARC_ENCRYPTION_KEY	No — refuses to start	Verified live, no plaintext fallback
enabled=true, key changed since registration	No — refuses to start	Verified live: names the cause; original key starts cleanly
enabled=true + key, auth enabled	Yes	RequireAdmin on admin routes
enabled=true + key, auth disabled	Yes	Admin routes unauthenticated by design; startup warns. Verified live
Zero registered spokes	Yes — sync 401s	Startup names the endpoint to fix it. Verified live
Spoke disabled mid-flight	Yes	Immediate 401. Verified live
Cluster + enabled	Yes — registry is Raft-independent	Not exercised live

Test plan

• Build, vet, gofmt, -race clean
• Mutation-tested: 8 killed, including plaintext storage, disabled-still-authenticates, re-register-reissues, per-spoke activity scoping, ORDER BY removal, and routing the key check through a path that short-circuits on disabled spokes
• Full loop verified live: register → upload signed with the issued secret → reconcile reports present → disable → immediate 401
• Binary runs for every refusing configuration
• Confirmed the moved admin path (old 404s, new works) and the 129-char name rejection

Review

Security pass, deep pass, and a third review. The security pass judged the auth-disabled question; the deep pass caught both blockers. A transient mutation in GenerateSecret during review — which would have made every secret identical — was a reviewer's own probe, not shipped code; I verified independently that generation is intact.

Note

§8.1 of the design doc still specifies secret_hash, which is architecturally impossible here. Documented in code, schema, and on the issue, but the doc itself should be corrected — a separate change from this PR.

🤖 Generated with Claude Code