@sakupa/mcp 0.7.22 → 0.7.23

package/dist/index.js

@@ -124,7 +124,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.22";
+var SAKUPA_MCP_VERSION = "0.7.23";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -155,8 +155,8 @@ var SakupaError = class extends Error {
     this.details = details;
   }
 };
-function isSakupaError(err) {
-  return err instanceof SakupaError;
+function isSakupaError(err2) {
+  return err2 instanceof SakupaError;
 }
 
 // ../core/dist/domain/tiers.js
@@ -431,7 +431,12 @@ function safeDecode(bytes) {
 }
 
 // ../core/dist/domain/credentials.js
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+var CREDENTIAL_PREFIX = "sk_";
 var CREDENTIAL_PATTERN = /^sk_[A-Za-z0-9_-]{43}$/;
+function generateCredential(random = randomBytes) {
+  return CREDENTIAL_PREFIX + random(32).toString("base64url");
+}
 
 // ../core/dist/domain/hashing.js
 async function sha256Hex(bytes) {
@@ -556,6 +561,29 @@ var FetchTransport = class {
       );
     }
   }
+  async download(url) {
+    let target;
+    try {
+      target = new URL(url);
+    } catch {
+      throw new SakupaError("invalid_request", "Archive download URL is invalid");
+    }
+    if (target.origin !== new URL(this.baseUrl).origin) {
+      throw new SakupaError("forbidden", "Archive download URL is outside the Sakupa API origin");
+    }
+    const res = await fetch(target, {
+      method: "GET",
+      headers: this.testAccessHeadersFor(target.toString())
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new SakupaError(
+        res.status === 429 || res.status >= 500 ? "internal" : "validation_failed",
+        `Archive download failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 200)}` : ""}`
+      );
+    }
+    return new Uint8Array(await res.arrayBuffer());
+  }
 };
 
 // src/api-client.ts
@@ -650,6 +678,16 @@ var HttpApiClient = class {
       credential
     });
   }
+  async getSiteArchive(siteId, credential) {
+    return this.call(
+      "GET",
+      `/v1/sites/${encodeURIComponent(siteId)}/archive`,
+      { credential }
+    );
+  }
+  async downloadArchive(url) {
+    return this.transport.download(url);
+  }
   async deleteSite(siteId, credential, req) {
     return this.call("POST", `/v1/sites/${encodeURIComponent(siteId)}/delete`, {
       credential,
@@ -747,19 +785,23 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync }
 import { dirname, join } from "node:path";
 var SITE_DIR = ".sakupa";
 var SITE_FILE = "site.json";
+var RECOVERY_FILE = "recovery.json";
 function siteFilePath(projectDir) {
   return join(projectDir, SITE_DIR, SITE_FILE);
 }
+function recoveryFilePath(projectDir) {
+  return join(projectDir, SITE_DIR, RECOVERY_FILE);
+}
 function loadSiteFile(projectDir) {
   const path = siteFilePath(projectDir);
   if (!existsSync(path)) return { kind: "absent" };
   let raw;
   try {
     raw = readFileSync(path, "utf8");
-  } catch (err) {
+  } catch (err2) {
     return {
       kind: "corrupted",
-      problem: `the file exists but could not be read (${err instanceof Error ? err.message : String(err)})`
+      problem: `the file exists but could not be read (${err2 instanceof Error ? err2.message : String(err2)})`
     };
   }
   let parsed;
@@ -796,6 +838,40 @@ function loadSiteFile(projectDir) {
     }
   };
 }
+function loadRecoveryFile(projectDir) {
+  const path = recoveryFilePath(projectDir);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed.verificationId !== "string" || parsed.verificationId.length === 0 || typeof parsed.credential !== "string" || !CREDENTIAL_PATTERN.test(parsed.credential)) {
+      throw new Error("required recovery fields are missing or invalid");
+    }
+    return {
+      verificationId: parsed.verificationId,
+      credential: parsed.credential,
+      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : ""
+    };
+  } catch (error) {
+    throw new Error(
+      `Recovery state ${path} is damaged (${error instanceof Error ? error.message : String(error)}). Do not start another DNS recovery until this file is repaired or deliberately removed.`
+    );
+  }
+}
+function writeRecoveryFile(projectDir, file) {
+  const dir = join(projectDir, SITE_DIR);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, RECOVERY_FILE);
+  writeFileSync(path, `${JSON.stringify(file, null, 2)}
+`, "utf8");
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+}
+function deleteRecoveryFile(projectDir) {
+  const path = recoveryFilePath(projectDir);
+  if (existsSync(path)) rmSync(path, { force: true });
+}
 function siteFileRecoveryGuidance(projectDir) {
   return `The site itself is intact on the server; only the local binding file (${siteFilePath(projectDir)}) is the problem. Restore the file (from a backup or by undoing the local edit). Do NOT delete it to work around the error: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site. Publishing this project as a brand-NEW site requires the user to manually delete the .sakupa directory first \u2014 the tool will never overwrite it.`;
 }
@@ -885,8 +961,8 @@ async function isFile(path) {
 }
 async function readTextIfExists(path, maxBytes = CONTENT_READ_MAX_BYTES) {
   try {
-    const stat = await fs.stat(path);
-    if (!stat.isFile() || stat.size > maxBytes) return null;
+    const stat2 = await fs.stat(path);
+    if (!stat2.isFile() || stat2.size > maxBytes) return null;
     return await fs.readFile(path, "utf8");
   } catch {
     return null;
@@ -926,8 +1002,8 @@ async function walkFiles(dir, opts) {
         await recurse(join2(current, entry.name), rel);
       } else if (entry.isFile()) {
         try {
-          const stat = await fs.stat(join2(current, entry.name));
-          out.push({ path: rel, size: stat.size });
+          const stat2 = await fs.stat(join2(current, entry.name));
+          out.push({ path: rel, size: stat2.size });
         } catch {
         }
       }
@@ -1342,8 +1418,8 @@ function withProjectDir(ctx, projectDirArg) {
       `projectDir "${dir}" is a filesystem root or the home directory. Pass the specific project folder that holds the site's files, not a top-level directory.`
     );
   }
-  const stat = statSync(dir, { throwIfNoEntry: false });
-  if (!stat?.isDirectory()) {
+  const stat2 = statSync(dir, { throwIfNoEntry: false });
+  if (!stat2?.isDirectory()) {
     throw new LocalGuidanceError(
       "invalid_request",
       `projectDir "${dir}" does not exist or is not a directory. Pass the absolute path of the directory the user is currently working in.`
@@ -1408,17 +1484,646 @@ function toolError(e) {
 // src/tools/definitions.ts
 import { randomUUID } from "node:crypto";
 import { existsSync as existsSync3, promises as fs2 } from "node:fs";
-import { join as join4, resolve as resolve3 } from "node:path";
+import { join as join5, resolve as resolve4 } from "node:path";
 import { z as z3 } from "zod";
 
+// src/recovery-archive.ts
+import { mkdtemp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve3, sep as sep2 } from "node:path";
+
+// ../../node_modules/fflate/esm/index.mjs
+import { createRequire } from "module";
+var require2 = createRequire("/");
+var _a;
+var Worker;
+var isMarkedAsUntransferable;
+try {
+  _a = require2("worker_threads"), Worker = _a.Worker, isMarkedAsUntransferable = _a.isMarkedAsUntransferable;
+} catch (e) {
+}
+var u8 = Uint8Array;
+var u16 = Uint16Array;
+var i32 = Int32Array;
+var fleb = new u8([
+  0,
+  0,
+  0,
+  0,
+  0,
+  0,
+  0,
+  0,
+  1,
+  1,
+  1,
+  1,
+  2,
+  2,
+  2,
+  2,
+  3,
+  3,
+  3,
+  3,
+  4,
+  4,
+  4,
+  4,
+  5,
+  5,
+  5,
+  5,
+  0,
+  /* unused */
+  0,
+  0,
+  /* impossible */
+  0
+]);
+var fdeb = new u8([
+  0,
+  0,
+  0,
+  0,
+  1,
+  1,
+  2,
+  2,
+  3,
+  3,
+  4,
+  4,
+  5,
+  5,
+  6,
+  6,
+  7,
+  7,
+  8,
+  8,
+  9,
+  9,
+  10,
+  10,
+  11,
+  11,
+  12,
+  12,
+  13,
+  13,
+  /* unused */
+  0,
+  0
+]);
+var clim = new u8([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15]);
+var freb = function(eb, start) {
+  var b = new u16(31);
+  for (var i = 0; i < 31; ++i) {
+    b[i] = start += 1 << eb[i - 1];
+  }
+  var r = new i32(b[30]);
+  for (var i = 1; i < 30; ++i) {
+    for (var j = b[i]; j < b[i + 1]; ++j) {
+      r[j] = j - b[i] << 5 | i;
+    }
+  }
+  return { b, r };
+};
+var _a = freb(fleb, 2);
+var fl = _a.b;
+var revfl = _a.r;
+fl[28] = 258, revfl[258] = 28;
+var _b = freb(fdeb, 0);
+var fd = _b.b;
+var revfd = _b.r;
+var rev = new u16(32768);
+for (i = 0; i < 32768; ++i) {
+  x = (i & 43690) >> 1 | (i & 21845) << 1;
+  x = (x & 52428) >> 2 | (x & 13107) << 2;
+  x = (x & 61680) >> 4 | (x & 3855) << 4;
+  rev[i] = ((x & 65280) >> 8 | (x & 255) << 8) >> 1;
+}
+var x;
+var i;
+var hMap = function(cd, mb, r) {
+  var s = cd.length;
+  var i = 0;
+  var l = new u16(mb);
+  for (; i < s; ++i) {
+    if (cd[i])
+      ++l[cd[i] - 1];
+  }
+  var le = new u16(mb);
+  for (i = 1; i < mb; ++i) {
+    le[i] = le[i - 1] + l[i - 1] << 1;
+  }
+  var co;
+  if (r) {
+    co = new u16(1 << mb);
+    var rvb = 15 - mb;
+    for (i = 0; i < s; ++i) {
+      if (cd[i]) {
+        var sv = i << 4 | cd[i];
+        var r_1 = mb - cd[i];
+        var v = le[cd[i] - 1]++ << r_1;
+        for (var m = v | (1 << r_1) - 1; v <= m; ++v) {
+          co[rev[v] >> rvb] = sv;
+        }
+      }
+    }
+  } else {
+    co = new u16(s);
+    for (i = 0; i < s; ++i) {
+      if (cd[i]) {
+        co[i] = rev[le[cd[i] - 1]++] >> 15 - cd[i];
+      }
+    }
+  }
+  return co;
+};
+var flt = new u8(288);
+for (i = 0; i < 144; ++i)
+  flt[i] = 8;
+var i;
+for (i = 144; i < 256; ++i)
+  flt[i] = 9;
+var i;
+for (i = 256; i < 280; ++i)
+  flt[i] = 7;
+var i;
+for (i = 280; i < 288; ++i)
+  flt[i] = 8;
+var i;
+var fdt = new u8(32);
+for (i = 0; i < 32; ++i)
+  fdt[i] = 5;
+var i;
+var flrm = /* @__PURE__ */ hMap(flt, 9, 1);
+var fdrm = /* @__PURE__ */ hMap(fdt, 5, 1);
+var max = function(a) {
+  var m = a[0];
+  for (var i = 1; i < a.length; ++i) {
+    if (a[i] > m)
+      m = a[i];
+  }
+  return m;
+};
+var bits = function(d, p, m) {
+  var o = p / 8 | 0;
+  return (d[o] | d[o + 1] << 8) >> (p & 7) & m;
+};
+var bits16 = function(d, p) {
+  var o = p / 8 | 0;
+  return (d[o] | d[o + 1] << 8 | d[o + 2] << 16) >> (p & 7);
+};
+var shft = function(p) {
+  return (p + 7) / 8 | 0;
+};
+var slc = function(v, s, e) {
+  if (s == null || s < 0)
+    s = 0;
+  if (e == null || e > v.length)
+    e = v.length;
+  return new u8(v.subarray(s, e));
+};
+var ec = [
+  "unexpected EOF",
+  "invalid block type",
+  "invalid length/literal",
+  "invalid distance",
+  "stream finished",
+  "no stream handler",
+  ,
+  // determined by compression function
+  "no callback",
+  "invalid UTF-8 data",
+  "extra field too long",
+  "date not in range 1980-2099",
+  "filename too long",
+  "stream finishing",
+  "invalid zip data"
+  // determined by unknown compression method
+];
+var err = function(ind, msg, nt) {
+  var e = new Error(msg || ec[ind]);
+  e.code = ind;
+  if (Error.captureStackTrace)
+    Error.captureStackTrace(e, err);
+  if (!nt)
+    throw e;
+  return e;
+};
+var inflt = function(dat, st, buf, dict) {
+  var sl = dat.length, dl = dict ? dict.length : 0;
+  if (!sl || st.f && !st.l)
+    return buf || new u8(0);
+  var noBuf = !buf;
+  var resize = noBuf || st.i != 2;
+  var noSt = st.i;
+  if (noBuf)
+    buf = new u8(sl * 3);
+  var cbuf = function(l2) {
+    var bl = buf.length;
+    if (l2 > bl) {
+      var nbuf = new u8(Math.max(bl * 2, l2));
+      nbuf.set(buf);
+      buf = nbuf;
+    }
+  };
+  var final = st.f || 0, pos = st.p || 0, bt = st.b || 0, lm = st.l, dm = st.d, lbt = st.m, dbt = st.n;
+  var tbts = sl * 8;
+  do {
+    if (!lm) {
+      final = bits(dat, pos, 1);
+      var type = bits(dat, pos + 1, 3);
+      pos += 3;
+      if (!type) {
+        var s = shft(pos) + 4, l = dat[s - 4] | dat[s - 3] << 8, t = s + l;
+        if (t > sl) {
+          if (noSt)
+            err(0);
+          break;
+        }
+        if (resize)
+          cbuf(bt + l);
+        buf.set(dat.subarray(s, t), bt);
+        st.b = bt += l, st.p = pos = t * 8, st.f = final;
+        continue;
+      } else if (type == 1)
+        lm = flrm, dm = fdrm, lbt = 9, dbt = 5;
+      else if (type == 2) {
+        var hLit = bits(dat, pos, 31) + 257, hcLen = bits(dat, pos + 10, 15) + 4;
+        var tl = hLit + bits(dat, pos + 5, 31) + 1;
+        pos += 14;
+        var ldt = new u8(tl);
+        var clt = new u8(19);
+        for (var i = 0; i < hcLen; ++i) {
+          clt[clim[i]] = bits(dat, pos + i * 3, 7);
+        }
+        pos += hcLen * 3;
+        var clb = max(clt), clbmsk = (1 << clb) - 1;
+        var clm = hMap(clt, clb, 1);
+        for (var i = 0; i < tl; ) {
+          var r = clm[bits(dat, pos, clbmsk)];
+          pos += r & 15;
+          var s = r >> 4;
+          if (s < 16) {
+            ldt[i++] = s;
+          } else {
+            var c = 0, n = 0;
+            if (s == 16)
+              n = 3 + bits(dat, pos, 3), pos += 2, c = ldt[i - 1];
+            else if (s == 17)
+              n = 3 + bits(dat, pos, 7), pos += 3;
+            else if (s == 18)
+              n = 11 + bits(dat, pos, 127), pos += 7;
+            while (n--)
+              ldt[i++] = c;
+          }
+        }
+        var lt = ldt.subarray(0, hLit), dt = ldt.subarray(hLit);
+        lbt = max(lt);
+        dbt = max(dt);
+        lm = hMap(lt, lbt, 1);
+        dm = hMap(dt, dbt, 1);
+      } else
+        err(1);
+      if (pos > tbts) {
+        if (noSt)
+          err(0);
+        break;
+      }
+    }
+    if (resize)
+      cbuf(bt + 131072);
+    var lms = (1 << lbt) - 1, dms = (1 << dbt) - 1;
+    var lpos = pos;
+    for (; ; lpos = pos) {
+      var c = lm[bits16(dat, pos) & lms], sym = c >> 4;
+      pos += c & 15;
+      if (pos > tbts) {
+        if (noSt)
+          err(0);
+        break;
+      }
+      if (!c)
+        err(2);
+      if (sym < 256)
+        buf[bt++] = sym;
+      else if (sym == 256) {
+        lpos = pos, lm = null;
+        break;
+      } else {
+        var add = sym - 254;
+        if (sym > 264) {
+          var i = sym - 257, b = fleb[i];
+          add = bits(dat, pos, (1 << b) - 1) + fl[i];
+          pos += b;
+        }
+        var d = dm[bits16(dat, pos) & dms], dsym = d >> 4;
+        if (!d)
+          err(3);
+        pos += d & 15;
+        var dt = fd[dsym];
+        if (dsym > 3) {
+          var b = fdeb[dsym];
+          dt += bits16(dat, pos) & (1 << b) - 1, pos += b;
+        }
+        if (pos > tbts) {
+          if (noSt)
+            err(0);
+          break;
+        }
+        if (resize)
+          cbuf(bt + 131072);
+        var end = bt + add;
+        if (bt < dt) {
+          var shift = dl - dt, dend = Math.min(dt, end);
+          if (shift + bt < 0)
+            err(3);
+          for (; bt < dend; ++bt)
+            buf[bt] = dict[shift + bt];
+        }
+        for (; bt < end; ++bt)
+          buf[bt] = buf[bt - dt];
+      }
+    }
+    st.l = lm, st.p = lpos, st.b = bt, st.f = final;
+    if (lm)
+      final = 1, st.m = lbt, st.d = dm, st.n = dbt;
+  } while (!final);
+  return bt != buf.length && noBuf ? slc(buf, 0, bt) : buf.subarray(0, bt);
+};
+var et = /* @__PURE__ */ new u8(0);
+var b2 = function(d, b) {
+  return d[b] | d[b + 1] << 8;
+};
+var b4 = function(d, b) {
+  return (d[b] | d[b + 1] << 8 | d[b + 2] << 16 | d[b + 3] << 24) >>> 0;
+};
+var b8 = function(d, b) {
+  return b4(d, b) + b4(d, b + 4) * 4294967296;
+};
+function inflateSync(data, opts) {
+  return inflt(data, { i: 2 }, opts && opts.out, opts && opts.dictionary);
+}
+var td = typeof TextDecoder != "undefined" && /* @__PURE__ */ new TextDecoder();
+var tds = 0;
+try {
+  td.decode(et, { stream: true });
+  tds = 1;
+} catch (e) {
+}
+var dutf8 = function(d) {
+  for (var r = "", i = 0; ; ) {
+    var c = d[i++];
+    var eb = (c > 127) + (c > 223) + (c > 239);
+    if (i + eb > d.length)
+      return { s: r, r: slc(d, i - 1) };
+    if (!eb)
+      r += String.fromCharCode(c);
+    else if (eb == 3) {
+      c = ((c & 15) << 18 | (d[i++] & 63) << 12 | (d[i++] & 63) << 6 | d[i++] & 63) - 65536, r += String.fromCharCode(55296 | c >> 10, 56320 | c & 1023);
+    } else if (eb & 1)
+      r += String.fromCharCode((c & 31) << 6 | d[i++] & 63);
+    else
+      r += String.fromCharCode((c & 15) << 12 | (d[i++] & 63) << 6 | d[i++] & 63);
+  }
+};
+function strFromU8(dat, latin1) {
+  if (latin1) {
+    var r = "";
+    for (var i = 0; i < dat.length; i += 16384)
+      r += String.fromCharCode.apply(null, dat.subarray(i, i + 16384));
+    return r;
+  } else if (td) {
+    return td.decode(dat);
+  } else {
+    var _a2 = dutf8(dat), s = _a2.s, r = _a2.r;
+    if (r.length)
+      err(8);
+    return s;
+  }
+}
+var slzh = function(d, b) {
+  return b + 30 + b2(d, b + 26) + b2(d, b + 28);
+};
+var zh = function(d, b, z6) {
+  var fnl = b2(d, b + 28), efl = b2(d, b + 30), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl;
+  var _a2 = z64hs(d, es, efl, z6, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
+  return [b2(d, b + 10), sc, su, fn, es + efl + b2(d, b + 32), off];
+};
+var z64hs = function(d, b, l, z6, sc, su, off) {
+  var nsc = sc == 4294967295, nsu = su == 4294967295, noff = off == 4294967295, e = b + l;
+  var nf = nsc + nsu + noff;
+  if (z6 && nf) {
+    for (; b + 4 < e; b += 4 + b2(d, b + 2)) {
+      if (b2(d, b) == 1) {
+        return [
+          nsc ? b8(d, b + 4 + 8 * nsu) : sc,
+          nsu ? b8(d, b + 4) : su,
+          noff ? b8(d, b + 4 + 8 * (nsu + nsc)) : off,
+          1
+        ];
+      }
+    }
+    if (z6 < 2)
+      err(13);
+  }
+  return [sc, su, off, 0];
+};
+function unzipSync(data, opts) {
+  var files = {};
+  var e = data.length - 22;
+  for (; b4(data, e) != 101010256; --e) {
+    if (!e || data.length - e > 65558)
+      err(13);
+  }
+  ;
+  var c = b2(data, e + 8);
+  if (!c)
+    return {};
+  var o = b4(data, e + 16);
+  var z6 = b4(data, e - 20) == 117853008;
+  if (z6) {
+    var ze = b4(data, e - 12);
+    z6 = b4(data, ze) == 101075792;
+    if (z6) {
+      c = b4(data, ze + 32);
+      o = b4(data, ze + 48);
+    }
+  }
+  var fltr = opts && opts.filter;
+  for (var i = 0; i < c; ++i) {
+    var _a2 = zh(data, o, z6), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
+    o = no;
+    if (!fltr || fltr({
+      name: fn,
+      size: sc,
+      originalSize: su,
+      compression: c_2
+    })) {
+      if (!c_2)
+        files[fn] = slc(data, b, b + sc);
+      else if (c_2 == 8)
+        files[fn] = inflateSync(data.subarray(b, b + sc), { out: new u8(su) });
+      else
+        err(14, "unknown compression type " + c_2);
+    }
+  }
+  return files;
+}
+
+// src/recovery-archive.ts
+function safeOutputPath(projectDir, outputDir) {
+  if (outputDir.length === 0 || isAbsolute2(outputDir)) {
+    throw new SakupaError("invalid_request", "Recovery outputDir must be a relative directory");
+  }
+  const root = resolve3(projectDir);
+  const target = resolve3(root, outputDir);
+  const rel = relative(root, target);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute2(rel)) {
+    throw new SakupaError("invalid_request", "Recovery outputDir must stay inside projectDir");
+  }
+  if (rel === ".sakupa" || rel.startsWith(`.sakupa${sep2}`)) {
+    throw new SakupaError("invalid_request", "Recovery content cannot be written inside .sakupa");
+  }
+  return target;
+}
+function safeEntryName(name) {
+  if (name.length === 0 || name.startsWith("/") || name.includes("\\") || /^[A-Za-z]:/.test(name)) {
+    throw new SakupaError("validation_failed", `Unsafe recovery archive path: ${name}`);
+  }
+  const segments = name.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new SakupaError("validation_failed", `Unsafe recovery archive path: ${name}`);
+  }
+  return segments.join("/");
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+async function listExistingFiles(root, current = root) {
+  const entries = await readdir(current, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) {
+      throw new SakupaError("state_conflict", `Recovery output contains a symlink: ${entry.name}`);
+    }
+    const absolute = join3(current, entry.name);
+    if (entry.isDirectory()) files.push(...await listExistingFiles(root, absolute));
+    else if (entry.isFile()) files.push(relative(root, absolute).split(sep2).join("/"));
+    else
+      throw new SakupaError(
+        "state_conflict",
+        `Recovery output contains a special file: ${entry.name}`
+      );
+  }
+  return files.sort();
+}
+async function existingOutputMatches(outputDir, files) {
+  const existing = await listExistingFiles(outputDir);
+  const expected = Object.keys(files).sort();
+  if (existing.length !== expected.length || existing.some((name, i) => name !== expected[i])) {
+    return false;
+  }
+  for (const name of expected) {
+    const actual = await readFile(join3(outputDir, ...name.split("/")));
+    const wanted = files[name];
+    if (!wanted || actual.byteLength !== wanted.byteLength || !actual.equals(wanted)) return false;
+  }
+  return true;
+}
+async function extractRecoveryArchive(input) {
+  if (!Number.isSafeInteger(input.expectedBytes) || input.expectedBytes < 0 || input.expectedBytes > PAID_SITE_MAX_TOTAL_BYTES || !Number.isSafeInteger(input.expectedFiles) || input.expectedFiles < 0 || input.expectedFiles > MAX_FILE_COUNT) {
+    throw new SakupaError("validation_failed", "Recovery archive metadata exceeds product limits");
+  }
+  const outputDir = safeOutputPath(input.projectDir, input.outputDir ?? "html");
+  const maxArchiveBytes = input.expectedBytes + input.expectedFiles * 4096 + 65536;
+  if (input.archive.byteLength > maxArchiveBytes) {
+    throw new SakupaError("validation_failed", "Recovery archive is larger than its site metadata");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let declaredBytes = 0;
+  let declaredFiles = 0;
+  const files = unzipSync(input.archive, {
+    filter(file) {
+      const name = safeEntryName(file.name);
+      if (seen.has(name)) {
+        throw new SakupaError("validation_failed", `Duplicate recovery archive path: ${name}`);
+      }
+      seen.add(name);
+      declaredFiles += 1;
+      declaredBytes += file.originalSize;
+      if (declaredFiles > input.expectedFiles || declaredFiles > MAX_FILE_COUNT || declaredBytes > input.expectedBytes || declaredBytes > PAID_SITE_MAX_TOTAL_BYTES) {
+        throw new SakupaError("validation_failed", "Recovery archive exceeds declared site limits");
+      }
+      return true;
+    }
+  });
+  if (declaredFiles !== input.expectedFiles || declaredBytes !== input.expectedBytes) {
+    throw new SakupaError("validation_failed", "Recovery archive does not match site metadata");
+  }
+  if (await pathExists(outputDir)) {
+    const info = await stat(outputDir);
+    if (info.isDirectory() && await existingOutputMatches(outputDir, files)) {
+      return {
+        outputDir,
+        totalBytes: declaredBytes,
+        fileCount: declaredFiles,
+        alreadyPresent: true
+      };
+    }
+    throw new SakupaError(
+      "state_conflict",
+      `Recovery output already exists with different content: ${outputDir}. Move it aside or choose another outputDir.`
+    );
+  }
+  const tempDir = await mkdtemp(join3(resolve3(input.projectDir), ".sakupa-restore-"));
+  try {
+    let writtenBytes = 0;
+    const entries = Object.entries(files).sort(([a], [b]) => a.localeCompare(b));
+    for (const [rawName, data] of entries) {
+      const name = safeEntryName(rawName);
+      const destination = join3(tempDir, ...name.split("/"));
+      await mkdir(dirname2(destination), { recursive: true });
+      await writeFile(destination, data, { flag: "wx" });
+      writtenBytes += data.byteLength;
+    }
+    if (entries.length !== input.expectedFiles || writtenBytes !== input.expectedBytes) {
+      throw new SakupaError(
+        "validation_failed",
+        "Extracted recovery data does not match site metadata"
+      );
+    }
+    await mkdir(dirname2(outputDir), { recursive: true });
+    await rename(tempDir, outputDir);
+    return {
+      outputDir,
+      totalBytes: writtenBytes,
+      fileCount: entries.length,
+      alreadyPresent: false
+    };
+  } catch (error) {
+    await rm(tempDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
 // src/creation-registry.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join3 } from "node:path";
+import { dirname as dirname3, join as join4 } from "node:path";
 var RECENT_WINDOW_MS = FREE_SITE_TTL_HOURS * 60 * 60 * 1e3;
 function creationRegistryPath() {
   const base = process.env["SAKUPA_STATE_DIR"] ?? homedir2();
-  return join3(base, ".sakupa", "created-sites.json");
+  return join4(base, ".sakupa", "created-sites.json");
 }
 function readAll() {
   const path = creationRegistryPath();
@@ -1435,7 +2140,7 @@ function readAll() {
 }
 function writeAll(records) {
   const path = creationRegistryPath();
-  mkdirSync2(dirname2(path), { recursive: true });
+  mkdirSync2(dirname3(path), { recursive: true });
   writeFileSync2(path, `${JSON.stringify(records, null, 2)}
 `, "utf-8");
 }
@@ -1664,7 +2369,7 @@ function ensureUploadSizeWithinLimits(manifest, isFirstFreeDeploy) {
 async function buildHashedManifest(files, outputAbs) {
   const manifest = [];
   for (const file of files) {
-    const bytes = new Uint8Array(await fs2.readFile(join4(outputAbs, file.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join5(outputAbs, file.path)));
     manifest.push({ path: file.path, size: file.size, contentHash: await sha256Hex(bytes) });
   }
   return manifest;
@@ -1683,7 +2388,7 @@ async function uploadAll(ctx, targets, files, outputAbs) {
         `No local file matches upload target "${target.path}"; aborting upload.`
       );
     }
-    const bytes = new Uint8Array(await fs2.readFile(join4(outputAbs, match.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join5(outputAbs, match.path)));
     if (bytes.byteLength !== match.size) {
       throw new SakupaError(
         "validation_failed",
@@ -1727,15 +2432,15 @@ ${block}`, checklist: toDnsChecklist(diag.checks) };
   }
 }
 function projectRootAbove(projectDir) {
-  if (existsSync3(join4(projectDir, "package.json"))) return null;
-  return findAncestor(projectDir, (dir) => existsSync3(join4(dir, "package.json")), 4);
+  if (existsSync3(join5(projectDir, "package.json"))) return null;
+  return findAncestor(projectDir, (dir) => existsSync3(join5(dir, "package.json")), 4);
 }
 function findNeighborBinding(projectDir, outputRel) {
   const bound = (dir) => loadSiteFile(dir).kind !== "absent";
   const above = findAncestor(projectDir, bound, 3);
   if (above) return above;
   if (outputRel && outputRel !== ".") {
-    const outputAbs = resolve3(projectDir, outputRel);
+    const outputAbs = resolve4(projectDir, outputRel);
     if (bound(outputAbs)) return outputAbs;
   }
   return null;
@@ -1818,7 +2523,7 @@ Next action: ${analysis.suggestedNextAction}`,
           return notDeployableResult(analysis);
         }
         const files = analysis.files;
-        const outputAbs = resolve3(ctx.projectDir, analysis.recommendedOutputDir ?? ".");
+        const outputAbs = resolve4(ctx.projectDir, analysis.recommendedOutputDir ?? ".");
         const manifest = await buildHashedManifest(files, outputAbs);
         const siteFileState = loadSiteFile(ctx.projectDir);
         if (siteFileState.kind === "corrupted") {
@@ -2295,25 +3000,126 @@ Full status:`, res);
   server.registerTool(
     "recover",
     {
-      description: "Recover management control of a subscribed site WITH A BOUND CUSTOM DOMAIN after losing the local project, by proving DNS control of the apex domain. Sites without a bound domain are identified solely by their local credential and cannot be recovered. By default, completing recovery REVOKES all previous local credentials. Call first with the hostname to get the DNS record, then again with verificationId to complete recovery (writes a new .sakupa/site.json and returns a download link for the current site content).",
+      description: "Recover management control of a subscribed site WITH A BOUND CUSTOM DOMAIN after losing the local project, by proving DNS control of the apex domain. Sites without a bound domain are identified solely by their local credential and cannot be recovered. By default, completing recovery REVOKES all previous local credentials. Recovery is resumable: start stores local pending state; complete installs and writes the new .sakupa/site.json credential BEFORE requesting content; download uses that credential to reissue an archive and safely extract it into html without repeating DNS.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
         projectDir: projectDirInput,
-        action: z3.enum(["start", "status", "complete"]),
+        action: z3.enum(["start", "status", "complete", "download"]),
         hostname: z3.string().optional().describe("Required for start."),
-        verificationId: z3.string().optional().describe("Required for status or complete."),
+        verificationId: z3.string().optional().describe("For status or complete; inferred from local recovery state when omitted."),
+        outputDir: z3.string().optional().describe("Relative extraction directory for complete/download (default: html)."),
         preserveExistingCredentials: z3.boolean().optional().describe("Explicitly keep old local credentials working (default: revoke them all).")
       }
     },
     async (args) => {
       try {
         const ctx = withProjectDir(baseCtx, args.projectDir);
+        const localSite = loadSiteFile(ctx.projectDir);
+        const localCredentialIsActive = async () => {
+          if (localSite.kind !== "ok") return false;
+          try {
+            await ctx.client.getSiteStatus(localSite.file.siteId, localSite.file.credential);
+            return true;
+          } catch (error) {
+            if (isSakupaError(error) && error.code === "unauthorized") return false;
+            throw error;
+          }
+        };
+        const download = async () => {
+          const site = requireSiteFile(ctx);
+          const archive = await ctx.client.getSiteArchive(site.siteId, site.credential);
+          const bytes = await ctx.client.downloadArchive(archive.archiveUrl);
+          const extracted = await extractRecoveryArchive({
+            projectDir: ctx.projectDir,
+            ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {},
+            archive: bytes,
+            expectedBytes: archive.totalBytes,
+            expectedFiles: archive.fileCount
+          });
+          deleteRecoveryFile(ctx.projectDir);
+          return { archive, extracted };
+        };
+        if (args.action === "download") {
+          const { archive, extracted } = await download();
+          return text(
+            "recovery_content_downloaded",
+            `Recovered site content with the credential in .sakupa/site.json.
+Output directory: ${extracted.outputDir}
+Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
+No DNS verification was started or repeated.`,
+            {
+              siteId: archive.siteId,
+              outputDir: extracted.outputDir,
+              fileCount: extracted.fileCount,
+              totalBytes: extracted.totalBytes,
+              alreadyPresent: extracted.alreadyPresent,
+              credentialUsedFromLocalFile: true,
+              dnsVerificationRepeated: false
+            }
+          );
+        }
         if (args.action === "start") {
+          if (localSite.kind === "ok" && await localCredentialIsActive()) {
+            return structuredToolResult({
+              schemaVersion: 1,
+              outcome: "completed",
+              resultCode: "recovery_credential_already_present",
+              summary: "A valid .sakupa/site.json already exists. Management authority is restored; do not start another TXT recovery. Continue with recover download.",
+              data: {
+                siteId: localSite.file.siteId,
+                credentialStoredLocally: true,
+                dnsVerificationRepeated: false
+              },
+              nextActions: [
+                {
+                  tool: "recover",
+                  arguments: {
+                    projectDir: ctx.projectDir,
+                    action: "download",
+                    outputDir: args.outputDir ?? "html"
+                  },
+                  allowed: true
+                }
+              ]
+            });
+          }
+          if (localSite.kind === "corrupted") {
+            throw new SakupaError(
+              "state_conflict",
+              `Cannot start recovery while .sakupa/site.json is damaged: ${localSite.problem}`
+            );
+          }
+          const pending2 = loadRecoveryFile(ctx.projectDir);
+          if (pending2) {
+            return structuredToolResult({
+              schemaVersion: 1,
+              outcome: "waiting_user",
+              resultCode: "domain_recovery_local_state_found",
+              summary: "A resumable DNS recovery already exists in this project. Do not create another TXT challenge; continue the stored verification.",
+              data: { verificationId: pending2.verificationId, resumable: true },
+              nextActions: [
+                {
+                  tool: "recover",
+                  arguments: {
+                    projectDir: ctx.projectDir,
+                    action: "status",
+                    verificationId: pending2.verificationId
+                  },
+                  allowed: true
+                }
+              ]
+            });
+          }
           if (!args.hostname) {
             throw new SakupaError("invalid_request", "hostname is required for start");
           }
           const res2 = await ctx.client.recoverDomain({ hostname: args.hostname });
+          writeRecoveryFile(ctx.projectDir, {
+            verificationId: res2.verificationId,
+            credential: generateCredential(),
+            createdAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
           const txtShort = shortHostFor(res2.verificationRecord.name, res2.apexDomain);
           return text(
             "domain_recovery_started",
@@ -2347,19 +3153,48 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
                   value: res2.verificationRecord.value
                 }
               ],
-              revokesPreviousCredentialsByDefault: true
+              revokesPreviousCredentialsByDefault: true,
+              localRecoveryStateStored: true
             },
             "waiting_user"
           );
         }
-        if (!args.verificationId) {
+        if (localSite.kind === "ok" && args.action === "status" && await localCredentialIsActive()) {
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "completed",
+            resultCode: "recovery_credential_already_present",
+            summary: "The recovered credential is already stored in .sakupa/site.json. Resume content download with the local key; DNS recovery must not be repeated.",
+            data: { siteId: localSite.file.siteId, credentialStoredLocally: true },
+            nextActions: [
+              {
+                tool: "recover",
+                arguments: {
+                  projectDir: ctx.projectDir,
+                  action: "download",
+                  outputDir: args.outputDir ?? "html"
+                },
+                allowed: true
+              }
+            ]
+          });
+        }
+        const pending = loadRecoveryFile(ctx.projectDir);
+        const verificationId = args.verificationId ?? pending?.verificationId;
+        if (!verificationId) {
           throw new SakupaError(
             "invalid_request",
-            "verificationId is required for status or complete"
+            "verificationId is required because no local resumable recovery state exists"
+          );
+        }
+        if (pending && pending.verificationId !== verificationId) {
+          throw new SakupaError(
+            "state_conflict",
+            "The supplied verificationId differs from this project\u2019s stored recovery state."
           );
         }
         if (args.action === "status") {
-          const res2 = await ctx.client.getRecoveryStatus(args.verificationId);
+          const res2 = await ctx.client.getRecoveryStatus(verificationId);
           return structuredToolResult({
             schemaVersion: 1,
             outcome: res2.status === "expired" ? "expired" : res2.readyToComplete ? "completed" : "pending_provider",
@@ -2369,14 +3204,29 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
             nextActions: [
               {
                 tool: "recover",
-                arguments: { action: "complete", verificationId: args.verificationId },
+                arguments: {
+                  projectDir: ctx.projectDir,
+                  action: "complete",
+                  verificationId,
+                  outputDir: args.outputDir ?? "html"
+                },
                 allowed: res2.readyToComplete,
                 ...res2.readyToComplete ? {} : { reasonCode: res2.status }
               }
             ]
           });
         }
-        const res = await ctx.client.completeRecovery(args.verificationId, {
+        const recoveryState = pending ?? (() => {
+          const created = {
+            verificationId,
+            credential: generateCredential(),
+            createdAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          writeRecoveryFile(ctx.projectDir, created);
+          return created;
+        })();
+        const res = await ctx.client.completeRecovery(verificationId, {
+          credential: recoveryState.credential,
           ...args.preserveExistingCredentials !== void 0 ? { preserveExistingCredentials: args.preserveExistingCredentials } : {}
         });
         writeSiteFile(
@@ -2384,31 +3234,63 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
           {
             siteId: res.siteId,
             ...res.boundHostnames[0] !== void 0 ? { boundDomain: res.boundHostnames[0] } : {},
-            credential: res.credential,
+            credential: recoveryState.credential,
             createdAt: (/* @__PURE__ */ new Date()).toISOString(),
             apiBaseUrl: ctx.apiBaseUrl
           },
           { allowReplace: true }
         );
-        return text(
-          "domain_recovery_completed",
-          `Recovery complete.
+        deleteRecoveryFile(ctx.projectDir);
+        try {
+          const { archive, extracted } = await download();
+          return text(
+            "domain_recovery_completed",
+            `Recovery complete.
 Site: ${res.siteId} (hostnames: ${res.boundHostnames.join(", ") || "(none)"})
 Previous credentials revoked: ${res.revokedPreviousCredentials ? "YES" : "no (preserved on request)"}
 
-A NEW management credential was written to .sakupa/site.json in this project \u2014 this project now manages the site.
-` + credentialGitReminder(ctx.projectDir) + `
-Download the current site content (signed URL):
-${res.archiveUrl}`,
-          {
-            siteId: res.siteId,
-            boundHostnames: res.boundHostnames,
-            revokedPreviousCredentials: res.revokedPreviousCredentials,
-            archiveUrl: res.archiveUrl,
-            archiveExpiresAt: res.archiveExpiresAt,
-            credentialStoredLocally: true
-          }
-        );
+The NEW management credential was written to .sakupa/site.json before content download. The site archive was then requested with that key and extracted.
+Output directory: ${extracted.outputDir}
+Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
+` + credentialGitReminder(ctx.projectDir),
+            {
+              siteId: res.siteId,
+              boundHostnames: res.boundHostnames,
+              revokedPreviousCredentials: res.revokedPreviousCredentials,
+              archiveExpiresAt: archive.archiveExpiresAt,
+              outputDir: extracted.outputDir,
+              fileCount: extracted.fileCount,
+              totalBytes: extracted.totalBytes,
+              alreadyPresent: extracted.alreadyPresent,
+              credentialStoredLocally: true,
+              archiveRequestedWithRecoveredCredential: true
+            }
+          );
+        } catch (downloadError) {
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "waiting_user",
+            resultCode: "recovery_credential_restored_download_pending",
+            summary: `Management authority was restored and .sakupa/site.json is safely written, but content download did not finish (${downloadError instanceof Error ? downloadError.message : String(downloadError)}). Do not repeat DNS recovery; run recover download in this project.`,
+            data: {
+              siteId: res.siteId,
+              credentialStoredLocally: true,
+              contentDownloadCompleted: false,
+              dnsVerificationRepeated: false
+            },
+            nextActions: [
+              {
+                tool: "recover",
+                arguments: {
+                  projectDir: ctx.projectDir,
+                  action: "download",
+                  outputDir: args.outputDir ?? "html"
+                },
+                allowed: true
+              }
+            ]
+          });
+        }
       } catch (e) {
         return toolError(e);
       }
@@ -2725,6 +3607,8 @@ Workflow:
    Plan changes are confirmed only on Stripe and synchronized by Stripe webhook.
    A cancellation keeps the site paid through the current period. Sakupa reverts it to a free
    24h site and removes paid data after Stripe sends the signed final-cancellation webhook.
+   Recovery writes the new local credential before downloading content. If a session stops after
+   .sakupa/site.json exists, NEVER repeat DNS recovery: resume with recover action "download".
 5. support (subscribed sites) opens a support ticket; report sends a
    sanitized diagnostic report after the user explicitly confirms it.