residoo 0.1.0

package/src/prompt.js

@@ -0,0 +1,30 @@
+"use strict";
+
+const readline = require("readline");
+const { Writable } = require("stream");
+
+/**
+ * Hidden passphrase prompt — echoes nothing while typing. Falls back to the
+ * RESIDOO_PASSPHRASE env var for scripted/CI use, and refuses to prompt when
+ * stdin isn't a TTY (a scanner hanging silently in a pipeline waiting for
+ * input nobody can see is worse than failing with instructions).
+ */
+function promptHidden(question) {
+  return new Promise((resolve, reject) => {
+    if (process.env.RESIDOO_PASSPHRASE) { resolve(process.env.RESIDOO_PASSPHRASE); return; }
+    if (!process.stdin.isTTY) {
+      reject(new Error("No TTY for a passphrase prompt. Set RESIDOO_PASSPHRASE in the environment for non-interactive use."));
+      return;
+    }
+    const muted = new Writable({ write(_chunk, _enc, cb) { cb(); } });
+    const rl = readline.createInterface({ input: process.stdin, output: muted, terminal: true });
+    process.stderr.write(question);
+    rl.question("", (answer) => {
+      rl.close();
+      process.stderr.write("\n");
+      resolve(answer);
+    });
+  });
+}
+
+module.exports = { promptHidden };

package/src/report.js

