@claude-flow/cli 3.6.23 → 3.6.25

package/dist/src/encryption/vault.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Encryption-at-rest vault primitives (ADR-096 Phase 1).
+ *
+ * Goal: provide deterministic encrypt/decrypt of arbitrary Buffers with a
+ * symmetric key, using a magic-byte format so readers of older plaintext
+ * stores can detect-then-pass-through during the migration window.
+ *
+ * Phase 1 deliberately ships only the cipher primitives + the env-var key
+ * source. Keychain (keytar) and interactive passphrase resolution land in
+ * a follow-up iteration so the blast radius of this commit is limited to
+ * a single self-contained module with no native dependencies.
+ *
+ * Wire format (output of encryptBuffer):
+ *
+ *   +---------+-----------+----------------+--------+
+ *   | magic 4 |   iv 12   |  ciphertext N  | tag 16 |
+ *   +---------+-----------+----------------+--------+
+ *      "RFE1"   random       AES-256-GCM     GCM
+ *
+ * The magic distinguishes encrypted blobs from plaintext during the
+ * incremental migration: readers call isEncryptedBlob() and either
+ * decryptBuffer() or treat the bytes as plaintext, so existing
+ * .claude-flow/sessions/*.json files keep working unchanged.
+ */
+/** ASCII "RFE1" — Ruflo File Encrypted v1. 4 bytes. */
+export declare const MAGIC: Buffer<ArrayBuffer>;
+/**
+ * True when at-rest encryption should be applied to writes.
+ *
+ * Truthy values: "1", "true", "yes", "on" (case-insensitive). Anything else
+ * — including unset — keeps the legacy plaintext path. This is the gate
+ * that lets the 1865-test baseline keep passing unchanged while users opt
+ * into encryption.
+ */
+export declare function isEncryptionEnabled(): boolean;
+/**
+ * Resolve a 32-byte encryption key from CLAUDE_FLOW_ENCRYPTION_KEY.
+ *
+ * Phase 1 supports only the env-var source; keychain and passphrase
+ * resolution are deferred to a follow-up iteration (see ADR-096). When
+ * encryption is enabled but no key resolves, this throws with a clear
+ * message rather than silently falling back to plaintext (fail-closed).
+ *
+ * Accepted encodings (auto-detected by length):
+ *   - 64-char hex (32 bytes)
+ *   - 44-char base64 (32 bytes + padding)
+ *   - exactly 32 raw bytes (rare; for callers that pre-decode)
+ *
+ * Anything else is rejected — we'd rather fail loudly than encrypt with a
+ * truncated key.
+ */
+export declare function getKey(): Buffer;
+/**
+ * Decode a key string. Exposed for testing and for the future passphrase
+ * resolver, which will scrypt-derive a Buffer and hand it back through here
+ * to share the same length-check.
+ */
+export declare function decodeKey(raw: string): Buffer;
+/**
+ * Encrypt a plaintext Buffer with AES-256-GCM. Returns the wire-format
+ * blob: magic(4) || iv(12) || ciphertext(N) || tag(16).
+ *
+ * The IV is freshly randomized per call. Reusing a (key, iv) pair under
+ * GCM is catastrophic — every call MUST produce a different IV. Node's
+ * randomBytes is csprng-backed so this is automatic; the function takes
+ * no IV input deliberately.
+ */
+export declare function encryptBuffer(plaintext: Buffer, key: Buffer): Buffer;
+/**
+ * Decrypt a wire-format blob. Verifies the magic byte (sanity), parses
+ * iv + ciphertext + tag, runs AES-256-GCM decrypt, and lets the GCM
+ * auth tag fail loudly on tamper (Node throws "Unsupported state or
+ * unable to authenticate data" — we let that propagate).
+ *
+ * Pre-condition: caller has already determined this is an encrypted
+ * blob via isEncryptedBlob(). decryptBuffer throws on bad magic so a
+ * mistaken plaintext blob still fails loudly rather than producing
+ * garbage.
+ */
+export declare function decryptBuffer(blob: Buffer, key: Buffer): Buffer;
+/**
+ * Magic-byte sniff. True iff the blob starts with the RFE1 magic AND is
+ * long enough to be a valid encrypted blob. Used by readers during the
+ * incremental migration: legacy plaintext files return false and flow
+ * through the existing read path unchanged.
+ *
+ * Note: this is a heuristic. A plaintext file that happens to start with
+ * "RFE1" would be misdetected — we accept that vanishingly small risk
+ * because (a) the four bytes 0x52,0x46,0x45,0x31 are an unusual prefix
+ * for JSON (`{`, `[`) or SQLite (`SQLite format 3`), and (b) decryption
+ * will then fail with a clear error rather than silently corrupt.
+ */
+export declare function isEncryptedBlob(blob: Buffer): boolean;
+//# sourceMappingURL=vault.d.ts.map

