docs(security): secrets store, secrets operations, and deploy_component registryAuth by kriszyp · Pull Request #581 · HarperFast/documentation

kriszyp · 2026-07-13T17:24:59Z

Summary

Adds v5 reference documentation for the encrypted secrets store and the deploy_component private-registry auth path. None of this was previously documented in v5 — the only secret-adjacent page was environment-variables/overview.md, which covers loadEnv/.env only.

Covers the feature shipped across harper#1550/#1554/#1582 (the store, operations, and component consumption) and harper#1717 — feat: registry-auth via the hdb_secret store (private-registry credentials on deploy_component).

What's included

reference/security/secrets.md (new — the hub): the hdb_secret store model; custody as a Harper Pro capability vs. what OSS core can do (store/replicate client-encrypted envelopes, but not decrypt); the two mutually-exclusive delivery tiers (global → process.env, scoped → grants + the secrets accessor); the config.yamlenv: declaration block (declarations are requests, not grants); the import { secrets } from 'harper' accessor and recommended top-level-destructure idiom; the full client-side enc:v1: envelope format with a Node reference client; and the threat model. Added to the Security sidebar.
reference/operations-api/operations.md: a new ## Secrets section documenting all six operations (set_secret, grant_secret, revoke_secret, list_secrets, delete_secret, get_secrets_public_key) with request/response shapes, plus a registryAuth subsection under deploy_component.
reference/components/javascript-environment.md: adds secrets to the Harper API globals list.
reference/environment-variables/overview.md: cross-links to the secrets store as the production alternative to a committed .env.

Verification

All cross-links and heading anchors resolve.
Content checked against the source: config.env wiring (componentLoader.ts), custody OSS/Pro split (secretDecryptor.ts — "Core ships no custody"), and the envelope format (ported from harper's own docs/env-secret-encryption.md).
⚠️ A full docusaurus build was not run in my environment (the @signalwire/docusaurus-plugin-llms-txt dependency wasn't installed locally). Please confirm a clean build in CI / a deps-installed checkout before merging.

Reviewer notes

Custody is framed as a Harper Pro capability rather than naming the specific component — confirm that's the right public positioning.
Design rationale (custody key model / decision records) is intentionally kept out of public docs.

🤖 Generated with Claude Code

…mponent registryAuth Adds v5 reference documentation for the encrypted secrets store (#1550/#1554/ #1582) and the deploy_component private-registry auth path (#1717), none of which was previously documented. - reference/security/secrets.md (new): store model, custody (Pro) vs OSS core, the two delivery tiers (process.env global vs scoped grants), the config.yaml `env:` declaration block, the `import { secrets } from 'harper'` accessor, full client-side `enc:v1:` envelope format + Node reference client, and the threat model. Added to the Security sidebar. - reference/operations-api/operations.md: new Secrets section (set_secret, grant_secret, revoke_secret, list_secrets, delete_secret, get_secrets_public_key) plus a registryAuth subsection under deploy_component. - reference/components/javascript-environment.md: add `secrets` to the Harper API globals list. - reference/environment-variables/overview.md: cross-link to the secrets store as the production alternative to a committed .env. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gemini-code-assist

Code Review

This pull request introduces comprehensive documentation for Harper's new encrypted and replicated secrets store, detailing its concepts, delivery tiers, management operations, and client-side encryption. The review feedback focuses on improving the documentation's clarity and professionalism, specifically by clarifying security risks in configuration files, refining grammar, replacing colloquial phrasing, and adding a response example for the list_secrets operation.

gemini-code-assist · 2026-07-13T17:27:22Z

+The `secrets` object is frozen and enumerable (`Object.keys(secrets)`, spread). Global-tier secrets are read from `process.env` as usual and do not need the accessor.
+
+:::note
+Under the VM/compartment component loaders the `harper` module is per-scope, so `import { secrets } from 'harper'` binds to the loading component exactly. Under the native loader the `harper` package is a process-wide singleton, so `secrets` binds to the current component via the component-load context; accessing it **outside** a component-load context fails loudly rather than guessing which component is asking. The module-top-level destructure above is exact in all modes.


Add commas after introductory adverbial phrases to improve the readability of the explanation.
Suggested change:
Under the VM/compartment component loaders, the harper module is per-scope, so import { secrets } from 'harper' binds to the loading component exactly. Under the native loader, the harper package is a process-wide singleton, so secrets binds to the current component via the component-load context; accessing it outside a component-load context fails loudly rather than guessing which component is asking. The module-top-level destructure above is exact in all modes.
Suggested change
Under the VM/compartment component loaders the `harper` module is per-scope, so `import { secrets } from 'harper'` binds to the loading component exactly. Under the native loader the `harper` package is a process-wide singleton, so `secrets` binds to the current component via the component-load context; accessing it **outside** a component-load context fails loudly rather than guessing which component is asking. The module-top-level destructure above is exact in all modes.
Under the VM/compartment component loaders, the harper module is per-scope, so import { secrets } from 'harper' binds to the loading component exactly. Under the native loader, the harper package is a process-wide singleton, so secrets binds to the current component via the component-load context; accessing it outside a component-load context fails loudly rather than guessing which component is asking. The module-top-level destructure above is exact in all modes.

gemini-code-assist · 2026-07-13T17:27:22Z

+
+### Healing after changes
+
+Materialization happens once per load cycle — there is no live re-materialization. A secret that was granted late, rotated, or whose custody came up after boot heals on the next **restart or component reload**, when the store is re-read.


The word "heals" is a bit colloquial for technical documentation. Using "is resolved" or "becomes available" is more professional and clear.
Suggested change
Materialization happens once per load cycle — there is no live re-materialization. A secret that was granted late, rotated, or whose custody came up after boot heals on the next **restart or component reload**, when the store is re-read.
Materialization happens once per load cycle — there is no live re-materialization. A secret that was granted late, rotated, or whose custody came up after boot is resolved on the next **restart or component reload**, when the store is re-read.

github-actions · 2026-07-13T17:28:08Z