shipback-sftp 0.2.0 → 0.2.1

package/README.md

@@ -26,6 +26,8 @@ if undo ever breaks one of them, that's the first bug I fix.
 - **Restores can be undone too.** A restore backs up what it replaces, the same way a deploy does.
 - **One run at a time.** A deploy or restore holds a lock on the site while it writes. A second one is turned away
   with nothing changed, so an agent and a person can't deploy over each other.
+- **Stays inside the site.** Deploy and undo won't write through a symlink or over a special file on the server,
+  so a symlinked folder can't carry a write somewhere else.
 - **Safe for agents.** The MCP server has no switch to delete server files or skip the backup. A deploy
   only runs the exact plan the agent previewed: if a file changed in between, it refuses.
 - **Spots the drift.** `--pull --dry-run` shows what changed on the server since your last deploy, so
@@ -113,7 +115,8 @@ step, keeping its permissions. Listings hide part files, and the next deploy or
 
 While a deploy, upload, restore or prune writes, it holds `.shipback-lock` in the remote root and refreshes it every
 30 seconds. The lock is never deployed, pulled or listed. A lock goes stale, and the next run takes it over, when its
-process on this computer has ended or nothing has refreshed it for 2 minutes. So a run that was cut off never leaves
+process on this computer has ended or nothing has refreshed it for 2 minutes. If the system has reused that process
+ID, the lock just waits out the 2 minutes; a run that's still going is never mistaken for a finished one. So a run that was cut off never leaves
 a site locked for long.
 
 `--restore` reads that record and checks each live file first:

package/UNDO-PROMISE.md

@@ -24,7 +24,7 @@ and Linux, and compare every byte on the server, not a sample.
 | **P10** | All of this works through a real SFTP server, and replaced files keep their permissions. |
 | **P11** | A dropped connection fails the deploy out loud and tells you how to undo it. It never stops in silence. |
 | **P12** | Only one deploy or undo writes to a site at a time. A second one is turned away without changing anything, so two runs can never get mixed into one backup. A lock left behind by a run that was cut off clears itself. |
-| **P13** | Undo never touches anything outside the site folder, even if a backup record has been tampered with to say it should. A record that can't be read is refused, never guessed at. |
+| **P13** | Undo never touches anything outside the site folder, even if a backup record has been tampered with to say it should, and neither undo nor deploy writes through a symlink or over a special file on the server. A record that can't be read is refused, never guessed at. |
 
 These have also been run on a real cPanel host, including cutting the connection halfway through a deploy and running
 two deploys at once.
@@ -41,7 +41,8 @@ If undo ever fails to do one of those things, [open an "Undo didn't work" issue]
 
 - **Deploys made with `--no-backup`.** They have nothing to undo from. The agent tools can't make them.
 - **Backups that are gone.** Undo needs that deploy's `_backup-…` folder. `--prune` will remove old ones if you ask, and so can you or your host.