@@ -0,0 +1,123 @@
+"use strict";
+
+const path = require("path");
+
+// Minimal raw ANSI — no chalk, no deps. A security tool asking you to trust
+// a pile of third-party packages before it's even scanned anything is a bad
+// first impression; residoo ships with zero runtime dependencies.
+const c = {
+  reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+  red: "\x1b[31m", yellow: "\x1b[33m", green: "\x1b[32m", cyan: "\x1b[36m",
+};
+// Read fresh on every call, not once at require() time — a module-level
+// const would freeze whatever the environment was at require() time, before
+// cli.js has even parsed argv. `forceNoColor` is how cli.js's --no-color
+// flag actually reaches this function: as an explicit per-call argument, not
+// by mutating process.env.NO_COLOR. `main()` is an exported function, not
+// only a one-shot CLI entrypoint — a mutated env var would leak into any
+// later call in the same process (a test runner, a wrapper CLI reusing it)
+// and silently disable color for calls that never asked for that.
+function supportsColor(forceNoColor) {
+  return !forceNoColor && process.stdout.isTTY && process.env.NO_COLOR === undefined;
+}
+function makePaint(forceNoColor) {
+  return (code, s) => (supportsColor(forceNoColor) ? `${code}${s}${c.reset}` : s);
+}
+
+function ageDays(mtimeMs) {
+  return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86400000));
+}
+
+function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false } = {}) {
+  const paint = makePaint(noColor);
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+
+  const suppressedNote = suppressedCount > 0
+    ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text — see --include-suppressed)`)
+    : "";
+  // Surfaced, not silent: a file that couldn't be (fully) read was not fully
+  // scanned, and a report must not read as "checked and found nothing" for
+  // it. `unreadableFiles` holds { file: <basename>, reason } — basenames
+  // only, deliberately: the full path can itself carry a username or a
+  // project-name-derived directory slug, which is exactly the kind of thing
+  // every other line in this report is careful to redact down from.
+  const unreadableNote = unreadableFiles.length > 0
+    ? paint(c.yellow, `⚠  ${unreadableFiles.length} file(s) not fully scanned — see --json for which and why.`)
+    : null;
+
+  if (findings.length === 0) {
+    push(paint(c.green + c.bold, "✓ No exposed secrets found") +
+      ` — ${filesScanned} file${filesScanned === 1 ? "" : "s"} scanned across ${sourcesScanned.join(", ") || "no sources"}.` +
+      suppressedNote);
+    if (unreadableNote) push(unreadableNote);
+    return lines.join("\n");
+  }
+
+  // Group by rule for the headline counts.
+  const byRule = new Map();
+  for (const f of findings) {
+    if (!byRule.has(f.ruleId)) byRule.set(f.ruleId, { label: f.label, confidence: f.confidence, items: [] });
+    byRule.get(f.ruleId).items.push(f);
+  }
+  const byFile = new Map();
+  for (const f of findings) byFile.set(f.file, (byFile.get(f.file) || 0) + 1);
+  const oldest = findings.reduce((a, b) => (b.fileMTimeMs < a ? b.fileMTimeMs : a), Date.now());
+  const newest = findings.reduce((a, b) => (b.fileMTimeMs > a ? b.fileMTimeMs : a), 0);
+
+  push();
+  push(paint(c.red + c.bold, `⚠  ${findings.length} potential secret${findings.length === 1 ? "" : "s"} found`) +
+    ` across ${byFile.size} file${byFile.size === 1 ? "" : "s"}`);
+  push(paint(c.dim, `   ${filesScanned} files scanned (${(bytesScanned / 1024 / 1024).toFixed(1)} MB) · sources: ${sourcesScanned.join(", ")}`));
+  push(paint(c.dim, `   oldest match ~${ageDays(oldest)}d old · most recent ~${ageDays(newest)}d old`) + suppressedNote);
+  if (unreadableNote) push(unreadableNote);
+  push();
+
+  const sorted = [...byRule.entries()].sort((a, b) => b[1].items.length - a[1].items.length);
+  for (const [ruleId, { label, confidence, items }] of sorted) {
+    const tag = confidence === "high" ? paint(c.red, "high") : confidence === "medium" ? paint(c.yellow, "med ") : paint(c.dim, "low ");
+    const distinct = distinctCounts[ruleId];
+    const distinctNote = distinct && distinct !== items.length
+      ? paint(c.dim, `  (${distinct} distinct value${distinct === 1 ? "" : "s"}, re-exposed ${items.length - distinct}× across tool output)`)
+      : "";
+    push(`  ${paint(c.bold, String(items.length).padStart(4))}  [${tag}]  ${label}${distinctNote}`);
+  }
+
+  push();
+  push(paint(c.bold, "By file:"));
+  const fileRows = [...byFile.entries()].sort((a, b) => b[1] - a[1]).slice(0, 15);
+  for (const [file, count] of fileRows) {
+    push(`  ${String(count).padStart(4)}  ${paint(c.cyan, path.basename(file))}`);
+  }
+  if (byFile.size > fileRows.length) push(paint(c.dim, `  … and ${byFile.size - fileRows.length} more file(s)`));
+
+  push();
+  push(paint(c.dim, "Values are redacted in this report — first/last 4 characters only. Nothing scanned"));
+  push(paint(c.dim, "here left your machine; residoo makes no network calls. Run with --json for full detail."));
+
+  return lines.join("\n");
+}
+
+function renderJson(result) {
+  return JSON.stringify(
+    {
+      summary: {
+        findingCount: result.findings.length,
+        filesScanned: result.filesScanned,
+        filesWithFindings: new Set(result.findings.map((f) => f.file)).size,
+        sourcesScanned: result.sourcesScanned,
+        bytesScanned: result.bytesScanned,
+        suppressedCount: result.suppressedCount || 0,
+        unreadableFiles: result.unreadableFiles || [],
+      },
+      findings: result.findings.map((f) => ({
+        rule: f.ruleId, label: f.label, confidence: f.confidence,
+        source: f.source, file: f.relFile, line: f.line, preview: f.preview,
+      })),
+    },
+    null,
+    2
+  );
+}
+
+module.exports = { render, renderJson };

package/src/scan.js

@@ -0,0 +1,163 @@
+"use strict";
+
+const path = require("path");
+const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
+
+/**
+ * Text immediately before a match that strongly suggests "this is an example
+ * or a UI hint," not a real credential — verified against residoo's own
+ * first real run, which flagged HTML `placeholder="AKIA..."` attributes in
+ * an unrelated codebase's connector form (a UI hint showing the expected
+ * key SHAPE) as if they were leaked keys. Suppressed by default, reported
+ * separately rather than silently dropped, and re-includable with
+ * --include-suppressed — a scanner that hides its own uncertainty is worse
+ * than one that shows it.
+ */
+const SUPPRESS_CONTEXT_RE = /(placeholder|example|sample|dummy|<REDACTED>|xxxxxxxx|your[_-]?(api[_-]?)?key|EXAMPLE)/i;
+const CONTEXT_WINDOW = 40;
+
+/** Matches every finding's own `relFile` convention — never the full path. See SECURITY.md. */
+function safeName(file) { return path.basename(file); }
+
+/**
+ * Scan every transcript from every available source.
+ *
+ * Matches raw text lines directly rather than parsing each line as JSON and
+ * walking specific fields — transcript schemas vary by tool and change over
+ * time, but a leaked key looks the same either way. This is also exactly the
+ * method verified against a real, populated transcript directory while this
+ * tool was built, so it's a known-working default rather than a redesign.
+ *
+ * Returns { findings, filesScanned, sourcesScanned, bytesScanned,
+ * suppressedCount, distinctCounts, unreadableFiles }. `findings` never
+ * contains the raw matched secret — only a redacted preview — because a
+ * security tool's own report output is itself a place secrets could leak
+ * from (a screenshot, a copied terminal log, a CI artifact). Same reasoning
+ * is why `unreadableFiles` holds basenames only, not full paths — an
+ * absolute path can itself carry a username or a project name the rest of
+ * this report is careful never to print.
+ */
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null } = {}) {
+  const rules = includeNoisy ? PATTERNS.concat(NOISY_PATTERNS) : PATTERNS;
+  const findings = [];
+  let suppressedCount = 0;
+  let filesScanned = 0;
+  let bytesScanned = 0;
+  const sourcesScanned = [];
+  const unreadableFiles = [];
+  // Raw values live ONLY in this in-process Set, for counting how many
+  // DISTINCT secrets exist vs. how many times one got echoed back across
+  // tool calls (a token re-surfacing in every screenshot/read_page during a
+  // browser-testing run is one leak, not ten) — never written to a report,
+  // never leaves this function.
+  const distinctByRule = new Map();
+
+  const matchLine = (line, file, relFile, lineNo, mtimeMs) => {
+    for (const rule of rules) {
+      rule.re.lastIndex = 0; // rules are reused across files; reset global regex state
+      let m;
+      while ((m = rule.re.exec(line)) !== null) {
+        const before = line.slice(Math.max(0, m.index - CONTEXT_WINDOW), m.index);
+        const looksLikePlaceholder = SUPPRESS_CONTEXT_RE.test(before);
+        if (looksLikePlaceholder && !includeSuppressed) {
+          suppressedCount++;
+        } else {
+          if (!distinctByRule.has(rule.id)) distinctByRule.set(rule.id, new Set());
+          distinctByRule.get(rule.id).add(m[0]);
+          findings.push({
+            ruleId: rule.id,
+            label: rule.label,
+            confidence: looksLikePlaceholder ? "low" : rule.confidence,
+            suppressedReason: looksLikePlaceholder ? "placeholder-like context" : null,
+            source: relFile.source,
+            file, relFile: relFile.name,
+            line: lineNo,
+            preview: redact(m[0]),
+            fileMTimeMs: mtimeMs,
+          });
+        }
+        if (m.index === rule.re.lastIndex) rule.re.lastIndex++; // guard zero-width matches
+      }
+    }
+  };
+
+  for (const source of sources) {
+    let sourceScannedAnything = false;
+
+    for (const entry of source.files()) {
+      if (onProgress) onProgress({ source: source.id(), file: entry.file });
+
+      // files() itself can now report an entry it couldn't resolve at all —
+      // chiefly a dangling symlink. Surfaced the same way an unreadable file
+      // is: visibly, never silently dropped inside the walk.
+      if (entry.broken) {
+        unreadableFiles.push({ file: safeName(entry.file), reason: "could not be resolved" });
+        continue;
+      }
+      const { file, mtimeMs, sizeBytes } = entry;
+
+      // Any unexpected throw here (a source's readLines behaving outside its
+      // documented contract, a future bug) must not take down the rest of
+      // the scan and discard every finding already collected from other
+      // files — one bad file degrading to "unreadable" is the correct
+      // failure mode; the whole run crashing is not.
+      let result;
+      try {
+        result = await source.readLines(file);
+      } catch (err) {
+        unreadableFiles.push({ file: safeName(file), reason: "unexpected error" });
+        continue;
+      }
+
+      const { lines, status, bytesRead } = result;
+      if (status === "failed") {
+        unreadableFiles.push({ file: safeName(file), reason: "could not be read" });
+        continue;
+      }
+      if (status === "too-large") {
+        unreadableFiles.push({ file: safeName(file), reason: "too large to scan" });
+        continue;
+      }
+      // "partial" means the read failed partway through, but real lines WERE
+      // captured before that — those lines get scanned normally below (a
+      // secret in the part that succeeded is still a real finding), and the
+      // file is ALSO flagged so the user knows it wasn't fully checked.
+      if (status === "partial") {
+        unreadableFiles.push({ file: safeName(file), reason: "only partially read" });
+      }
+
+      sourceScannedAnything = true;
+      filesScanned++;
+      // Actual bytes streamed, not the pre-read stat() snapshot — matters
+      // for a file Claude Code is actively appending to mid-scan, where the
+      // two can genuinely differ.
+      bytesScanned += bytesRead || sizeBytes || 0;
+
+      const relFile = { name: safeName(file), source: source.id() };
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i]) matchLine(lines[i], file, relFile, i + 1, mtimeMs);
+      }
+    }
+
+    if (sourceScannedAnything) sourcesScanned.push(source.id());
+  }
+
+  const distinctCounts = {};
+  for (const [ruleId, set] of distinctByRule) distinctCounts[ruleId] = set.size;
+  return { findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount, distinctCounts, unreadableFiles };
+}
+
+/**
+ * The shape of a scan() result with nothing in it — exported so callers with
+ * a "nothing to scan" path (no sources on this machine) can reuse the exact
+ * result shape instead of hand-typing a duplicate literal that has to be
+ * remembered and kept in sync every time a new field is added here.
+ */
+function emptyResult() {
+  return {
+    findings: [], filesScanned: 0, sourcesScanned: [], bytesScanned: 0,
+    suppressedCount: 0, distinctCounts: {}, unreadableFiles: [],
+  };
+}
+
+module.exports = { scan, emptyResult };

package/src/sealcrypto.js

@@ -0,0 +1,149 @@
+"use strict";
+
+const fs = require("fs");
+const crypto = require("crypto");
+const zlib = require("zlib");
+const { pipeline } = require("stream/promises");
+const { Transform } = require("stream");
+
+/**
+ * Streaming seal/unseal for transcript files.
+ *
+ * AES-256-GCM + scrypt — the same primitives validated in the memvault spike,
+ * with both of that spike's hard-won lessons applied from the start:
+ *   - everything is Buffers end to end (a .toString("utf-8") round-trip on
+ *     binary silently corrupts it — verified, not theoretical);
+ *   - scrypt at N=2^15/r=8 needs ~32MB, exactly Node's DEFAULT maxmem, so
+ *     maxmem must be raised explicitly or the very first real run throws
+ *     ERR_CRYPTO_INVALID_SCRYPT_PARAMS (also verified the hard way).
+ *
+ * And one lesson from residoo itself: transcripts run to 800MB+, past V8's
+ * ~512M-char single-string ceiling, so seal/unseal are stream pipelines —
+ * no step ever materializes the whole file.
+ *
+ * Container format (one sealed file):
+ *   [4-byte BE header length][JSON header][ciphertext...][16-byte GCM tag]
+ * The header is PLAINTEXT and deliberately minimal — salt, iv, version.
+ * Anything sensitive (original path, plaintext hash) lives in the vault's
+ * separate manifest, which is itself sealed: a sealed blob that leaks its
+ * own origin path in cleartext would undermine the point of sealing it.
+ */
+
+const MAGIC = 1;
+const SCRYPT = { N: 2 ** 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+
+function deriveKey(passphrase, salt) {
+  return crypto.scryptSync(passphrase, salt, 32, SCRYPT);
+}
+
+/**
+ * Seal srcPath -> destPath, streaming (read -> gzip -> encrypt -> write).
+ * Returns { plainSha256, plainBytes, sealedBytes } — the plaintext hash is
+ * computed on the fly from the same bytes that get sealed, so the caller can
+ * later prove an unsealed copy is byte-identical to what went in.
+ */
+async function sealFile(srcPath, destPath, passphrase) {
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = deriveKey(passphrase, salt);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const hash = crypto.createHash("sha256");
+  let plainBytes = 0;
+
+  const header = Buffer.from(JSON.stringify({
+    v: MAGIC, salt: salt.toString("base64"), iv: iv.toString("base64"), gzip: true,
+  }), "utf-8");
+  const lenBuf = Buffer.alloc(4);
+  lenBuf.writeUInt32BE(header.length);
+
+  const out = fs.createWriteStream(destPath);
+  out.write(lenBuf);
+  out.write(header);
+
+  const tap = new Transform({
+    transform(chunk, _enc, cb) { plainBytes += chunk.length; hash.update(chunk); cb(null, chunk); },
+  });
+
+  await pipeline(fs.createReadStream(srcPath), tap, zlib.createGzip(), cipher, out, { end: false });
+  // GCM's auth tag only exists after the cipher finishes — appended last, read
+  // back first by unsealFile below.
+  const tag = cipher.getAuthTag();
+  await new Promise((resolve, reject) => out.end(tag, (err) => (err ? reject(err) : resolve())));
+
+  const sealedBytes = fs.statSync(destPath).size;
+  return { plainSha256: hash.digest("hex"), plainBytes, sealedBytes };
+}
+
+/** Unseal sealedPath -> destPath, streaming. Throws on wrong passphrase or any tampering (GCM tag). */
+async function unsealFile(sealedPath, destPath, passphrase) {
+  const fd = fs.openSync(sealedPath, "r");
+  let headerLen, header, dataStart, dataEnd, tag;
+  try {
+    const size = fs.fstatSync(fd).size;
+    const lenBuf = Buffer.alloc(4);
+    fs.readSync(fd, lenBuf, 0, 4, 0);
+    headerLen = lenBuf.readUInt32BE(0);
+    if (headerLen <= 0 || headerLen > 4096) throw new Error("not a residoo sealed file (bad header)");
+    const headerBuf = Buffer.alloc(headerLen);
+    fs.readSync(fd, headerBuf, 0, headerLen, 4);
+    header = JSON.parse(headerBuf.toString("utf-8"));
+    dataStart = 4 + headerLen;
+    dataEnd = size - 16; // GCM tag
+    if (dataEnd < dataStart) throw new Error("sealed file truncated");
+    tag = Buffer.alloc(16);
+    fs.readSync(fd, tag, 0, 16, dataEnd);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  const key = deriveKey(passphrase, Buffer.from(header.salt, "base64"));
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(header.iv, "base64"));
+  decipher.setAuthTag(tag);
+
+  const hash = crypto.createHash("sha256");
+  let plainBytes = 0;
+  const tap = new Transform({
+    transform(chunk, _enc, cb) { plainBytes += chunk.length; hash.update(chunk); cb(null, chunk); },
+  });
+
+  await pipeline(
+    fs.createReadStream(sealedPath, { start: dataStart, end: dataEnd - 1 }),
+    decipher,
+    zlib.createGunzip(),
+    tap,
+    fs.createWriteStream(destPath)
+  );
+  return { plainSha256: hash.digest("hex"), plainBytes };
+}
+
+/** Seal a small in-memory Buffer (the vault manifest) into the same container format. */
+function sealBuffer(buf, passphrase) {
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = deriveKey(passphrase, salt);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const gz = zlib.gzipSync(buf);
+  const ct = Buffer.concat([cipher.update(gz), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  const header = Buffer.from(JSON.stringify({
+    v: MAGIC, salt: salt.toString("base64"), iv: iv.toString("base64"), gzip: true,
+  }), "utf-8");
+  const lenBuf = Buffer.alloc(4);
+  lenBuf.writeUInt32BE(header.length);
+  return Buffer.concat([lenBuf, header, ct, tag]);
+}
+
+/** Inverse of sealBuffer. Returns the plaintext Buffer; throws on wrong passphrase/tampering. */
+function unsealBuffer(sealed, passphrase) {
+  const headerLen = sealed.readUInt32BE(0);
+  const header = JSON.parse(sealed.slice(4, 4 + headerLen).toString("utf-8"));
+  const tag = sealed.slice(sealed.length - 16);
+  const ct = sealed.slice(4 + headerLen, sealed.length - 16);
+  const key = deriveKey(passphrase, Buffer.from(header.salt, "base64"));
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(header.iv, "base64"));
+  decipher.setAuthTag(tag);
+  const gz = Buffer.concat([decipher.update(ct), decipher.final()]);
+  return zlib.gunzipSync(gz);
+}
+
+module.exports = { sealFile, unsealFile, sealBuffer, unsealBuffer };

package/src/sealvault.js

@@ -0,0 +1,111 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { sealFile, sealBuffer, unsealBuffer, unsealFile } = require("./sealcrypto");
+
+/**
+ * Seal every file that carried findings into an encrypted vault directory.
+ *
+ * Principles, in order of importance:
+ *   - NEVER touches the originals. Seal creates new files only; deleting the
+ *     plaintext afterwards is the user's own, separate, informed decision.
+ *     (residoo's core promise is that scanning is read-only — sealing writes
+ *     NEW files and nothing else.)
+ *   - The vault leaks nothing in plaintext. Sealed blobs are numbered
+ *     (0001.sealed…), and the mapping back to real paths + plaintext hashes
+ *     lives in manifest.sealed — itself encrypted. A vault that names its
+ *     own contents would defeat the point of uploading it anywhere.
+ *   - Streaming throughout: transcripts run to 800MB+; nothing here ever
+ *     holds a whole file in memory.
+ *
+ * Vault layout:
+ *   residoo-vault-<stamp>/
+ *     0001.sealed …      encrypted+gzipped transcript files
+ *     manifest.sealed    encrypted JSON: [{n, origPath, plainSha256, plainBytes, sealedBytes}]
+ *     README.txt         plaintext instructions (no sensitive content)
+ */
+async function sealFindings({ files, vaultDir, passphrase, log = () => {} }) {
+  fs.mkdirSync(vaultDir, { recursive: true });
+  const entries = [];
+  let n = 0;
+  for (const file of files) {
+    n++;
+    const name = String(n).padStart(4, "0") + ".sealed";
+    const dest = path.join(vaultDir, name);
+    log(`  sealing ${path.basename(file)} …`);
+    const { plainSha256, plainBytes, sealedBytes } = await sealFile(file, dest, passphrase);
+    entries.push({ n: name, origPath: file, plainSha256, plainBytes, sealedBytes });
+    log(`    -> ${name}  (${(plainBytes / 1024 / 1024).toFixed(1)}MB plain -> ${(sealedBytes / 1024 / 1024).toFixed(1)}MB sealed)`);
+  }
+
+  const manifest = { v: 1, entries };
+  fs.writeFileSync(path.join(vaultDir, "manifest.sealed"), sealBuffer(Buffer.from(JSON.stringify(manifest, null, 2), "utf-8"), passphrase));
+  fs.writeFileSync(path.join(vaultDir, "README.txt"),
+    "residoo sealed vault\n" +
+    "====================\n\n" +
+    "Files here are AES-256-GCM encrypted (scrypt-derived key). Without the\n" +
+    "passphrase they are unreadable, including by residoo's authors.\n\n" +
+    "To list contents:   residoo unseal <vault-dir>            (prompts for passphrase)\n" +
+    "To restore a file:  residoo unseal <vault-dir> --restore <n> --out <path>\n\n" +
+    "manifest.sealed maps the numbered blobs back to their original paths and\n" +
+    "records a SHA-256 of each original, so a restore can be verified as\n" +
+    "byte-identical. The manifest is encrypted for the same reason the files\n" +
+    "are: even the NAMES of what is in here are nobody else's business.\n"
+  );
+  return { entries, vaultDir };
+}
+
+/** Decrypt and return the vault's manifest. Throws on wrong passphrase. */
+function openManifest(vaultDir, passphrase) {
+  const sealed = fs.readFileSync(path.join(vaultDir, "manifest.sealed"));
+  return JSON.parse(unsealBuffer(sealed, passphrase).toString("utf-8"));
+}
+
+/** Restore one numbered entry to outPath and verify it against the recorded hash. */
+async function restoreEntry(vaultDir, entry, outPath, passphrase) {
+  const { plainSha256, plainBytes } = await unsealFile(path.join(vaultDir, entry.n), outPath, passphrase);
+  const ok = plainSha256 === entry.plainSha256 && plainBytes === entry.plainBytes;
+  return { ok, plainSha256, plainBytes };
+}
+
+/**
+ * Upload a vault to CloudRoam — the ONLY code path in residoo that touches
+ * the network, and it never runs unless the user passed --upload-cloudroam
+ * explicitly. Uses CloudRoam's raw-body streaming endpoint
+ * (POST /api/files/upload-stream?bucket&key + X-Connector-Id), so this stays
+ * zero-dependency. Only ciphertext leaves the machine: the vault's files are
+ * already sealed before this function is ever called, and the manifest that
+ * names them is sealed too.
+ */
+async function uploadVaultToCloudRoam({ vaultDir, baseUrl, apiKey, connectorId, bucket, prefix, log = () => {} }) {
+  const files = fs.readdirSync(vaultDir).filter((f) => f.endsWith(".sealed") || f === "README.txt");
+  const base = baseUrl.replace(/\/+$/, "");
+  const uploaded = [];
+  for (const f of files) {
+    const full = path.join(vaultDir, f);
+    const size = fs.statSync(full).size;
+    const key = (prefix ? prefix.replace(/\/+$/, "") + "/" : "") + path.basename(vaultDir) + "/" + f;
+    const q = new URLSearchParams({ bucket, key });
+    log(`  uploading ${f} (${(size / 1024 / 1024).toFixed(1)}MB) …`);
+    const res = await fetch(`${base}/api/files/upload-stream?${q}`, {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + apiKey,
+        "X-Connector-Id": connectorId,
+        "Content-Type": "application/octet-stream",
+        "Content-Length": String(size),
+      },
+      body: fs.createReadStream(full),
+      duplex: "half", // required by Node's fetch for a streaming request body
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`upload of ${f} failed: HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    uploaded.push(key);
+  }
+  return uploaded;
+}
+
+module.exports = { sealFindings, openManifest, restoreEntry, uploadVaultToCloudRoam };