package/dist/src/encryption/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/encryption/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,uDAAuD;AACvD,eAAO,MAAM,KAAK,qBAAwC,CAAC;AAa3D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAK7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAU/B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAc7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAYpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CA2B/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIrD"}

package/dist/src/encryption/vault.js

@@ -0,0 +1,172 @@
+/**
+ * Encryption-at-rest vault primitives (ADR-096 Phase 1).
+ *
+ * Goal: provide deterministic encrypt/decrypt of arbitrary Buffers with a
+ * symmetric key, using a magic-byte format so readers of older plaintext
+ * stores can detect-then-pass-through during the migration window.
+ *
+ * Phase 1 deliberately ships only the cipher primitives + the env-var key
+ * source. Keychain (keytar) and interactive passphrase resolution land in
+ * a follow-up iteration so the blast radius of this commit is limited to
+ * a single self-contained module with no native dependencies.
+ *
+ * Wire format (output of encryptBuffer):
+ *
+ *   +---------+-----------+----------------+--------+
+ *   | magic 4 |   iv 12   |  ciphertext N  | tag 16 |
+ *   +---------+-----------+----------------+--------+
+ *      "RFE1"   random       AES-256-GCM     GCM
+ *
+ * The magic distinguishes encrypted blobs from plaintext during the
+ * incremental migration: readers call isEncryptedBlob() and either
+ * decryptBuffer() or treat the bytes as plaintext, so existing
+ * .claude-flow/sessions/*.json files keep working unchanged.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual, } from 'node:crypto';
+// ── Constants ────────────────────────────────────────────────────────────────
+/** ASCII "RFE1" — Ruflo File Encrypted v1. 4 bytes. */
+export const MAGIC = Buffer.from([0x52, 0x46, 0x45, 0x31]); // "RFE1"
+const MAGIC_LEN = MAGIC.length; // 4
+const IV_LEN = 12; // GCM-recommended nonce size
+const TAG_LEN = 16; // GCM auth tag
+const KEY_LEN = 32; // AES-256
+const ALG = 'aes-256-gcm';
+const MIN_BLOB_LEN = MAGIC_LEN + IV_LEN + TAG_LEN; // empty plaintext still has these
+const ENV_ENABLE_FLAG = 'CLAUDE_FLOW_ENCRYPT_AT_REST';
+const ENV_KEY_VAR = 'CLAUDE_FLOW_ENCRYPTION_KEY';
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * True when at-rest encryption should be applied to writes.
+ *
+ * Truthy values: "1", "true", "yes", "on" (case-insensitive). Anything else
+ * — including unset — keeps the legacy plaintext path. This is the gate
+ * that lets the 1865-test baseline keep passing unchanged while users opt
+ * into encryption.
+ */
+export function isEncryptionEnabled() {
+    const v = process.env[ENV_ENABLE_FLAG];
+    if (typeof v !== 'string')
+        return false;
+    const norm = v.trim().toLowerCase();
+    return norm === '1' || norm === 'true' || norm === 'yes' || norm === 'on';
+}
+/**
+ * Resolve a 32-byte encryption key from CLAUDE_FLOW_ENCRYPTION_KEY.
+ *
+ * Phase 1 supports only the env-var source; keychain and passphrase
+ * resolution are deferred to a follow-up iteration (see ADR-096). When
+ * encryption is enabled but no key resolves, this throws with a clear
+ * message rather than silently falling back to plaintext (fail-closed).
+ *
+ * Accepted encodings (auto-detected by length):
+ *   - 64-char hex (32 bytes)
+ *   - 44-char base64 (32 bytes + padding)
+ *   - exactly 32 raw bytes (rare; for callers that pre-decode)
+ *
+ * Anything else is rejected — we'd rather fail loudly than encrypt with a
+ * truncated key.
+ */
+export function getKey() {
+    const raw = process.env[ENV_KEY_VAR];
+    if (!raw) {
+        throw new Error(`${ENV_ENABLE_FLAG} is set but ${ENV_KEY_VAR} is not. ` +
+            `Provide a 32-byte key as 64-char hex or 44-char base64. ` +
+            `See ADR-096 for keychain/passphrase support (coming in a follow-up).`);
+    }
+    return decodeKey(raw);
+}
+/**
+ * Decode a key string. Exposed for testing and for the future passphrase
+ * resolver, which will scrypt-derive a Buffer and hand it back through here
+ * to share the same length-check.
+ */
+export function decodeKey(raw) {
+    const trimmed = raw.trim();
+    // Hex first — strict 64 chars [0-9a-fA-F]
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+        return Buffer.from(trimmed, 'hex');
+    }
+    // Base64 — accept padded 44-char or unpadded 43-char forms
+    if (/^[A-Za-z0-9+/]{43}=?$/.test(trimmed)) {
+        const buf = Buffer.from(trimmed, 'base64');
+        if (buf.length === KEY_LEN)
+            return buf;
+    }
+    throw new Error(`Invalid ${ENV_KEY_VAR}: expected 32-byte key as 64-char hex or 44-char base64`);
+}
+/**
+ * Encrypt a plaintext Buffer with AES-256-GCM. Returns the wire-format
+ * blob: magic(4) || iv(12) || ciphertext(N) || tag(16).
+ *
+ * The IV is freshly randomized per call. Reusing a (key, iv) pair under
+ * GCM is catastrophic — every call MUST produce a different IV. Node's
+ * randomBytes is csprng-backed so this is automatic; the function takes
+ * no IV input deliberately.
+ */
+export function encryptBuffer(plaintext, key) {
+    if (!Buffer.isBuffer(plaintext)) {
+        throw new TypeError('encryptBuffer: plaintext must be a Buffer');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+        throw new TypeError(`encryptBuffer: key must be a ${KEY_LEN}-byte Buffer`);
+    }
+    const iv = randomBytes(IV_LEN);
+    const cipher = createCipheriv(ALG, key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([MAGIC, iv, ciphertext, tag]);
+}
+/**
+ * Decrypt a wire-format blob. Verifies the magic byte (sanity), parses
+ * iv + ciphertext + tag, runs AES-256-GCM decrypt, and lets the GCM
+ * auth tag fail loudly on tamper (Node throws "Unsupported state or
+ * unable to authenticate data" — we let that propagate).
+ *
+ * Pre-condition: caller has already determined this is an encrypted
+ * blob via isEncryptedBlob(). decryptBuffer throws on bad magic so a
+ * mistaken plaintext blob still fails loudly rather than producing
+ * garbage.
+ */
+export function decryptBuffer(blob, key) {
+    if (!Buffer.isBuffer(blob)) {
+        throw new TypeError('decryptBuffer: blob must be a Buffer');
+    }
+    if (!Buffer.isBuffer(key) || key.length !== KEY_LEN) {
+        throw new TypeError(`decryptBuffer: key must be a ${KEY_LEN}-byte Buffer`);
+    }
+    if (blob.length < MIN_BLOB_LEN) {
+        throw new Error(`decryptBuffer: blob too short (${blob.length}B; need >= ${MIN_BLOB_LEN}B)`);
+    }
+    const magic = blob.subarray(0, MAGIC_LEN);
+    // timingSafeEqual to avoid an oracle on the magic bytes specifically;
+    // not strictly required (the magic isn't secret) but cheap and correct.
+    if (!timingSafeEqual(magic, MAGIC)) {
+        throw new Error('decryptBuffer: bad magic — blob is not Ruflo-encrypted (RFE1)');
+    }
+    const iv = blob.subarray(MAGIC_LEN, MAGIC_LEN + IV_LEN);
+    const tag = blob.subarray(blob.length - TAG_LEN);
+    const ciphertext = blob.subarray(MAGIC_LEN + IV_LEN, blob.length - TAG_LEN);
+    const decipher = createDecipheriv(ALG, key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Magic-byte sniff. True iff the blob starts with the RFE1 magic AND is
+ * long enough to be a valid encrypted blob. Used by readers during the
+ * incremental migration: legacy plaintext files return false and flow
+ * through the existing read path unchanged.
+ *
+ * Note: this is a heuristic. A plaintext file that happens to start with
+ * "RFE1" would be misdetected — we accept that vanishingly small risk
+ * because (a) the four bytes 0x52,0x46,0x45,0x31 are an unusual prefix
+ * for JSON (`{`, `[`) or SQLite (`SQLite format 3`), and (b) decryption
+ * will then fail with a clear error rather than silently corrupt.
+ */
+export function isEncryptedBlob(blob) {
+    if (!Buffer.isBuffer(blob))
+        return false;
+    if (blob.length < MIN_BLOB_LEN)
+        return false;
+    return timingSafeEqual(blob.subarray(0, MAGIC_LEN), MAGIC);
+}
+//# sourceMappingURL=vault.js.map

package/dist/src/encryption/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../../src/encryption/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAEhF,uDAAuD;AACvD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;AACrE,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI;AACpC,MAAM,MAAM,GAAG,EAAE,CAAC,CAAc,6BAA6B;AAC7D,MAAM,OAAO,GAAG,EAAE,CAAC,CAAa,eAAe;AAC/C,MAAM,OAAO,GAAG,EAAE,CAAC,CAAa,UAAU;AAC1C,MAAM,GAAG,GAAG,aAAsB,CAAC;AACnC,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,kCAAkC;AAErF,MAAM,eAAe,GAAG,6BAA6B,CAAC;AACtD,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACvC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,IAAI,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,MAAM;IACpB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,GAAG,eAAe,eAAe,WAAW,WAAW;YACvD,0DAA0D;YAC1D,sEAAsE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,0CAA0C;IAC1C,IAAI,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IACD,2DAA2D;IAC3D,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC3C,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO;YAAE,OAAO,GAAG,CAAC;IACzC,CAAC;IACD,MAAM,IAAI,KAAK,CACb,WAAW,WAAW,yDAAyD,CAChF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,GAAW;IAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CAAC,gCAAgC,OAAO,cAAc,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CAAC,gCAAgC,OAAO,cAAc,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,kCAAkC,IAAI,CAAC,MAAM,cAAc,YAAY,IAAI,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1C,sEAAsE;IACtE,wEAAwE;IACxE,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,GAAG,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;IAE5E,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAChD,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/dist/src/fs-secure.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Restricted-permission file helpers.
+ *
+ * audit_1776853149979: session/memory/terminal stores were written with the
+ * process umask, which on most macOS/Linux setups leaves them world-readable
+ * (mode 0644). They contain conversation snapshots, agent prompts, and
+ * terminal command history — anyone else on the host can read them.
+ *
+ * These helpers write atomically and force mode 0600 (files) / 0700 (dirs).
+ * chmod fails silently on Windows, where POSIX modes don't apply — that's
+ * fine, the OS-level ACL surface there is different.
+ *
+ * ADR-096 Phase 2: optional opt-in encryption-at-rest. When the caller
+ * passes `encrypt: true` AND the env-gated vault is enabled, payloads are
+ * AES-256-GCM-encrypted before hitting disk. Reads use the magic-byte
+ * sniff so legacy plaintext files keep working unchanged during the
+ * incremental migration.
+ */
+/**
+ * Create a directory tree with mode 0700 (owner-only). No-op if exists.
+ * Uses recursive: true so missing parents are created with the same mode.
+ */
+export declare function mkdirRestricted(path: string): void;
+/**
+ * Options for writeFileRestricted. Object form so we can grow the API
+ * without churning every call site.
+ */
+export interface WriteOptions {
+    /** Buffer encoding when `data` is a string. Ignored for Buffer payloads. */
+    encoding?: BufferEncoding;
+    /**
+     * If true AND encryption is globally enabled (CLAUDE_FLOW_ENCRYPT_AT_REST),
+     * encrypt the payload with AES-256-GCM before writing. If encryption is
+     * NOT enabled, this flag is silently ignored — the legacy plaintext path
+     * runs unchanged. Default: false.
+     */
+    encrypt?: boolean;
+}
+/**
+ * Write a file and tighten its permissions to mode 0600 (owner read/write).
+ *
+ * Two call signatures, both supported (the legacy positional one keeps
+ * existing call sites working without churn):
+ *
+ *   writeFileRestricted(path, data)                      // plaintext, utf-8
+ *   writeFileRestricted(path, data, 'utf-8')             // legacy: encoding only
+ *   writeFileRestricted(path, data, { encrypt: true })   // opt-in encryption
+ */
+export declare function writeFileRestricted(path: string, data: string | Buffer, optsOrEncoding?: BufferEncoding | WriteOptions): void;
+/**
+ * Read a file and transparently decrypt if it carries the RFE1 magic.
+ *
+ * Returns a string when the caller asks for one (default utf-8). Returns
+ * a Buffer when `encoding` is null. This matches Node's readFileSync
+ * shape so the function is a near-drop-in replacement.
+ *
+ * Migration semantics:
+ *   - If the file IS encrypted, decrypt and return.
+ *   - If the file is NOT encrypted, return its raw bytes (string-decoded
+ *     under `encoding` if requested).
+ *
+ * That means a reader can be migrated *first*, before its writer flips
+ * `encrypt: true`, without breaking on the legacy plaintext path.
+ */
+export declare function readFileMaybeEncrypted(path: string, encoding?: BufferEncoding): string;
+export declare function readFileMaybeEncrypted(path: string, encoding: null): Buffer;
+//# sourceMappingURL=fs-secure.d.ts.map

package/dist/src/fs-secure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-secure.d.ts","sourceRoot":"","sources":["../../src/fs-secure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,cAAc,GAAE,cAAc,GAAG,YAAsB,GACtD,IAAI,CA0BN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,cAAc,GACxB,MAAM,CAAC;AACV,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,IAAI,GACb,MAAM,CAAC"}

package/dist/src/fs-secure.js

@@ -0,0 +1,74 @@
+/**
+ * Restricted-permission file helpers.
+ *
+ * audit_1776853149979: session/memory/terminal stores were written with the
+ * process umask, which on most macOS/Linux setups leaves them world-readable
+ * (mode 0644). They contain conversation snapshots, agent prompts, and
+ * terminal command history — anyone else on the host can read them.
+ *
+ * These helpers write atomically and force mode 0600 (files) / 0700 (dirs).
+ * chmod fails silently on Windows, where POSIX modes don't apply — that's
+ * fine, the OS-level ACL surface there is different.
+ *
+ * ADR-096 Phase 2: optional opt-in encryption-at-rest. When the caller
+ * passes `encrypt: true` AND the env-gated vault is enabled, payloads are
+ * AES-256-GCM-encrypted before hitting disk. Reads use the magic-byte
+ * sniff so legacy plaintext files keep working unchanged during the
+ * incremental migration.
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { decryptBuffer, encryptBuffer, getKey, isEncryptedBlob, isEncryptionEnabled, } from './encryption/vault.js';
+/**
+ * Create a directory tree with mode 0700 (owner-only). No-op if exists.
+ * Uses recursive: true so missing parents are created with the same mode.
+ */
+export function mkdirRestricted(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+/**
+ * Write a file and tighten its permissions to mode 0600 (owner read/write).
+ *
+ * Two call signatures, both supported (the legacy positional one keeps
+ * existing call sites working without churn):
+ *
+ *   writeFileRestricted(path, data)                      // plaintext, utf-8
+ *   writeFileRestricted(path, data, 'utf-8')             // legacy: encoding only
+ *   writeFileRestricted(path, data, { encrypt: true })   // opt-in encryption
+ */
+export function writeFileRestricted(path, data, optsOrEncoding = 'utf-8') {
+    const opts = typeof optsOrEncoding === 'string'
+        ? { encoding: optsOrEncoding }
+        : optsOrEncoding;
+    const encoding = opts.encoding ?? 'utf-8';
+    let payload = data;
+    if (opts.encrypt && isEncryptionEnabled()) {
+        const plaintext = Buffer.isBuffer(data) ? data : Buffer.from(data, encoding);
+        payload = encryptBuffer(plaintext, getKey());
+    }
+    // For encrypted payloads we always have a Buffer — pass through without an
+    // encoding so writeFileSync doesn't try to text-decode it.
+    if (Buffer.isBuffer(payload)) {
+        writeFileSync(path, payload);
+    }
+    else {
+        writeFileSync(path, payload, encoding);
+    }
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows / FS without POSIX modes — silently skip.
+    }
+}
+export function readFileMaybeEncrypted(path, encoding = 'utf-8') {
+    const raw = readFileSync(path);
+    let plain;
+    if (isEncryptedBlob(raw)) {
+        plain = decryptBuffer(raw, getKey());
+    }
+    else {
+        plain = raw;
+    }
+    return encoding === null ? plain : plain.toString(encoding);
+}
+//# sourceMappingURL=fs-secure.js.map

package/dist/src/fs-secure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-secure.js","sourceRoot":"","sources":["../../src/fs-secure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EACL,aAAa,EACb,aAAa,EACb,MAAM,EACN,eAAe,EACf,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACpD,CAAC;AAkBD;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,IAAqB,EACrB,iBAAgD,OAAO;IAEvD,MAAM,IAAI,GACR,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE;QAC9B,CAAC,CAAC,cAAc,CAAC;IACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC;IAE1C,IAAI,OAAO,GAAoB,IAAI,CAAC;IACpC,IAAI,IAAI,CAAC,OAAO,IAAI,mBAAmB,EAAE,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC7E,OAAO,GAAG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,2EAA2E;IAC3E,2DAA2D;IAC3D,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;AACH,CAAC;AAyBD,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,WAAkC,OAAO;IAEzC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAa,CAAC;IAClB,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,GAAG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;IACD,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC9D,CAAC"}

package/dist/src/mcp-tools/github-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/github-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,YAAY,CAAC;AA8EzD,eAAO,MAAM,WAAW,EAAE,OAAO,EAmbhC,CAAC"}
+{"version":3,"file":"github-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/github-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,YAAY,CAAC;AAqIzD,eAAO,MAAM,WAAW,EAAE,OAAO,EAqdhC,CAAC"}