@swarmdo/cli 1.4.8

package/dist/src/config-lint/lint.js

@@ -0,0 +1,172 @@
+/**
+ * lint.ts — static validation of a project's swarmdo config surfaces.
+ *
+ * Complements the runtime doctors: `doctor` probes the environment and
+ * `mcp doctor` probes server binaries/URLs; `config lint` is the PURE shape
+ * layer — parse errors, schema violations, unknown keys, malformed hook
+ * entries, and pre-1.4 layout leftovers — with no PATH probing and no
+ * network. Every rule takes parsed input and returns findings, so the whole
+ * ruleset is unit-testable; the command layer only reads files.
+ */
+const f = (file, severity, rule, message) => ({ file, severity, rule, message });
+export const TOPOLOGIES = ['hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive'];
+export const MEMORY_BACKENDS = ['agentdb', 'sqlite', 'hybrid', 'memory'];
+export const KNOWN_CONFIG_KEYS = ['topology', 'maxAgents', 'strategy', 'consensus', 'memory', 'memoryBackend', 'hnsw', 'neural', 'embeddings', 'providers', 'mcp', 'logging', 'daemon', 'hooks', 'version', '$schema'];
+export const HOOK_EVENTS = [
+    'PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Notification', 'Stop', 'SubagentStop',
+    'SessionStart', 'SessionEnd', 'PreCompact', 'TeammateIdle', 'TaskCompleted', 'PermissionDecision',
+];
+/** Parse a JSON file's raw text; a null raw means "file absent" (fine). */
+export function lintJson(file, raw) {
+    if (raw === null)
+        return { obj: undefined, findings: [] };
+    try {
+        return { obj: JSON.parse(raw), findings: [] };
+    }
+    catch (e) {
+        return { obj: undefined, findings: [f(file, 'error', 'invalid-json', `not valid JSON: ${e.message}`)] };
+    }
+}
+/** swarmdo.config.json: enums + ranges + unknown keys. */
+export function lintSwarmdoConfig(file, obj) {
+    if (obj === undefined)
+        return [];
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return [f(file, 'error', 'config-shape', 'top level must be a JSON object')];
+    }
+    const out = [];
+    const c = obj;
+    for (const key of Object.keys(c)) {
+        if (!KNOWN_CONFIG_KEYS.includes(key))
+            out.push(f(file, 'warn', 'unknown-key', `unknown key "${key}" (known: ${KNOWN_CONFIG_KEYS.filter(k => k !== '$schema').join(', ')})`));
+    }
+    if (c.topology !== undefined && !TOPOLOGIES.includes(String(c.topology))) {
+        out.push(f(file, 'error', 'bad-topology', `topology "${String(c.topology)}" is not one of: ${TOPOLOGIES.join(', ')}`));
+    }
+    if (c.maxAgents !== undefined && (typeof c.maxAgents !== 'number' || !Number.isInteger(c.maxAgents) || c.maxAgents < 1 || c.maxAgents > 64)) {
+        out.push(f(file, 'error', 'bad-max-agents', `maxAgents must be an integer 1–64 (got ${JSON.stringify(c.maxAgents)})`));
+    }
+    const backend = (c.memoryBackend ?? c.memory?.backend);
+    if (backend !== undefined && !MEMORY_BACKENDS.includes(String(backend))) {
+        out.push(f(file, 'error', 'bad-memory-backend', `memory backend "${String(backend)}" is not one of: ${MEMORY_BACKENDS.join(', ')}`));
+    }
+    return out;
+}
+/** .claude/settings*.json: the hooks block must match Claude Code's schema. */
+export function lintSettingsHooks(file, obj) {
+    if (obj === undefined || obj === null || typeof obj !== 'object')
+        return [];
+    const hooks = obj.hooks;
+    if (hooks === undefined)
+        return [];
+    if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) {
+        return [f(file, 'error', 'hooks-shape', '`hooks` must be an object of event → entries[]')];
+    }
+    const out = [];
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (!HOOK_EVENTS.includes(event))
+            out.push(f(file, 'warn', 'unknown-hook-event', `unknown hook event "${event}" (known: ${HOOK_EVENTS.join(', ')})`));
+        if (!Array.isArray(entries)) {
+            out.push(f(file, 'error', 'hook-entries-shape', `hooks.${event} must be an array`));
+            continue;
+        }
+        entries.forEach((entry, i) => {
+            const where = `hooks.${event}[${i}]`;
+            if (entry === null || typeof entry !== 'object') {
+                out.push(f(file, 'error', 'hook-entry-shape', `${where} must be an object`));
+                return;
+            }
+            const e = entry;
+            if (e.matcher !== undefined && typeof e.matcher !== 'string')
+                out.push(f(file, 'error', 'hook-matcher-type', `${where}.matcher must be a string`));
+            if (!Array.isArray(e.hooks) || e.hooks.length === 0) {
+                out.push(f(file, 'error', 'hook-inner-shape', `${where}.hooks must be a non-empty array of {type, command}`));
+                return;
+            }
+            e.hooks.forEach((h, j) => {
+                const hw = `${where}.hooks[${j}]`;
+                const hh = (h ?? {});
+                if (hh.type !== 'command')
+                    out.push(f(file, 'error', 'hook-type', `${hw}.type must be "command" (got ${JSON.stringify(hh.type)})`));
+                if (typeof hh.command !== 'string' || hh.command.trim() === '')
+                    out.push(f(file, 'error', 'hook-command', `${hw}.command must be a non-empty string`));
+            });
+        });
+    }
+    return out;
+}
+/** .mcp.json: server entry SHAPES only (mcp doctor probes the runtime). */
+export function lintMcpConfig(file, obj) {
+    if (obj === undefined)
+        return [];
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return [f(file, 'error', 'mcp-shape', 'top level must be a JSON object')];
+    }
+    const servers = obj.mcpServers;
+    if (servers === undefined)
+        return [f(file, 'warn', 'mcp-no-servers', 'no `mcpServers` key — file has no effect')];
+    if (servers === null || typeof servers !== 'object' || Array.isArray(servers)) {
+        return [f(file, 'error', 'mcp-servers-shape', '`mcpServers` must be an object of name → definition')];
+    }
+    const out = [];
+    for (const [name, def] of Object.entries(servers)) {
+        if (def === null || typeof def !== 'object') {
+            out.push(f(file, 'error', 'mcp-server-shape', `server "${name}" must be an object`));
+            continue;
+        }
+        const d = def;
+        const transport = String(d.type ?? (d.url ? 'http' : 'stdio'));
+        if (transport === 'stdio') {
+            if (typeof d.command !== 'string' || d.command.trim() === '')
+                out.push(f(file, 'error', 'mcp-missing-command', `server "${name}" (stdio) needs a non-empty \`command\``));
+            if (d.args !== undefined && !Array.isArray(d.args))
+                out.push(f(file, 'error', 'mcp-args-type', `server "${name}": \`args\` must be an array`));
+        }
+        else {
+            const url = String(d.url ?? '');
+            if (!/^(https?|wss?):\/\/.+/.test(url))
+                out.push(f(file, 'error', 'mcp-bad-url', `server "${name}" (${transport}) needs a valid http(s)/ws(s) \`url\` (got ${JSON.stringify(d.url ?? null)})`));
+        }
+        if (d.env !== undefined && (d.env === null || typeof d.env !== 'object' || Array.isArray(d.env))) {
+            out.push(f(file, 'error', 'mcp-env-type', `server "${name}": \`env\` must be an object`));
+        }
+    }
+    return out;
+}
+/** Pre-1.4 layout leftovers: flat commands / unprefixed skill duplicates. */
+export function lintLegacyLayout(commandsRoot, skills) {
+    const out = [];
+    const flat = commandsRoot.filter((n) => n !== 'sDo');
+    if (flat.length > 0) {
+        out.push(f('.claude/commands', 'warn', 'pre-1.4-commands', `${flat.length} entr${flat.length === 1 ? 'y' : 'ies'} outside the sDo/ namespace (${flat.slice(0, 5).join(', ')}${flat.length > 5 ? ', …' : ''}) — swarmdo commands moved to /sDo:* in v1.4.0; re-run \`swarmdo init --force\` to migrate swarmdo-owned ones`));
+    }
+    const skillSet = new Set(skills);
+    const dupes = skills.filter((s) => !s.startsWith('sdo-') && skillSet.has(`sdo-${s}`));
+    for (const d of dupes) {
+        out.push(f(`.claude/skills/${d}`, 'warn', 'duplicate-legacy-skill', `both "${d}" and "sdo-${d}" exist — the unprefixed copy is a pre-1.4 leftover; remove it or re-run \`swarmdo efficiency on\`/\`init --force\``));
+    }
+    return out;
+}
+/** Run every rule over pre-read inputs. Pure. */
+export function lintAll(input) {
+    const findings = [];
+    if (input.swarmdoConfig) {
+        const { obj, findings: jf } = lintJson(input.swarmdoConfig.file, input.swarmdoConfig.raw);
+        findings.push(...jf, ...lintSwarmdoConfig(input.swarmdoConfig.file, obj));
+    }
+    for (const s of input.settingsFiles ?? []) {
+        const { obj, findings: jf } = lintJson(s.file, s.raw);
+        findings.push(...jf, ...lintSettingsHooks(s.file, obj));
+    }
+    if (input.mcpConfig) {
+        const { obj, findings: jf } = lintJson(input.mcpConfig.file, input.mcpConfig.raw);
+        findings.push(...jf, ...lintMcpConfig(input.mcpConfig.file, obj));
+    }
+    findings.push(...lintLegacyLayout(input.commandsRoot ?? [], input.skills ?? []));
+    return {
+        findings,
+        errors: findings.filter((x) => x.severity === 'error').length,
+        warnings: findings.filter((x) => x.severity === 'warn').length,
+    };
+}
+//# sourceMappingURL=lint.js.map

package/dist/src/config-lint/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../src/config-lint/lint.ts"],"names":[],"mappings":"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"}

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
+ * .swarmdo/sessions/*.json files keep working unchanged.
+ */
+/** ASCII "RFE1" — Swarmdo 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 SWARMDO_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,yDAAyD;AACzD,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
+ * .swarmdo/sessions/*.json files keep working unchanged.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual, } from 'node:crypto';
+// ── Constants ────────────────────────────────────────────────────────────────
+/** ASCII "RFE1" — Swarmdo 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 = 'SWARMDO_ENCRYPT_AT_REST';
+const ENV_KEY_VAR = 'SWARMDO_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 SWARMDO_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 Swarmdo-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":"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"}

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 (SWARMDO_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"}