feat(security): prototype — trusted secrets store + config-declared scope.secrets

[dawsontoth]

Prototype for discussion, stacked on #505. Secrets for components where authority lives in a trusted store Harper controls — never in a component's own config — hardening the private key and env vars against a compromised plugin / SSR JS-RCE.

What changed since the first cut (and why)

The first version used a component's own config.yaml secrets: block as the allow-list. That's not a control: the component (and whoever deploys its config) controls that file, so it authorizes itself. Authority moved to a store the component can't write.

I also grounded this in how Harper actually isolates code (core: server/threads/manageThreads.js, security/jsLoader.ts):

• One process, worker threads; components run in node:vm contexts hardened by SES / frozen intrinsics — not isolated-vm, not separate processes. So a separate broker process buys ~nothing against a JS-level compromise; keeping the key in host scope is what isolates it. (Broker dropped; KMS kept only as an optional off-box tier.)
• process is reachable in the sandbox and loadEnv writes decrypted values to process.env, so that path is ambient. scope.secrets never populates process.env.

The authority: system.hdb_secret (trusted, replicated)

A table in Harper's system database — the same replicated store behind hdb_user/hdb_role, so grants + encrypted values are consistent cluster-wide and survive an instance being down. Super_user-writable only.

field	meaning
name (PK)	cluster-wide secret name
value	enc:v1: ciphertext (decryptable only by the host-scope key)
grants	components authorized to read it — the authority
metadata	description, updatedBy, updatedAt

Operator ops (ciphertext + metadata only; plaintext never passes through the server): set_secret, grant_secret, revoke_secret, list_secrets.

Identity: asserted by Harper, not the component

Grants key off the component name the loader stamps (new ApplicationScope(basename(componentDirectory), …)), so a component can't claim another's identity. Caveat, stated honestly: trust in the name is only as strong as who can deploy under it — operator-controlled in managed/Fabric, a deploy-time assumption on self-hosted.

Resolution

scope.secrets.get('X') from component C → look up X → allow only if C ∈ X.grants (else throw, pointing at grant_secret) → decrypt X.value on the trusted side via KeyCustody → return plaintext. Never process.env; key never enters the sandbox; C can't read another component's secret.

The manifest: non-authoritative

A component may still declare needs in config.yaml — but only as a request:

secrets:
  DATABASE_URL: { required: true, description: Postgres DSN }
  DEBUG_WEBHOOK_URL: { required: false }
# or shorthand:  secrets: [DATABASE_URL, STRIPE_API_KEY]

Used only for ensureRequired() fail-fast (distinguishing not granted from granted but unset) and operator UX. It can never widen access beyond the store's grants — there's a test for exactly that.

Changes

• security/secretsStore.ts (new) — SecretsStore + InMemorySecretsStore (tested), isGranted, operator ops, and a TableSecretsStore sketch binding to system.hdb_secret.
• security/secretsAccessor.ts — authority from the store keyed by the Harper-asserted componentName; has/list reflect grants; ensureRequired distinguishes not-granted vs granted-unset; manifest advisory only.
• security/envSecrets.ts — createScopeSecrets(componentName, store, {manifest}).
• security/secretsConfig.ts — re-documented as a non-authoritative manifest.
• security/keyCustody.ts — host-scope framing; broker removed; KMS demoted to optional off-box tier.
• docs/component-secrets.md — full design.
• Tests — 36 passing, incl. "a component cannot widen access via its own manifest".

Threat model, honestly

• Defends: compromised plugin / SSR JS-RCE reading un-granted secrets, scraping process.env, or self-granting via config. No extra process needed.
• Does not (by itself): host-root / native RCE reading raw memory (→ KMS/HSM or cluster threshold key-shares, optional tiers behind the same interface); a hostile deploy assuming a granted component's name (→ deploy-time trust).

Not wired into core yet (deliberately)

• Declare system.hdb_secret in core (super_user-writable, replicated); bind TableSecretsStore.
• Register set_secret/grant_secret/revoke_secret/list_secrets (handlers delegate to the store fns).
• core loader: build the accessor with the loader-asserted componentName + shared store, bind to per-component scope.secrets (+ harper secrets export), pass the manifest, call ensureRequired() at load.

Related

• Base: feat(security): Pro env-secrets component for .env encryption #505 (Pro env-secrets component)
• Core contract: feat(env): dormant decrypt hook + enc:v1 contract for env-secret encryption harper#1528 (enc:v1 + dormant decrypt hook)

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

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

[claude]

Reviewed; no blockers found.

[claude]

Suggestion (non-blocking): Cache the KMSClient instance rather than constructing one per call. unwrapKey is called on every scope.secrets.get(), so each resolution currently opens a fresh TCP+TLS connection to KMS. Cache as a field:

Suggested change

	async #kms(): Promise<any> {
	const pkg = '@aws-sdk/client-kms';
	const { KMSClient } = await import(pkg);
	return new KMSClient({ region: this.#region });
	}
	#client?: any;
	async #kms(): Promise<any> {
	if (this.#client) return this.#client;
	const pkg = '@aws-sdk/client-kms';
	const { KMSClient } = await import(pkg);
	this.#client = new KMSClient({ region: this.#region });
	return this.#client;
	}