suaveplan/openspec/archive/2026-05-25-api-secrets-worker-proxy/change/proposal.md

@suaveplan/api-secrets-worker-proxy — worker-side proxy to main-process secrets adapter

Package: @suaveplan/api-secrets-worker-proxy Status: PROPOSED Type: new-package Stage: 3 (Worker isolation infrastructure)

Why

Per design doc §5.2a, every capability ships a proxy surface. Secrets are unusually sensitive: a worker reading a value it didn't manifest is a security incident. So the main-side adapter does the allow-check before the value crosses the wire (design doc §5.2b sandboxed gating), and this proxy is the worker-side transport. The proxy MUST NEVER cache a secret value in the worker heap beyond the immediate caller's scope — that's the proxy's job to enforce by not exposing any internal storage.

What changes

Net-new package.

ADDED exports:

• ./client — createSecretsProxyClient(port): WorkerProxyOf<SecretsLike>. Worker-side ctx.secrets.get(name) → main-side allow-check + read → marshalled value.
• ./error-codes — SECRETS_PROXY_* codes (SECRETS_PROXY_NOT_MANIFESTED, SECRETS_PROXY_NOT_FOUND, SECRETS_PROXY_PORT_CLOSED).
• ./testing — paired MessageChannel + stub main-side server.

Out of scope

• Manifest allowlist enforcement — main-side per §5.2b.
• Concrete secrets source — api-secrets-env / api-secrets-bun / api-secrets-vault are Stages 4 / 8.
• Secret rotation hooks — not in foundation scope.

Source mapping

Genesis-original. Design doc sections: §5.2a, §5.2b.

Requirement	Design doc section
Proxy over abstract SecretsLike	§5.2
Non-manifested key rejected main-side	§5.2b
No worker-side caching of values	§5.2a (cloneable boundary)

Verification approach

• src/client/client.test.ts — manifested key returns value; non-manifested throws SECRETS_PROXY_NOT_MANIFESTED.
• src/client/no-cache.test.ts — calling get(name) twice issues two main-side calls (no worker-side caching).
• tests/conformance/run-secrets-conformance.test.ts — runSecretsConformance from @suaveplan/api-secrets/testing passes. Required before Stage 4 can complete.

Migration impact

None — additive only.