feat(cloud): add a system-managed Secret Store and runtime secret injection
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
Parent RFC: #1286
Related snapshot boundary: #2369
Raised from [@likun666661's comment](https://github.com/maka-agent/maka-agent/issues/2369#issuecomment-5214121247), which identifies user-authored secrets as a missing platform capability rather than only a Session Bundle filtering concern.
@likun666661 please take a look at this proposed scope and boundary.
## Summary
Define and implement a system-managed Secret Store plus runtime secret injection for Cloud Sessions and Activations.
Workspace files, Session state, and Session Bundles should contain only stable secret references, never secret values. The control plane owns encrypted value storage, authorization, resolution, and runtime injection. Fork and restore operations re-authorize and re-bind references instead of copying credentials.
## Problem
#2369 must fail closed when known user-authored secret files such as `.env`, private keys, or credential files are found in a workspace. That is a necessary safety boundary for legacy and accidental secret placement, but it is not a complete secret-management model.
Without a platform-owned secret capability, users are encouraged to place values in portable workspace or Session state. Those values can then leak through:
- Session Bundle snapshots and forks;
- logs, tool telemetry, diagnostics, and error details;
- workspace history and source control;
- copied or restored sandboxes;
- snapshot manifests and exclusion reports.
Encrypting values inside the portable Session database or workspace does not by itself solve the problem: ciphertext and secret metadata would still be copied, and encryption-key distribution, authorization, revocation, and fork behavior would remain undefined.
## Responsibility boundary
The Secret Store owns:
- a versioned secret-reference contract that does not reveal secret values;
- encrypted value persistence outside portable Session state and Session Bundles;
- authorization and scope checks for each Session/Activation resolution;
- runtime injection into an ephemeral sandbox through explicitly supported targets;
- rotation, revocation, and deletion semantics;
- re-authorization and reference re-binding for fork/restore;
- bounded, redacted audit and error records;
- deterministic cleanup of injected material at Activation/sandbox teardown.
It does not make the Session Bundle codec understand secret semantics or scan payload bytes. It also does not replace #2369's fail-closed handling of known secret files already present in legacy workspaces.
## Proposed execution flow
1. A user or control-plane operation creates or updates a secret outside the Session-owned storage root.
2. The workspace or Session configuration records only a stable reference.
3. Before an Activation starts, the control plane resolves the references under the target user, project, Session, and Activation authorization context.
4. Authorized values are injected into the ephemeral sandbox through a declared mechanism, such as an environment variable or a temporary mounted file.
5. Runtime surfaces treat injected values as sensitive and redact them from logs, diagnostics, telemetry, and manifests.
6. At terminal Activation/sandbox cleanup, injected files and process-local material are removed.
7. Fork/restore copies references only when policy permits, then requires explicit re-authorization or re-binding for the target Session; it never copies secret values in the Bundle.
## Contract decisions required
- Secret ownership and scope: user, organization, project, Session, or another explicit hierarchy.
- Reference identity and portability across Session restore and fork.
- Supported injection targets and their lifetime: environment variables, temporary files, or provider-specific handles.
- Encryption and key-management boundary, including local-development behavior and cloud KMS integration.
- Authorization, rotation, revocation, deletion, and audit semantics.
- Fork/restore policy: which references may be inherited, which must be re-bound, and who can authorize the target.
- Redaction boundaries and the guarantees possible after a secret is exposed to user-authored code or third-party tools.
- Stable failure behavior when a reference is missing, unauthorized, revoked, or cannot be injected safely.
The persistence backend is intentionally not pinned by this issue title or contract. SQLite may be one implementation backend, but keys must remain outside the encrypted value store and the store must remain outside portable Session Bundle state.
## Acceptance criteria
- [ ] A versioned secret-reference contract is defined without embedding secret values.
- [ ] Secret values are stored outside Workspace contents, Session-owned state, and Session Bundles.
- [ ] Values are encrypted at rest behind an explicit key-management boundary.
- [ ] Activation-time resolution performs authorization before any value is injected.
- [ ] Injection targets, lifetime, cleanup, and failure behavior are deterministic and tested.
- [ ] Missing, unauthorized, revoked, and malformed references fail closed with bounded errors.
- [ ] Fork and restore never copy secret values and require the documented re-authorization/re-binding flow.
- [ ] Logs, diagnostics, telemetry, manifests, and audit records do not expose secret values.
- [ ] Rotation and revocation affect subsequent Activations without rewriting committed Session Bundles.
- [ ] End-to-end tests cover create/reference/inject/cleanup, authorization denial, rotation, revocation, restore, and fork.
- [ ] #2369 retains a fail-closed compatibility boundary for known secret files in legacy workspaces.
## Out of scope
- General Session Bundle filtering and quiescent snapshot coordination (#2369).
- SessionRepository revision/CAS and Bundle publication (#2370).
- Cloud Session fork orchestration and identity re-keying (#1415).
- Automatically migrating arbitrary existing `.env` or credential files into the Secret Store.
- Claiming that redaction can recover a value after user-authored code deliberately exports it.
Contributor guide
Assessment
This issue has not been assessed yet.