-- **Anything outside the site folder:** databases, server settings, cron jobs, email.
+- **Anything outside the site folder:** databases, server settings, cron jobs, email. The site folder itself may be a
+  symlink (cPanel's `www` → `public_html` is normal), and Shipback follows that one. It won't follow any symlink inside it.
 - **Backups made before 0.2.** Those still restore, but they don't carry the checksums behind P4 and P8.
 - **File dates and owners.** Restored files get the current time. A file brought back after a deploy deleted it gets the server's default permissions.
 - **Losing the hosting account.** Backups sit on the same server as the site. Keep your host's own backups too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipback-sftp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "SFTP deploys to shared hosting that you, a script or an AI agent can undo: backup before every overwrite, one-command restore that won't clobber live edits, and an MCP server.",
   "keywords": [
     "sftp",

package/src/deploy.js

@@ -5,7 +5,7 @@ const posix = path.posix;
 const { scanLocal, loadIgnore, dropIgnored, sha256File } = require('./manifest');
 const { plan: makePlan, resolveVerify, MANIFEST_NAME, BACKUP_PREFIX } = require('./diff');
 const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo } = require('./backup');
-const { writeLive } = require('./remote-fs');
+const { writeLive, outsideReason } = require('./remote-fs');
 const { withLock } = require('./lock');
 
 const isBackupDir = name => name.startsWith(BACKUP_PREFIX);
@@ -15,6 +15,15 @@ async function readRemoteManifest(remoteFs, root) {
   catch { return null; }
 }
 
+/** Throw before anything changes if any path would write through a symlink or over a special file. */
+async function refuseOutside(remoteFs, root, paths) {
+  const folders = new Map();
+  for (const p of paths) {
+    const why = await outsideReason(remoteFs, root, p, folders);
+    if (why) throw new Error(`Refused: ${why}. Nothing was changed. Ignore that path in sites.json or .deployignore, or replace the symlink with a real folder.`);
+  }
+}
+
 /** Preview only: scan both sides and return the plan. */
 async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, ignore, onEvent = () => {} }) {
   const root = remoteRoot.replace(/\/$/, '');
@@ -27,6 +36,7 @@ async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, i
   const remoteListing = rootStat ? dropIgnored(await remoteFs.listRecursive(root, { skipDir: isBackupDir }), await loadIgnore(localDir, ignore)) : [];
   const remoteManifest = rootStat ? await readRemoteManifest(remoteFs, root) : null;
   const plan = makePlan({ local, remoteManifest, remoteListing, mirror });
+  if (rootStat) await refuseOutside(remoteFs, root, [...plan.upload.map(u => u.path), ...plan.delete]);
   if (plan.verify.length) await resolveVerify(plan, { readFile: p => remoteFs.readFile(`${root}/${p}`), onEvent });
   onEvent({ type: 'plan', plan, localCount: local.length, remoteCount: remoteListing.length, remoteExists: !!rootStat });
   return { local, plan, remoteExists: !!rootStat };
@@ -114,6 +124,7 @@ async function uploadNow({ files, remoteDir, remoteFs, backup = true, now = new
   const summary = { uploaded: [], backedUp: [], backupDir: null, bytes: 0 };
   try {
     await remoteFs.mkdirp(root);
+    await refuseOutside(remoteFs, root, files.map(f => f.name));
     if (backup && files.length) {
       const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
       await writeBackupInfo({ remoteFs, backupDir, info: { action: 'upload', at: now.toISOString(), status: 'saving', overwritten: [], added: [], deleted: [] } });

package/src/remote-fs.js

@@ -3,6 +3,7 @@
 //   stat(p) → { size, mtime(ms), isDir } | null
 //   listRecursive(dir, { skipDir }) → [{ path (posix, relative to dir), size, mtime(ms) }]  (files only)
 //   mkdirp(p) · readFile(p) → Buffer · writeFile(p, Buffer) · uploadFile(localPath, p)
+//   lstat(p) → { isDir, isFile, isLink } | null (does not follow symlinks)
 //   rename(a, b) · replace(tmp, dest) · remove(p) · rmdir(p) · close()
 //
 // Live files are never written in place: the new copy goes to partPath(dest) and replace() swaps it in, so a
@@ -21,7 +22,15 @@ const isHidden = rel => isPart(rel) || rel === LOCK_NAME; // Shipback's own work
 // ---------------------------------------------------------------- MemoryRemoteFs (tests)
 class MemoryRemoteFs {
   // failOn(p): throw before touching p · tornOn(p): write half of p, then throw (a dropped connection)
-  constructor() { this.files = new Map(); this.dirs = new Set(['/']); this.failOn = null; this.tornOn = null; }
+  // odd: path → 'link' | 'fifo', for paths a test says are a symlink or a special file
+  constructor() { this.files = new Map(); this.dirs = new Set(['/']); this.failOn = null; this.tornOn = null; this.odd = new Map(); }
+  async lstat(p) {
+    p = posix.normalize(p);
+    const odd = this.odd.get(p);
+    if (odd) return { isDir: false, isFile: false, isLink: odd === 'link' };
+    const st = await this.stat(p);
+    return st && { isDir: st.isDir, isFile: !st.isDir, isLink: false };
+  }
   _check(p) { if (this.failOn && this.failOn(p)) throw new Error(`Simulated failure on ${p}`); }
   async stat(p) {
     p = posix.normalize(p);
@@ -143,6 +152,10 @@ class SftpRemoteFs {
     try { const a = await this._p(cb => this.sftp.stat(p, cb)); return { size: a.size, mtime: a.mtime * 1000, isDir: a.isDirectory(), mode: a.mode }; }
     catch (e) { if (e.code === 2 || /No such file/i.test(e.message)) return null; throw e; }
   }
+  async lstat(p) {
+    try { const a = await this._p(cb => this.sftp.lstat(p, cb)); return { isDir: a.isDirectory(), isFile: a.isFile(), isLink: a.isSymbolicLink() }; }
+    catch (e) { if (e.code === 2 || /No such file/i.test(e.message)) return null; throw e; }
+  }
   async listRecursive(dir, { skipDir } = {}) {
     const out = [];
     const walk = async (abs, rel) => {
@@ -215,6 +228,32 @@ class SftpRemoteFs {
   async close() { try { this.client.end(); } catch { /* ignore */ } }
 }
 
+/**
+ * Why writing or removing <root>/<rel> would not stay inside the site, or null if it's safe: every folder between
+ * the root and the file must be a real folder (a symlinked one would carry the write somewhere else), and the file
+ * itself a plain file or not there yet. The root itself may be a symlink (cPanel's www → public_html is normal).
+ * folders: a Map shared across one run, so each folder is looked at once.
+ */
+async function outsideReason(remoteFs, root, rel, folders = new Map()) {
+  const segs = rel.split('/');
+  let cur = root.replace(/\/$/, '');
+  for (let i = 0; i < segs.length; i++) {
+    cur += '/' + segs[i];
+    const shown = segs.slice(0, i + 1).join('/');
+    const last = i === segs.length - 1;
+    if (!last && folders.has(cur)) { const why = folders.get(cur); if (why === 'missing') return null; if (why) return why; continue; }
+    const st = await remoteFs.lstat(cur);
+    if (!st) { if (!last) folders.set(cur, 'missing'); return null; } // nothing there yet: what gets made is a real folder
+    let why = null;
+    if (st.isLink) why = `${shown} is a symlink on the server, so writing there could reach outside the site`;
+    else if (!last && !st.isDir) why = `${shown} is not a folder on the server`;
+    else if (last && !st.isFile && !st.isDir) why = `${shown} is a special file on the server (not a plain file)`;
+    if (!last) folders.set(cur, why);
+    if (why) return why;
+  }
+  return null;
+}
+
 /** Write a live file the safe way: to its part file first, then swapped in whole. Give { data } or { localPath }. */
 async function writeLive(remoteFs, dest, { data, localPath }) {
   const part = partPath(dest);
@@ -223,4 +262,4 @@ async function writeLive(remoteFs, dest, { data, localPath }) {
   await remoteFs.replace(part, dest);
 }
 
-module.exports = { PART_PREFIX, LOCK_NAME, partPath, isPart, isHidden, writeLive, MemoryRemoteFs, SftpRemoteFs };
+module.exports = { PART_PREFIX, LOCK_NAME, partPath, isPart, isHidden, writeLive, outsideReason, MemoryRemoteFs, SftpRemoteFs };

package/src/restore.js

@@ -23,7 +23,7 @@ const posix = require('node:path').posix;
 const { BACKUP_PREFIX, MANIFEST_NAME } = require('./diff');
 const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, BACKUP_INFO } = require('./backup');
 const { listBackups } = require('./prune');
-const { partPath, writeLive } = require('./remote-fs');
+const { partPath, writeLive, outsideReason } = require('./remote-fs');
 const { withLock } = require('./lock');
 
 const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
@@ -97,9 +97,18 @@ async function restoreNow({ remoteRoot, remoteFs, name, dryRun = false, force =
   };
   const conflict = (p, why) => summary.conflicts.push({ path: p, why });
 
+  // never through a symlink or over a special file, even forced: that could reach outside the site
+  const folders = new Map(), unsafe = new Set();
+  const outside = async p => {
+    const why = await outsideReason(remoteFs, root, p, folders);
+    if (why) { unsafe.add(p); conflict(p, why); }
+    return !!why;
+  };
+
   // 1. what goes back: every file in the backup folder
   const puts = [];
   for (const f of (await remoteFs.listRecursive(dir)).filter(f => f.path !== BACKUP_INFO)) {
+    if (await outside(f.path)) continue;
     const data = await remoteFs.readFile(`${dir}/${f.path}`);
     if (was.has(f.path) && sha256(data) !== was.get(f.path)) { conflict(f.path, 'its copy in the backup folder is damaged (it no longer matches what was saved)'); continue; } // never put back, even forced
     const now_ = await live(f.path);
@@ -112,6 +121,7 @@ async function restoreNow({ remoteRoot, remoteFs, name, dryRun = false, force =
   // 2. what comes off: the files that run added
   const removes = [];
   if (info) for (const e of info.added) {
+    if (await outside(e.path)) continue;
     const now_ = await live(e.path);
     if (now_ === null) { summary.same.push(e.path); continue; }
     if (now_ === 'dir') { conflict(e.path, 'is a folder on the server now'); continue; }
@@ -132,6 +142,7 @@ async function restoreNow({ remoteRoot, remoteFs, name, dryRun = false, force =
   // part files a stopped run left behind (hidden from listings, but they hold the run's bytes)
   const sweepParts = async () => {
     for (const p of new Set([...left.keys(), ...deleted])) {
+      if (unsafe.has(p)) continue;
       const part = partPath(`${root}/${p}`);
       if (await remoteFs.stat(part)) await remoteFs.remove(part).catch(() => {});
     }