π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): ADR-096 β encryption-at-rest design (audit_1776853149979)
Reuvene6478f9ab540
diff --git a/v3/docs/adr/ADR-096-encryption-at-rest.md b/v3/docs/adr/ADR-096-encryption-at-rest.mdnew file mode 100644index 0000000000..d7dddb50d8--- /dev/null+++ b/v3/docs/adr/ADR-096-encryption-at-rest.md@@ -0,0 +1,144 @@+# ADR-096: Encryption at Rest for Session, Memory, and Terminal Stores++**Status**: Proposed+**Date**: 2026-05-03+**Version**: target v3.6.x (post-batch publish)+**Supersedes**: nothing+**Related**: ADR-093 (May 2026 audit remediation), ADR-095 (April architectural gaps), audit_1776853149979 finding "Plaintext session/memory storage", commits `de96b0e` (chmod 0600 mitigation), `fb256ac` (loader-hijack env denylist)++## Context++The May 2026 audit (`audit_1776853149979`) flagged plaintext storage of session and memory state as a class-3 finding. The defense-in-depth mitigation (`de96b0e`, iter #35) restricts file mode to 0600 and dir mode to 0700 for the audit-cited writers. That closes the cross-user-on-same-host vector but does **not** protect against:++1. **Backup exfiltration** β a Time Machine snapshot, a Dropbox sync, or any backup tool that copies `.claude-flow/` reads with the *backup user's* permissions, not the original mode.+2. **Disk forensics** β a recovered SSD or stolen laptop without FileVault yields the plaintext bytes regardless of file mode.+3. **Hostile shared-tenant environments** β CI runners, dev containers, and shared workspaces where the FS perms are scoped wider than the project owner.+4. **Process memory dumps** β orthogonal; out of scope for this ADR.++### What's at-rest today (sensitivity tiers)++| Store | Path | Sensitivity | Reason |+|---|---|---|---|+| Session JSON | `.claude-flow/sessions/*.json` | **High** | Bundles memory snapshots + agent prompts on save |+| Memory DB (sql.js SQLite) | `.swarm/memory.db` | **High** | Conversation entries + 384-dim embeddings; embeddings leak topics |+| Terminal history | `.claude-flow/terminals/store.json` | **High** | Pasted shell commands often include API keys, DB passwords |+| Agent registry | `.claude-flow/agents/store.json` | Medium | Agent configs incl. model + domain; no prompts |+| Task store | `.claude-flow/tasks/store.json` | Medium | Task descriptions + status |+| Claims / config / workflow / neural / DAA / GitHub stores | various under `.claude-flow/` | LowβMedium | Mostly metadata; case-by-case |+| Update history | `~/.claude-flow/update-history.json` | Low | Package names + versions; relevant only for the integrity gate added in `c1b57e4f` |+| Attestation log | `.swarm/attestation.db` | Low | Hash chain of mutations; integrity-protective, not confidentiality-sensitive |++### Existing crypto in the codebase++`src/appliance/rvfa-builder.ts` and `rvfa-runner.ts` already use `aes-256-gcm` + `scryptSync` (key-derivation) + `randomBytes` for the RVFA appliance vault. Same stack can be reused β no new dependency.++## Decision++Ship encryption at rest in three phases. Each phase is independently shippable and testable.++### Phase 1 (this ADR's scope) β opt-in encrypted vault++**Posture**: opt-in via `CLAUDE_FLOW_ENCRYPT_AT_REST=1`. Default off so the 1865 existing tests and current users keep working unchanged.++**What's encrypted**: only the **High** tier (`sessions/`, `.swarm/memory.db`, `terminals/`). The Medium and Low tier stores stay plaintext for now β they hold nothing the audit specifically flagged.++**Algorithm**: `aes-256-gcm` with random 12-byte nonce per file, 16-byte auth tag appended. Format:++```++---------+--------+----------------+--------++| magic 4 | iv 12 | ciphertext N | tag 16 |++---------+--------+----------------+--------++ "RFE1" random plaintext xor GCM+```++Magic `"RFE1"` (Ruflo File Encrypted v1) β distinguishes from plaintext on read so we can roll out incrementally without a repo-wide migration.++**Key source** (precedence, fail closed):++1. `CLAUDE_FLOW_ENCRYPTION_KEY` β base64-encoded 32 bytes. Highest precedence, useful for CI / containers / users who already have a secret manager.+2. OS keychain β `keytar`-style lookup under service `claude-flow`, account `default`. macOS Keychain, Windows DPAPI, libsecret on Linux. **Optional dependency**: `keytar` is a native module; if unavailable, fall back to (3).+3. Passphrase prompt + scrypt KDF β interactive only. Stored derived key in process memory for the session, never on disk. Salt persisted at `~/.claude-flow/.kdf-salt` (16 bytes random, mode 0600).++If `CLAUDE_FLOW_ENCRYPT_AT_REST=1` and *no* key source resolves, the CLI **errors immediately** rather than silently writing plaintext. Fail-closed posture.++**Migration**: lazy. On read, sniff the magic. If `"RFE1"`, decrypt; otherwise treat as plaintext (backward compatible). On the *first write* after enable, the file is rewritten encrypted. A `ruflo migrate encrypt` subcommand (also opt-in) does an eager pass for users who want it now.++**Out of scope**:+- Key rotation (next phase)+- Encrypted backups / off-host sync (orthogonal)+- Per-tenant keys for multi-user installs (different threat model)++### Phase 2 (separate ADR) β key rotation + sealed-box backups++`ruflo encryption rotate` re-encrypts all High-tier stores under a new key. Existing key kept for read-only one cycle to avoid bricking running daemons. Sealed-box format (`age` or `nacl.box`) for files that need to survive off-host transfer.++### Phase 3 (separate ADR) β extend coverage to Medium-tier stores + AgentDB column-level encryption++After Phase 1 ships and the migration story is proven, extend to `agents/`, `tasks/`, and any AgentDB columns that hold free-form text. AgentDB column-level needs SQLite extension support β open question.++## Implementation outline++This ADR proposes the design; the implementation iteration ships in a separate commit. Order of operations:++1. **`src/encryption/vault.ts`** β new module. Exports:+ - `isEncryptionEnabled(): boolean` β env-var check+ - `getKey(): Promise<Buffer>` β key resolution per the precedence above+ - `encryptBuffer(plain: Buffer, key: Buffer): Buffer` β magic + iv + ct + tag+ - `decryptBuffer(blob: Buffer, key: Buffer): Buffer` β verify magic, parse, GCM-verify+ - `isEncryptedBlob(blob: Buffer): boolean` β magic sniff for migration++2. **Wire into `src/fs-secure.ts`** (already exists from iter #35). Extend `writeFileRestricted` with an opt-in `encrypt: boolean` flag. Default `false` to keep existing call sites working.++3. **Update three call sites**:+ - `mcp-tools/session-tools.ts:saveSession` β pass `encrypt: isEncryptionEnabled()`+ - `mcp-tools/terminal-tools.ts:saveTerminalStore` β same+ - `memory/memory-initializer.ts` β the seven `writeFileRestricted(dbPath, ...)` writes need a different shape (sql.js exports a Buffer of the whole DB; encrypt the whole Buffer). On open, check magic; if encrypted, decrypt to in-memory buffer and pass to `new SQL.Database(buf)`.++4. **Read paths** β every reader of those three stores already exists. Wrap each `readFileSync(path)` in a `decryptIfEncrypted(blob, key)` helper. Backwards-compat for plaintext via the magic sniff.++5. **Tests** (`__tests__/encryption-vault.test.ts`):+ - encrypt β decrypt round-trip+ - tamper detection (flip one byte β GCM auth fails)+ - magic sniff: plaintext blob returns plaintext, encrypted returns decrypted+ - key precedence: env-var > keychain > passphrase+ - fail-closed when enabled with no key++6. **Doctor check** β `ruflo doctor` reports encryption status (off / on with env-var / on with keychain / on with passphrase).++7. **Documentation** β `docs/security/encryption.md` covers user-facing setup, recovery if a key is lost (the data is gone β by design), and CI guidance (set `CLAUDE_FLOW_ENCRYPTION_KEY` in repo secrets).++## Trade-offs++| Decision | Alternative | Why we chose this |+|---|---|---|+| Opt-in via env var | Always-on | 1865 tests pass today against plaintext. Always-on without a migration story regresses the test suite and bricks every existing user's install on upgrade. Opt-in is reversible. |+| AES-256-GCM | ChaCha20-Poly1305, age, libsodium | GCM already shipped + tested in rvfa-builder. No new native dependency. |+| Magic-byte sniff for migration | Filename suffix, separate dir | The set of writers is small but the readers are scattered; a magic byte means readers self-detect without coordinated migration. |+| Keychain via optional `keytar` | Force keychain everywhere | `keytar` is a native module β making it required regresses cross-platform install (Alpine containers, Termux, NixOS without binary cache). Optional with env-var fallback covers the realistic cases. |+| Per-file IV, no per-store key | Per-store key derivation | Per-store keys complicate rotation and key recovery. One process-key + per-file IV gives the same security and a much simpler rotation story. |+| Encrypt only High-tier stores in Phase 1 | Encrypt everything | Embeddings + commands + agent prompts cover ~95% of the audit's concern. Medium-tier stores have far fewer and lower-value secrets β adding them later when migration is proven is safer. |++## Risks++1. **Lost-key data loss**. If a user enables encryption then loses the key (env var unset, keychain wiped, passphrase forgotten), their memory + sessions are unrecoverable. Document this prominently. Consider a recovery-passphrase escrow option in Phase 2.+2. **Performance cost of per-write encryption**. AES-GCM is ~1 GB/s on modern x64 with AES-NI; for sub-MB writes the overhead is sub-ms. Memory DB writes are larger (multi-MB) but already infrequent. Bench in the implementation iteration.+3. **Compromise of the key in process memory**. Out of scope for at-rest encryption. Memory dumps are a different threat (Phase 4 if it ever becomes relevant).+4. **Cross-platform keychain divergence**. `keytar` works but is unmaintained. Consider `node-keytar` fork or libsecret-direct binding when implementing. Pinning the version is a must.++## Open questions++- **Daemon vs CLI**: the daemon long-lived process and the CLI one-shot process need to share a key. For env-var/keychain, they both read the same source. For passphrase, the daemon would need to be started with the passphrase or a derived key passed in via stdin. Document the daemon-mode setup explicitly.+- **MCP server mode**: when started by Claude Code via `claude mcp add`, the MCP server inherits Claude Code's environment. The user has to set `CLAUDE_FLOW_ENCRYPTION_KEY` in the env Claude Code launches with β which is doable but non-obvious. A `~/.claude-flow/encryption.json` config (mode 0600, keychain reference) might be cleaner than env-var-everywhere. Decide in implementation.+- **AgentDB v3 native encryption**: if AgentDB ever exposes a transparent column-encryption API, switch to it for the memory DB. Until then, file-level on the whole DB blob is correct.++## Acceptance criteria++The implementation iteration is done when:++- `CLAUDE_FLOW_ENCRYPT_AT_REST=1` round-trips a session save β restore unchanged+- A plaintext `.claude-flow/sessions/foo.json` from before the upgrade is still readable after the upgrade (magic-sniff backward compat)+- A flipped byte in any encrypted file produces a decrypt error, not a panic+- The 1865-test baseline stays green with `CLAUDE_FLOW_ENCRYPT_AT_REST` unset+- A new test file `__tests__/encryption-vault.test.ts` exercises every path above+- `ruflo doctor` reports encryption status+- The witness manifest (`verification.md.json`) gains a fix entry covering the new vault module so `ruflo verify` confirms it after publish