memoir-cli 3.12.0 → 3.14.0

package/src/providers/index.js

@@ -4,6 +4,8 @@ import os from 'os';
 import chalk from 'chalk';
 import { execFileSync } from 'child_process';
 import { appendEvent } from '../events/log.js';
+import { listSafeFiles, readSafeFile, writeSafeFile, restoreFileSet } from '../security/files.js';
+import { withSessionLock } from '../session/lock.js';
 
 function sanitizeUrl(url) {
   // Reject URLs with shell metacharacters
@@ -13,99 +15,228 @@ function sanitizeUrl(url) {
   return url;
 }
 
-export async function syncToLocal(config, stagingDir, spinner) {
-  const destDir = config.localPath;
-  if (!destDir) throw new Error('Local path is not configured.');
+export async function withLocalBackupLock(config, fn) {
+  const dest = path.resolve(config.localPath.replace(/^~/, os.homedir()));
+  return withSessionLock(dest + '.memoir-lock', fn, { maxWaitMs: 5000 });
+}
 
-  const resolvedDest = destDir.replace(/^~/, os.homedir());
+export async function syncToLocal(config, stagingDir, spinner, options = {}) {
+  if (!config.localPath) throw new Error('Local path is not configured.');
+  const dest = path.resolve(config.localPath.replace(/^~/, os.homedir()));
+  if (dest === path.parse(dest).root || dest === path.resolve(os.homedir()) || path.resolve(stagingDir).startsWith(dest + path.sep)) throw new Error('Choose a dedicated backup directory');
+  const sync = async () => {
+    const stat = await fs.lstat(dest).catch(err => { if (err.code !== 'ENOENT') throw err; return null; });
+    if (stat?.isSymbolicLink()) throw new Error('Backup destination must not be a symlink');
+    const encrypted = await fs.pathExists(path.join(stagingDir, 'manifest.enc'));
+    const exists = await fs.pathExists(dest);
+    const wasEncrypted = exists && await fs.pathExists(path.join(dest, 'manifest.enc'));
+    if (encrypted) {
+      if (exists && !wasEncrypted && (await fs.readdir(dest)).length && !options.verifiedReplacement) throw new Error('Use memoir push to verify and migrate this plaintext backup before replacing it.');
+      const parent = path.dirname(dest);
+      await fs.ensureDir(parent);
+      const next = await fs.mkdtemp(path.join(parent, '.memoir-sync-'));
+      const old = next + '-previous';
+      try {
+        await listSafeFiles(stagingDir);
+        await fs.copy(stagingDir, next);
+        if (exists) await fs.rename(dest, old);
+        try { await fs.rename(next, dest); }
+        catch (err) { if (exists) await fs.rename(old, dest); throw err; }
+        if (exists) await fs.remove(old);
+      } finally { await fs.remove(next).catch(() => {}); }
+    } else {
+      if (wasEncrypted) throw new Error('Cannot append plaintext to an encrypted backup. Use memoir push with encryption enabled.');
+      const files = [];
+      for (const rel of await listSafeFiles(stagingDir)) files.push({ path: rel, content: await readSafeFile(stagingDir, rel) });
+      await restoreFileSet(dest, files);
+    }
+  };
+  if (options.lockHeld) await sync();
+  else await withLocalBackupLock(config, sync);
+  spinner.succeed(chalk.green('Sync complete! ') + chalk.gray('(Saved to ' + dest + ')'));
+  await appendEvent('sync_pushed', { provider: 'local' });
+}
 
-  spinner.text = `Syncing files to local directory: ${chalk.cyan(resolvedDest)}`;
-  await fs.ensureDir(resolvedDest);
+// ── Git sync ─────────────────────────────────────────────────────
+//
+// One cheap clone per push. `--depth 1 --filter=blob:none --no-checkout`
+// fetches commits and trees only — no file contents, no working tree. The
+// remote of the author's own store is 720MB with ~40MB of workspace bundles
+// at HEAD; the old full shallow clone, done TWICE per push (the merge peek in
+// push.js and then this function), pulled all of it through on every Stop
+// hook and a quarter of pushes died on the 60s timeout (183 sync_failed in
+// 15 days, none with a reason). Blobs are now fetched on demand only for the
+// files a caller actually reads (`git checkout HEAD -- session.json`).
+// Remotes that don't support filters (plain file:// paths, old hosts) print
+// a warning and fall back to a normal shallow clone — never worse than before.
+//
+// Mirror semantics are unchanged and come for free: after a --no-checkout
+// clone the index is empty and every remote file is a staged deletion until
+// something re-adds it, so `copy staging → git add -A` yields exactly
+// "staging + the files the caller asked to preserve".
+
+export const CLONE_TIMEOUT_MS = 60000;
+const GIT_QUIET = ['ignore', 'ignore', 'pipe']; // stderr kept for classifyGitError
+
+export function cloneForSync(repoUrl, dir, { timeout = CLONE_TIMEOUT_MS } = {}) {
+  execFileSync('git', ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', repoUrl, '.'], {
+    cwd: dir, stdio: GIT_QUIET, timeout,
+  });
+  // Memoir writes main; read that same branch even when remote HEAD is master.
+  const main = execFileSync('git', ['ls-remote', '--heads', 'origin', 'refs/heads/main'], {
+    cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout,
+  }).trim();
+  if (main) {
+    execFileSync('git', ['fetch', '--depth', '1', 'origin', 'refs/heads/main'], { cwd: dir, stdio: GIT_QUIET, timeout });
+    execFileSync('git', ['update-ref', 'refs/heads/main', 'FETCH_HEAD'], { cwd: dir, stdio: GIT_QUIET, timeout });
+    execFileSync('git', ['symbolic-ref', 'HEAD', 'refs/heads/main'], { cwd: dir, stdio: GIT_QUIET, timeout });
+  }
+}
 
-  await fs.copy(stagingDir, resolvedDest);
+// Does the remote HEAD carry `file`? Reads the tree only — no blob fetch.
+export function remoteHasFile(dir, file) {
+  try {
+    const out = execFileSync('git', ['ls-tree', '--name-only', 'HEAD', '--', file], {
+      cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000,
+    });
+    return out.trim().length > 0;
+  } catch {
+    return false; // unborn HEAD (empty remote) or not a repo
+  }
+}
 
-  // Prune orphaned encrypted blobs. Each encrypted push derives a fresh salt
-  // and therefore fresh HMAC filenames, so without this every push leaves the
-  // previous push's data/*.enc behind forever and localPath grows without
-  // bound. Only runs for a full encrypted sync (manifest.enc present in what
-  // we just wrote) — `memoir snapshot` also calls syncToLocal with a staging
-  // dir of a single handoff file, and blanket-emptying the destination there
-  // would delete the user's backup.
+// Materialise one remote file into the working tree (fetches its blob).
+export function checkoutFromRemote(dir, file) {
   try {
-    const stagedManifest = path.join(stagingDir, 'manifest.enc');
-    const destData = path.join(resolvedDest, 'data');
-    if (await fs.pathExists(stagedManifest) && await fs.pathExists(destData)) {
-      const keep = new Set(await fs.readdir(path.join(stagingDir, 'data')).catch(() => []));
-      for (const f of await fs.readdir(destData)) {
-        if (!keep.has(f)) await fs.remove(path.join(destData, f)).catch(() => {});
-      }
-    }
+    execFileSync('git', ['checkout', 'HEAD', '--', file], { cwd: dir, stdio: 'ignore', timeout: 30000 });
+    return true;
   } catch {
-    // Pruning is housekeeping — never fail a completed backup over it.
+    return false;
   }
+}
 
-  spinner.succeed(chalk.green('Sync complete! ') + chalk.gray(`(Saved to ${resolvedDest})`));
-  await appendEvent('sync_pushed', { provider: 'local' });
+// A short enum for the event log — never the raw stderr (it can carry the
+// repo URL, a username, a local path). Enough to tell "the network is down"
+// from "two pushes raced" from "the token expired" when reading events.jsonl.
+export function classifyGitError(err) {
+  const text = `${err?.message || ''}\n${err?.stderr || ''}`.toLowerCase();
+  if (err?.code === 'ETIMEDOUT' || err?.signal === 'SIGTERM' || /timed? ?out/.test(text)) return 'timeout';
+  if (/non-fast-forward|fetch first|\[rejected\]/.test(text)) return 'non_fast_forward';
+  // Match HTTP diagnostics, not a coincidental 403 in a path or timestamp.
+  if (/authentication failed|could not read username|could not read password|permission denied|terminal prompts disabled|invalid credentials|requested url returned error: 403\b|http(?:\/[\d.]+)?(?: error| status(?: code)?)?[: ]+403\b/.test(text)) return 'auth';
+  if (/could not resolve host|unable to access|connection (?:refused|reset|timed)|network is unreachable|early eof|remote end hung up/.test(text)) return 'network';
+  if (/repository not found|does not appear to be a git repository|does not exist|no such file/.test(text)) return 'not_found';
+  if (/invalid characters/.test(text)) return 'bad_url';
+  return 'unknown';
 }
 
+/**
+ * Push `stagingDir` to the git remote as the new HEAD:main.
+ *
+ * options:
+ *   cloneDir  — a directory already prepared by cloneForSync (push.js's merge
+ *               peek). Reused instead of cloning again; removed when done.
+ *   preserve  — remote files to keep even though staging lacks them
+ *               (an unreadable session.json the caller declined to overwrite).
+ *   additive  — overlay staging onto the remote tree instead of mirroring it
+ *               (`memoir snapshot` uploads ONE handoff file; mirroring would
+ *               have wiped every other file in the backup).
+ */
 export async function syncToGit(config, stagingDir, spinner, options = {}) {
   const repoUrl = sanitizeUrl(config.gitRepo);
   if (!repoUrl) throw new Error('Git repository is not configured.');
 
   spinner.text = `Authenticating and syncing with Git remote: ${chalk.cyan(repoUrl)}`;
 
-  const gitDir = path.join(os.tmpdir(), `memoir-git-${Date.now()}`);
+  const reuse = Boolean(options.cloneDir) && await fs.pathExists(path.join(options.cloneDir, '.git'));
+  const gitDir = reuse ? options.cloneDir : path.join(os.tmpdir(), `memoir-git-${Date.now()}`);
   await fs.ensureDir(gitDir);
+  const started = Date.now();
 
   try {
-    try {
-      execFileSync('git', ['clone', '--depth', '1', repoUrl, '.'], { cwd: gitDir, stdio: 'ignore', timeout: 60000 });
-      const preserve = new Set(options.preserve || []);
-      const files = await fs.readdir(gitDir);
-      for (const f of files) {
-        // preserve: files the caller knows exist remotely but could not
-        // merge (unreadable session.json) — deleting them here would be
-        // the mirror-clobber the push guard just declined to commit.
-        if (f !== '.git' && !preserve.has(f)) await fs.remove(path.join(gitDir, f));
+    if (!reuse) {
+      try {
+        cloneForSync(repoUrl, gitDir);
+      } catch (err) {
+        // Cloning an EMPTY remote succeeds (git warns and continues), so a
+        // failure here is a real one. Unreachable / unauthorised / timed out
+        // must surface as such — the old unconditional `git init` fallback
+        // turned every one of them into a later, misleading
+        // "non-fast-forward" or "credentials" failure. Only a not_found /
+        // unknown failure (a host that refuses to clone an empty repo) still
+        // falls back to init so a first push can create the history.
+        const reason = classifyGitError(err);
+        if (reason === 'timeout' || reason === 'auth' || reason === 'network') throw err;
+        execFileSync('git', ['init'], { cwd: gitDir, stdio: 'ignore' });
+        execFileSync('git', ['branch', '-m', 'main'], { cwd: gitDir, stdio: 'ignore' });
       }
-    } catch {
-      execFileSync('git', ['init'], { cwd: gitDir, stdio: 'ignore' });
-      execFileSync('git', ['branch', '-m', 'main'], { cwd: gitDir, stdio: 'ignore' });
     }
 
-    await fs.copy(stagingDir, gitDir);
+    // Files the caller wants kept although staging lacks them: check them
+    // out (one blob each) so `git add -A` below sees them in the tree.
+    const preserved = [];
+    for (const p of options.preserve || []) {
+      if (!checkoutFromRemote(gitDir, p)) throw new Error('Could not preserve remote file');
+      preserved.push({ path: p, content: await readSafeFile(gitDir, p) });
+    }
+    if (!options.additive) {
+      // The merge peek may have materialized plaintext. A complete encrypted
+      // replacement must remove it from the current tree before adding blobs.
+      for (const entry of await fs.readdir(gitDir)) {
+        if (entry !== '.git') await fs.remove(path.join(gitDir, entry));
+      }
+    }
 
-    execFileSync('git', ['add', '-A'], { cwd: gitDir, stdio: 'ignore', timeout: 30000 });
+
+    if (options.additive) {
+      // Populate the index from HEAD (trees only, no blobs) so everything
+      // the remote already has stays in the commit; then add ONLY what
+      // staging brought. `git add -A` over an empty working tree would
+      // stage every other remote file as deleted.
+      try { execFileSync('git', ['read-tree', 'HEAD'], { cwd: gitDir, stdio: 'ignore', timeout: 30000 }); } catch {}
+    }
+
+    const stagedFiles = await listSafeFiles(stagingDir);
+    await fs.copy(stagingDir, gitDir);
+    for (const entry of preserved) await writeSafeFile(gitDir, entry.path, entry.content);
+
+    if (options.additive) {
+      if (stagedFiles.length) execFileSync('git', ['add', '--pathspec-from-file=-', '--pathspec-file-nul'], {
+        cwd: gitDir, input: Buffer.from(stagedFiles.join('\0') + '\0'), stdio: ['pipe', 'ignore', 'pipe'], timeout: 30000,
+      });
+    } else {
+      execFileSync('git', ['add', '-A'], { cwd: gitDir, stdio: 'ignore', timeout: 30000 });
+    }
     execFileSync('git', ['config', 'user.name', 'memoir'], { cwd: gitDir, stdio: 'ignore', timeout: 5000 });
     execFileSync('git', ['config', 'user.email', 'bot@memoir.dev'], { cwd: gitDir, stdio: 'ignore', timeout: 5000 });
 
     const timestamp = new Date().toISOString().split('T')[0];
-    try {
-      execFileSync('git', ['commit', '-m', `memoir backup ${timestamp}`], { cwd: gitDir, stdio: 'ignore', timeout: 30000 });
-    } catch {
+    const changed = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: gitDir, encoding: 'utf8', timeout: 30000 });
+    if (!changed.trim()) {
       spinner.succeed(chalk.green('Already up to date! ') + chalk.gray('No changes to push.'));
       return;
     }
+    execFileSync('git', ['commit', '-q', '-m', 'memoir backup ' + timestamp], { cwd: gitDir, stdio: GIT_QUIET, timeout: 30000 });
 
     spinner.text = `Pushing data to ${chalk.cyan(repoUrl)}...`;
     // HEAD:main pushes whatever branch the clone checked out (a master-
     // default remote used to make `push main` fail silently under autopush
     // with a misleading credentials error, while doctor reported green).
-    execFileSync('git', ['push', repoUrl, 'HEAD:main'], { cwd: gitDir, stdio: 'ignore', timeout: 120000 });
+    execFileSync('git', ['push', '-q', repoUrl, 'HEAD:main'], { cwd: gitDir, stdio: GIT_QUIET, timeout: 120000 });
 
     spinner.succeed(chalk.green('Sync complete! ') + chalk.gray('(Uploaded securely to GitHub)'));
-    await appendEvent('sync_pushed', { provider: 'git' });
+    await appendEvent('sync_pushed', { provider: 'git', ms: Date.now() - started, reused_clone: reuse });
   } catch (err) {
     // Makes a silently-swallowed push failure (a non-fast-forward rejection
     // from two racing pushes, a network error, bad credentials, etc.)
     // visible in the event log instead of vanishing into the detached
-    // autopush child's ignored stdio. Deliberately no raw error text/repo
-    // URL in the payload — those can contain usernames/paths; type+provider
-    // is enough to know "pushes are failing" without leaking anything.
-    await appendEvent('sync_failed', { provider: 'git' });
+    // autopush child's ignored stdio. `reason` is a short enum, never the
+    // raw error text/repo URL — those can contain usernames/paths.
+    const reason = classifyGitError(err);
+    await appendEvent('sync_failed', { provider: 'git', reason, ms: Date.now() - started });
     if (err.message.includes('invalid characters')) throw err;
-    throw new Error('Failed to push to git repository. Ensure your credentials are configured and the repository exists.');
+    throw new Error(`Failed to push to git repository (${reason}). Ensure your credentials are configured and the repository exists.`);
   } finally {
-    await fs.remove(gitDir);
+    await fs.remove(gitDir).catch(() => {});
   }
 }

package/src/providers/restore.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { execFileSync } from 'child_process';
+import { cloneForSync, checkoutFromRemote } from './index.js';
 import { restoreMemories } from '../adapters/restore.js';
 
 export async function fetchFromLocal(config, stagingDir, spinner, onlyFilter = null, autoYes = false) {
@@ -18,6 +19,7 @@ export async function fetchFromLocal(config, stagingDir, spinner, onlyFilter = n
   spinner.text = `Fetching data from local directory: ${chalk.cyan(resolvedSource)}`;
   await fs.copy(resolvedSource, stagingDir);
 
+  if (await fs.pathExists(path.join(stagingDir, 'manifest.enc'))) return false;
   return await restoreMemories(stagingDir, spinner, onlyFilter, autoYes);
 }
 
@@ -28,10 +30,12 @@ export async function fetchFromGit(config, stagingDir, spinner, onlyFilter = nul
   spinner.text = `Cloning memory from Git remote: ${chalk.cyan(repoUrl)}`;
 
   try {
-    execFileSync('git', ['clone', '--depth', '1', repoUrl, '.'], { cwd: stagingDir, stdio: 'ignore' });
+    cloneForSync(repoUrl, stagingDir);
+    if (!checkoutFromRemote(stagingDir, '.')) throw new Error('Could not read backup main branch');
   } catch (err) {
     throw new Error('Failed to pull from git repository. Ensure your SSH keys are configured and the repository is accessible.');
   }
 
+  if (await fs.pathExists(path.join(stagingDir, 'manifest.enc'))) return false;
   return await restoreMemories(stagingDir, spinner, onlyFilter, autoYes);
 }

package/src/security/encryption.js

@@ -2,6 +2,7 @@ import crypto from 'crypto';
 import { promisify } from 'util';
 import fs from 'fs-extra';
 import path from 'path';
+import { listSafeFiles, readSafeFile, restoreFileSet, relativeFile, MAX_SNAPSHOT_FILES, MAX_SNAPSHOT_BYTES, MAX_FILE_BYTES } from './files.js';
 
 const scryptAsync = promisify(crypto.scrypt);
 
@@ -50,6 +51,7 @@ export async function encryptBuffer(plaintext, passphrase) {
  * Decrypt a buffer. Throws on wrong passphrase or tampered data.
  */
 export async function decryptBuffer(data, passphrase) {
+  if (!Buffer.isBuffer(data) || data.length < 68) throw new Error('Truncated encrypted file');
   const magic = data.subarray(0, 8);
   if (!magic.equals(MAGIC)) {
     throw new Error('Not a memoir-encrypted file (bad header)');
@@ -88,23 +90,16 @@ export async function encryptDirectory(srcDir, destDir, passphrase, spinner = nu
   // Phase 2: Index files
   if (spinner) spinner.text = 'Indexing files...';
   const fileList = [];
-  async function index(dir, relBase = '') {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name);
-      const relPath = path.join(relBase, entry.name);
-      if (entry.isDirectory()) {
-        await index(fullPath, relPath);
-      } else {
-        const stat = await fs.stat(fullPath);
-        fileList.push({ fullPath, relPath, size: stat.size });
-      }
-    }
+  for (const relPath of await listSafeFiles(srcDir)) {
+    const fullPath = path.join(srcDir, relPath);
+    const stat = await fs.stat(fullPath);
+    if (stat.size > MAX_FILE_BYTES) throw new Error('Snapshot file size limit exceeded');
+    fileList.push({ fullPath, relPath, size: stat.size });
   }
-  await index(srcDir);
 
   const totalFiles = fileList.length;
   const totalBytes = fileList.reduce((sum, f) => sum + f.size, 0);
+  if (totalBytes > MAX_SNAPSHOT_BYTES) throw new Error('Snapshot size limit exceeded');
 
   // Phase 3: Encrypt files
   const manifest = {};
@@ -118,9 +113,10 @@ export async function encryptDirectory(srcDir, destDir, passphrase, spinner = nu
       .digest('hex')
       .slice(0, 24);
 
-    const plaintext = await fs.readFile(fullPath);
+    const plaintext = await readSafeFile(srcDir, relPath);
     const iv = crypto.randomBytes(IV_LENGTH);
     const cipher = crypto.createCipheriv(ALGORITHM, key, iv, { authTagLength: TAG_LENGTH });
+    cipher.setAAD(Buffer.from(relPath, 'utf8'));
     const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const tag = cipher.getAuthTag();
 
@@ -143,7 +139,7 @@ export async function encryptDirectory(srcDir, destDir, passphrase, spinner = nu
 
   // Phase 4: Encrypt manifest
   if (spinner) spinner.text = 'Encrypting file manifest...';
-  const manifestJson = Buffer.from(JSON.stringify(manifest));
+  const manifestJson = Buffer.from(JSON.stringify({ version: 2, files: manifest }));
   const manifestEncrypted = await encryptBuffer(manifestJson, passphrase);
   await fs.writeFile(path.join(destDir, 'manifest.enc'), manifestEncrypted);
 
@@ -166,53 +162,31 @@ function formatBytes(bytes) {
  * Decrypt an encrypted directory back to plaintext.
  */
 export async function decryptDirectory(encDir, destDir, passphrase, spinner = null) {
-  const startTime = Date.now();
-
-  // Phase 1: Decrypt manifest
-  if (spinner) spinner.text = 'Decrypting file manifest...';
-  const manifestData = await fs.readFile(path.join(encDir, 'manifest.enc'));
-  const manifestJson = await decryptBuffer(manifestData, passphrase);
-  const manifest = JSON.parse(manifestJson.toString('utf8'));
-
-  // Phase 2: Derive key
-  if (spinner) spinner.text = 'Deriving decryption key (scrypt)...';
-  const salt = await fs.readFile(path.join(encDir, 'salt'));
+  const manifestData = await readSafeFile(encDir, 'manifest.enc');
+  const decoded = JSON.parse((await decryptBuffer(manifestData, passphrase)).toString('utf8'));
+  const version = decoded.version === 2 ? 2 : 1;
+  const manifest = version === 2 ? decoded.files : decoded;
+  if (!manifest || Array.isArray(manifest) || typeof manifest !== 'object' || Object.keys(manifest).length > MAX_SNAPSHOT_FILES) throw new Error('Invalid encrypted manifest');
+  const salt = await readSafeFile(encDir, 'salt');
+  if (salt.length !== SALT_LENGTH) throw new Error('Invalid encryption salt');
   const { key } = await deriveKey(passphrase, salt);
-
-  const dataDir = path.join(encDir, 'data');
-  const totalFiles = Object.keys(manifest).length;
-  let count = 0;
-  let bytesProcessed = 0;
-
-  // Phase 3: Decrypt files
-  for (const [hashedName, relPath] of Object.entries(manifest)) {
-    const encFilePath = path.join(dataDir, `${hashedName}.enc`);
-    if (!(await fs.pathExists(encFilePath))) continue;
-
-    const data = await fs.readFile(encFilePath);
-    const iv = data.subarray(0, IV_LENGTH);
-    const tag = data.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
-    const ciphertext = data.subarray(IV_LENGTH + TAG_LENGTH);
-
-    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv, { authTagLength: TAG_LENGTH });
-    decipher.setAuthTag(tag);
-    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-
-    const outPath = path.join(destDir, relPath);
-    await fs.ensureDir(path.dirname(outPath));
-    await fs.writeFile(outPath, decrypted);
-    count++;
-    bytesProcessed += decrypted.length;
-
-    if (spinner) {
-      const pct = Math.round((count / totalFiles) * 100);
-      spinner.text = `Decrypting ${count}/${totalFiles} files — ${formatBytes(bytesProcessed)} [${pct}%]`;
-    }
+  const files = [];
+  let bytes = 0;
+  for (const [hashedName, storedPath] of Object.entries(manifest)) {
+    if (!/^[a-f0-9]{24}$/.test(hashedName)) throw new Error('Invalid encrypted blob name');
+    const relPath = relativeFile(storedPath);
+    const data = await readSafeFile(encDir, 'data/' + hashedName + '.enc', { maxBytes: MAX_FILE_BYTES + IV_LENGTH + TAG_LENGTH });
+    if (data.length < IV_LENGTH + TAG_LENGTH) throw new Error('Truncated encrypted blob');
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, data.subarray(0, IV_LENGTH), { authTagLength: TAG_LENGTH });
+    if (version === 2) decipher.setAAD(Buffer.from(storedPath, 'utf8'));
+    decipher.setAuthTag(data.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH));
+    const content = Buffer.concat([decipher.update(data.subarray(IV_LENGTH + TAG_LENGTH)), decipher.final()]);
+    bytes += content.length;
+    if (bytes > MAX_SNAPSHOT_BYTES) throw new Error('Snapshot size limit exceeded');
+    files.push({ path: relPath, content });
   }
-
-  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-  if (spinner) spinner.text = `Decrypted ${count} files (${formatBytes(bytesProcessed)}) in ${elapsed}s`;
-
+  const count = await restoreFileSet(destDir, files);
+  if (spinner) spinner.text = 'Decrypted and verified ' + count + ' files (' + formatBytes(bytes) + ')';
   return count;
 }
 

package/src/security/files.js

@@ -0,0 +1,155 @@
+import fs from 'fs-extra';
+import path from 'path';
+import crypto from 'crypto';
+import { constants } from 'fs';
+
+export const MAX_FILE_BYTES = 16 * 1024 * 1024;
+export const MAX_SNAPSHOT_BYTES = 256 * 1024 * 1024;
+export const MAX_SNAPSHOT_FILES = 50_000;
+
+// Validate both Windows and POSIX paths regardless of the restoring OS.
+export function relativeFile(value) {
+  if (typeof value !== 'string' || !value || /[\x00-\x1f:]/.test(value) || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)) throw new Error('Invalid relative memory path');
+  const parts = value.replace(/\\/g, '/').split('/');
+  if (parts.some(p => !p || p === '.' || p === '..' || p.toLowerCase() === '.git' || /[. ]$/.test(p) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i.test(p))) throw new Error('Invalid relative memory path');
+  return parts.join('/');
+}
+
+export function memoryFilename(value) {
+  const name = relativeFile(value.endsWith('.md') ? value : value + '.md');
+  if (name.includes('/')) throw new Error('Memory filename must be a bare .md name');
+  return name;
+}
+
+// Platform root aliases such as /tmp are supported; child symlinks are not.
+export async function safePath(root, relative, { createParents = false } = {}) {
+  const rel = relativeFile(relative);
+  if (createParents) await fs.ensureDir(root, { mode: 0o700 });
+  const base = await fs.realpath(root);
+  const parts = rel.split('/');
+  let current = base;
+  for (let i = 0; i < parts.length; i++) {
+    current = path.join(current, parts[i]);
+    let st;
+    try { st = await fs.lstat(current); }
+    catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      if (createParents && i < parts.length - 1) {
+        await fs.mkdir(current, { mode: 0o700 }).catch(err => { if (err.code !== 'EEXIST') throw err; });
+        st = await fs.lstat(current);
+      }
+    }
+    if (st?.isSymbolicLink()) throw new Error('Symlinks are not allowed in memory paths');
+    if (st && i < parts.length - 1 && !st.isDirectory()) throw new Error('Memory parent is not a directory');
+    if (st && i === parts.length - 1 && !st.isFile()) throw new Error('Memory path is not a regular file');
+  }
+  return current;
+}
+
+export async function readSafeFile(root, relative, { maxBytes = MAX_FILE_BYTES } = {}) {
+  const full = await safePath(root, relative);
+  const fd = await fs.open(full, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const st = await fs.fstat(fd);
+    if (!st.isFile() || st.size > maxBytes) throw new Error('Memory file is not regular or exceeds the size limit');
+    await safePath(root, relative);
+    return await fs.readFile(fd);
+  } finally { await fs.close(fd); }
+}
+
+// One inventory refresh may inspect thousands of files sharing the same
+// parents. Validate each parent once within this short-lived context, while
+// always lstat'ing the leaf. This is a metadata optimization only: content
+// reads still use readSafeFile, and search revalidates returned sources with
+// safePath. Never retain this context across queries or use it for writes.
+export async function createReadInventory(root) {
+  const base = await fs.realpath(root);
+  const parents = new Map();
+  const parent = dir => {
+    if (!parents.has(dir)) parents.set(dir, (async () => {
+      if (dir !== base) await parent(path.dirname(dir));
+      const st = await fs.lstat(dir);
+      if (!st.isDirectory() || st.isSymbolicLink()) throw new Error('Memory parent is not a regular directory');
+    })());
+    return parents.get(dir);
+  };
+  return {
+    root: base,
+    async stat(relative) {
+      const rel = relativeFile(relative);
+      const full = path.join(base, rel);
+      await parent(path.dirname(full));
+      const stat = await fs.lstat(full);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_FILE_BYTES) throw new Error('Memory file is not regular or exceeds the size limit');
+      return { full, stat, relative: rel };
+    },
+  };
+}
+
+export async function writeSafeFile(root, relative, content) {
+  const full = await safePath(root, relative, { createParents: true });
+  const tmp = path.join(path.dirname(full), '.memoir-write-' + crypto.randomUUID());
+  try {
+    await fs.writeFile(tmp, content, { flag: 'wx', mode: 0o600 });
+    await safePath(root, relative);
+    await fs.rename(tmp, full);
+  } finally { await fs.remove(tmp).catch(() => {}); }
+}
+
+export async function listSafeFiles(root) {
+  const result = [];
+  const base = await fs.realpath(root);
+  async function walk(dir, prefix = '') {
+    for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+      const rel = relativeFile(prefix + entry.name);
+      if (entry.isSymbolicLink()) throw new Error('Snapshot contains a symlink: ' + rel);
+      if (entry.isDirectory()) await walk(path.join(dir, entry.name), rel + '/');
+      else if (entry.isFile()) result.push(rel);
+      else throw new Error('Snapshot contains a non-regular file: ' + rel);
+      if (result.length > MAX_SNAPSHOT_FILES) throw new Error('Snapshot file limit exceeded');
+    }
+  }
+  await walk(base);
+  return result;
+}
+
+// Validate everything, build a replacement beside the destination, then swap.
+// Corrupt/incomplete snapshots cannot partially overwrite the prior destination.
+export async function restoreFileSet(dest, entries) {
+  if (!Array.isArray(entries) || entries.length > MAX_SNAPSHOT_FILES) throw new Error('Invalid snapshot file list');
+  const seen = new Set();
+  let bytes = 0;
+  for (const entry of entries) {
+    entry.path = relativeFile(entry.path);
+    const key = entry.path.normalize('NFC').toLowerCase();
+    if (seen.has(key)) throw new Error('Duplicate snapshot path');
+    seen.add(key);
+    if (!Buffer.isBuffer(entry.content) || entry.content.length > MAX_FILE_BYTES) throw new Error('Snapshot file limit exceeded');
+    bytes += entry.content.length;
+    if (bytes > MAX_SNAPSHOT_BYTES) throw new Error('Snapshot size limit exceeded');
+  }
+  for (const key of seen) {
+    const parts = key.split('/');
+    while (parts.length > 1) {
+      parts.pop();
+      if (seen.has(parts.join('/'))) throw new Error('Conflicting snapshot paths');
+    }
+  }
+  const absolute = path.resolve(dest);
+  await fs.ensureDir(path.dirname(absolute));
+  const prior = await fs.lstat(absolute).catch(err => { if (err.code !== 'ENOENT') throw err; return null; });
+  if (prior && (!prior.isDirectory() || prior.isSymbolicLink())) throw new Error('Restore destination must be a directory, not a symlink');
+  if (prior) for (const entry of entries) await safePath(absolute, entry.path);
+  const staged = await fs.mkdtemp(path.join(path.dirname(absolute), '.memoir-restore-'));
+  const previous = staged + '-previous';
+  let moved = false;
+  try {
+    if (prior) await fs.copy(absolute, staged, { dereference: false });
+    for (const entry of entries) await writeSafeFile(staged, entry.path, entry.content);
+    if (prior) { await fs.rename(absolute, previous); moved = true; }
+    try { await fs.rename(staged, absolute); }
+    catch (err) { if (moved) await fs.rename(previous, absolute); throw err; }
+    if (moved) await fs.remove(previous);
+  } finally { await fs.remove(staged).catch(() => {}); }
+  return entries.length;
+}