Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.md
new file mode 100644
index 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