feat(secrets): cluster secrets page on the hdb_secret store

[dawsontoth]

Draft — stacked on #1409 (the application-editor .env panel, which is independently deployable). This PR is the in-progress half: the cluster-level Secrets page, consuming backend work that hasn't landed yet — core's hdb_secret store (harper#1554), the Pro key-custody layer (harper-pro#512, tracking issue harper-pro#166), and central-manager's custody keypair endpoints (central-manager#409). Review the top commits only; the base commit belongs to #1409.

What

Config → Secrets manages the replicated system.hdb_secret store: named, envelope-encrypted rows on the cluster itself, edited through the per-instance operations API and scoped to applications via grants. Built on the shared SecretsManager / SecretModals components from #1409.

• integrations/api/instance/secrets/secrets.ts — hooks for list_secrets / set_secret / delete_secret / grant_secret / revoke_secret, plus public-key resolution:
  • Managed clusters fetch the public key from central-manager (POST /ClusterSecrets, per central-manager#409) — CM is the custodian there, and Studio's key fetch is what triggers the first-use mint. Requires cluster-update rights on first use (the mint stamps fingerprints onto instances).
  • Self-hosted / local instances use the node's get_secrets_public_key operation (file-tier custody mints its own key).
  • Both shapes (camelCase vs snake_case) normalize to one interface.
• Client-side encryption (lib/crypto/envSecret.ts, the enc:v1 codec harper#1554 ported into core): values are encrypted in the browser and submitted as envelopes to the cluster's own set_secret — plaintext never reaches the operations API, the operation log, disk, or CM, and can never be read back.
• Rotation/race-aware: the public key is cached for minutes (not forever); a kid-mismatch rejection drops the cached key, re-encrypts against the freshly served key, and retries once. This is also the documented heal for CM's transient first-mint race (two CM workers minting concurrently — the loser's envelopes kid-mismatch, re-encrypting fixes them).
• Grants editor in the edit dialog: only granted applications receive a secret in their environment at load time (grant/revoke apply immediately). Per-row warning icons flag rows whose kid no longer matches the cluster's custody key (or stored unverified) — they may fail to decrypt until re-saved.
• Custody-aware degradation: without a secrets key (no custody registered, CM unreachable, or pre-[Enhancement] Added syntax highlighting for .mjs files #409 CM) the list stays browsable, a banner explains why, and add/edit is disabled.
• Gating: nav entry is version-gated only (>= 5.2.0, matching harper#1554's upgrade directive tag) — the store ships in core, so it isn't restricted to Fabric-managed clusters.

Verification

• tsc, oxlint, dprint clean; full suite green (1089 tests; 6 secrets-hook tests run real WebCrypto RSA keys, asserting plaintext never appears in a request body, the CM-vs-node key routing, and the rotation retry re-encrypting under the newly served key).
• Click-tested live on stage (Harper 5.1.14, CM without [Enhancement] Added syntax highlighting for .mjs files #409): the version gate correctly hides the nav entry, and direct navigation shows the degraded state (banner, read-only, empty list) with the key fetch correctly routed to CM's /ClusterSecrets for the managed cluster.
• The full write path (set/grant/delete) needs a Harper build with #1554 and a CM with [Enhancement] Added syntax highlighting for .mjs files #409 — covered by the hook tests until then.

Notes / open items

• The >= 5.2.0 gate matches harper#1554's upgrade directive tag; retag if that ships in a different release.
• /ClusterSecrets isn't in the generated OpenAPI SDK yet; regenerate to type it once central-manager#409 ships.
• Grant names are free text (grants may precede a deploy, matching the backend's stance); a picker fed by get_components would be a nice follow-up.
• History: the first cut posted to the central-manager ClusterSecrets store from central-manager#405 (control-plane values + host-manager value injection). That model was superseded by the two-key custody plan (harper-pro#166 / central-manager#409: CM keeps the key, the cluster keeps the ciphertext), and this page was retargeted accordingly.

🤖 Generated with Claude Code

---

Related PRs — secrets management

One enc:v1: client contract everywhere (public key + envelope; values encrypted before they leave the client):

• Core (Apache):
  • feat(components): protect .env files in the operations API harper#1527 — .env protection in the operations API — merged (consumed by feat(secrets): version-adaptive .env editor in the application editor #1409)
  • feat(env): dormant decrypt hook + enc:v1 contract for env-secret encryption harper#1528 — dormant enc:v1: decrypt hook + envelope contract — merged
  • feat: hdb_secret store with grant-scoped secret operations harper#1554 — hdb_secret store with grant-scoped secret operations + get_secrets_public_key
  • Add worker-spawn workerData providers and deferred env-secret decrypt replay harper#1559 — workerData providers + deferred decrypt replay
• Pro key custody (tracked by Secrets / env-var management for Fabric-deployed applications harper-pro#166):
  • Key-custody seam: file + injected secret-key providers (closes #166) harper-pro#512 — KeyCustody seam: file (self-hosted) + injected (Fabric) providers; supersedes harper-pro#505
• Fabric control plane:
  • HarperFast/central-manager#409 — per-cluster custody keypair: eager keygen, pull delivery, public-key endpoints; supersedes the CM half of central-manager#405
  • HarperFast/host-manager#130 — key delivery into containers; supersedes host-manager#128
• UI (this stack):
  • feat(secrets): version-adaptive .env editor in the application editor #1409 — application-editor .env panel (deployable now)
  • feat(secrets): cluster secrets page on the hdb_secret store #1402 — this PR: cluster Secrets page (stacked on feat(secrets): version-adaptive .env editor in the application editor #1409)

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[dawsontoth]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces client-side envelope encryption (enc:v1) using the Web Crypto API to securely manage cluster-level deployment secrets, including UI components for listing, adding, and editing secrets. Feedback focuses on utilizing the query cache for the public key, adding a deletion confirmation prompt, handling non-secure contexts where the Web Crypto API is unavailable, ensuring type safety when closing the edit modal, and optimizing ArrayBuffer slicing to avoid unnecessary memory allocations.