pi-webdav-backup 1.0.0

package/extensions/webdav-backup/migrate.mjs

@@ -0,0 +1,167 @@
+/**
+ * migrate.mjs — 把配置里的明文密钥迁移为安全引用
+ *
+ * 迁移策略：
+ *   plain  →  dpapi:<名称>      （Windows，推荐：本机本用户可解，无主密码）
+ *   plain  →  $ENV_VAR          （跨平台，写入用户级环境变量）
+ *   plain  →  file:<路径>        （写入 0600 权限的独立文件）
+ *
+ * 迁移后原配置文件只保留引用字符串，明文不再落盘。
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { configPath, getAgentDir } from "./config-paths.mjs";
+import {
+  setDpapiSecret,
+  dpapiAvailable,
+  setUserEnvVar,
+  DPAPI_SCHEME,
+  FILE_SCHEME,
+} from "./secrets.mjs";
+
+const ENV_PASSWORD = "PI_WEBDAV_BACKUP_PASSWORD";
+const ENV_KEY = "PI_WEBDAV_BACKUP_KEY";
+const DPAPI_PASSWORD_NAME = "webdav-password";
+const DPAPI_KEY_NAME = "backup-key";
+
+function stripBom(t) {
+  return t.replace(/^\uFEFF/, "");
+}
+
+/** 判断配置里的值是否为明文（需要迁移） */
+function needsMigration(v) {
+  if (typeof v !== "string") return false;
+  const t = v.trim();
+  if (!t) return false;
+  if (
+    t.startsWith(DPAPI_SCHEME) ||
+    t.startsWith(FILE_SCHEME) ||
+    t.startsWith("plain:") ||
+    t.startsWith("!")
+  ) {
+    return false;
+  }
+  if (t.includes("$")) return false;
+  return true;
+}
+
+function backupFile(p) {
+  if (!existsSync(p)) return null;
+  const dest = `${p}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  copyFileSync(p, dest);
+  return dest;
+}
+
+/**
+ * 执行迁移。
+ * @param {object} opts
+ * @param {"dpapi"|"env"|"file"} opts.method
+ * @param {(s: string) => void} opts.log
+ * @param {boolean} [opts.dryRun]
+ */
+export async function migrateSecrets({ method = "dpapi", log = () => {}, dryRun = false } = {}) {
+  const p = configPath();
+  if (!existsSync(p)) {
+    return { ok: false, error: `配置文件不存在：${p}` };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(stripBom(readFileSync(p, "utf8")));
+  } catch (e) {
+    return { ok: false, error: `配置文件不是合法 JSON：${e.message}` };
+  }
+
+  const remote = raw.remote ?? {};
+  const changes = [];
+
+  const plan = [];
+  if (needsMigration(remote.password)) {
+    plan.push({ field: "remote.password", value: remote.password.trim(), kind: "password" });
+  }
+  if (needsMigration(raw.encryptKey)) {
+    plan.push({ field: "encryptKey", value: raw.encryptKey.trim(), kind: "key" });
+  }
+
+  if (plan.length === 0) {
+    return { ok: true, migrated: 0, message: "配置中没有明文密钥，无需迁移" };
+  }
+
+  if (method === "dpapi" && !dpapiAvailable()) {
+    return { ok: false, error: "DPAPI 仅支持 Windows；请改用 --method env 或 --method file" };
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      wouldMigrate: plan.map((x) => ({ field: x.field, method, target: method === "env" ? (x.kind === "password" ? ENV_PASSWORD : ENV_KEY) : method === "dpapi" ? `${DPAPI_SCHEME}${x.kind === "password" ? DPAPI_PASSWORD_NAME : DPAPI_KEY_NAME}` : `${FILE_SCHEME}secrets/${x.kind}.txt` })),
+    };
+  }
+
+  // 先备份原文件，再逐项迁移
+  const backup = backupFile(p);
+  if (backup) log(`已备份原配置：${backup}`);
+
+  const secretsDir = join(getAgentDir(), "secrets");
+
+  for (const item of plan) {
+    if (method === "dpapi") {
+      const name = item.kind === "password" ? DPAPI_PASSWORD_NAME : DPAPI_KEY_NAME;
+      setDpapiSecret(name, item.value);
+      const ref = `${DPAPI_SCHEME}${name}`;
+      if (item.kind === "password") remote.password = ref;
+      else raw.encryptKey = ref;
+      changes.push({ field: item.field, to: ref });
+      log(`已用 DPAPI 加密保存并替换 ${item.field} → ${ref}`);
+      continue;
+    }
+
+    if (method === "env") {
+      const envName = item.kind === "password" ? ENV_PASSWORD : ENV_KEY;
+      const r = setUserEnvVar(envName, item.value);
+      const ref = `$${envName}`;
+      if (item.kind === "password") remote.password = ref;
+      else raw.encryptKey = ref;
+      changes.push({ field: item.field, to: ref, note: r.note });
+      log(r.ok ? `已写入用户环境变量 ${envName}，并替换 ${item.field} → ${ref}` : `请手动设置 ${envName}；配置已改为 ${ref}`);
+      continue;
+    }
+
+    if (method === "file") {
+      mkdirSync(secretsDir, { recursive: true });
+      const file = join(secretsDir, `${item.kind}.txt`);
+      writeFileSync(file, item.value, { encoding: "utf8", mode: 0o600 });
+      try {
+        chmodSync(file, 0o600);
+      } catch {
+        /* ignore */
+      }
+      const ref = `${FILE_SCHEME}${file}`;
+      if (item.kind === "password") remote.password = ref;
+      else raw.encryptKey = ref;
+      changes.push({ field: item.field, to: ref });
+      log(`已写入 ${file}（0600）并替换 ${item.field} → ${ref}`);
+      continue;
+    }
+
+    return { ok: false, error: `未知迁移方式：${method}` };
+  }
+
+  raw.remote = remote;
+  writeFileSync(p, JSON.stringify(raw, null, 2), { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(p, 0o600);
+  } catch {
+    /* ignore */
+  }
+
+  // 迁移到 file 方式时提醒保护目录
+  if (method === "file") {
+    log(`注意：${secretsDir} 内为明文密钥文件，请确保该目录不被同步/备份到不可信位置。`);
+  }
+
+  return { ok: true, migrated: changes.length, method, changes, backup };
+}

package/extensions/webdav-backup/restore.mjs

@@ -0,0 +1,220 @@
+/**
+ * restore.mjs — 从 WebDAV 恢复备份
+ *
+ * 支持两种远端布局：
+ *   - 归档：<remoteDir>/<remoteName>-<时间戳>.tar.gz[.pibak]
+ *         → 下载、解压（必要时先解密）、解包 tar 到目标目录
+ *   - 快照：<remoteDir>/<remoteName>/ 逐文件下载
+ *
+ * 安全：解包时拒绝绝对路径与 .. 穿越；默认恢复到临时目录而非直接覆盖 ~/.pi/agent。
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+  createReadStream,
+  createWriteStream as createWriteStreamImpl,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { createGunzip } from "node:zlib";
+import { pipeline } from "node:stream/promises";
+
+import { WebDAVClient } from "./webdav.mjs";
+import { archiveNameRe } from "./backup.mjs";
+import { decryptFile } from "./crypto.mjs";
+import { extractTar } from "./tar.mjs";
+
+/** 列出远端可恢复的备份（归档 + 快照目录） */
+export async function listBackups(config) {
+  const client = new WebDAVClient({
+    baseUrl: config.url,
+    username: config.username,
+    password: config.password,
+    timeoutMs: config.timeoutMs,
+    insecureTls: config.insecureTls,
+  });
+  const entries = await client.list(config.remoteDir);
+  const isArchive = archiveNameRe(config.remoteName);
+  const archives = entries
+    .filter((e) => !e.isCollection && isArchive.test(e.name))
+    .sort((a, b) => (a.name < b.name ? 1 : -1))
+    .map((e) => ({ type: "archive", name: e.name, size: e.size, lastModified: e.lastModified }));
+
+  const snapDir = `${config.remoteDir}/${config.remoteName}`;
+  let snapshot = null;
+  try {
+    const m = await client.get(`${snapDir}/manifest.json`);
+    if (m) {
+      const manifest = JSON.parse(m.toString("utf8"));
+      snapshot = {
+        type: "snapshot",
+        name: `${config.remoteName}/`,
+        remoteDir: snapDir,
+        fileCount: manifest.fileCount ?? manifest.files?.length ?? 0,
+        createdAt: manifest.createdAt ?? manifest.updatedAt,
+      };
+    }
+  } catch {
+    /* 无快照 */
+  }
+
+  return { archives, snapshot, all: snapshot ? [...archives, snapshot] : archives };
+}
+
+/**
+ * 恢复。
+ * @param {object} config
+ * @param {object} opts
+ * @param {string} opts.agentDir
+ * @param {string|null} opts.file  指定归档名；null 则恢复最新
+ * @param {string|null} opts.to    目标目录；null 则解到临时目录
+ * @param {boolean} opts.listOnly  只列出不下载
+ * @param {(s: string) => void} opts.log
+ */
+export async function restoreBackup(config, opts) {
+  const log = opts.log ?? (() => {});
+  const client = new WebDAVClient({
+    baseUrl: config.url,
+    username: config.username,
+    password: config.password,
+    timeoutMs: config.timeoutMs,
+    insecureTls: config.insecureTls,
+  });
+
+  const listing = await listBackups(config);
+  if (opts.listOnly) {
+    return { ok: true, listOnly: true, ...listing };
+  }
+
+  if (listing.all.length === 0) {
+    return { ok: false, error: `远端 ${config.remoteDir}/ 下找不到可恢复的备份` };
+  }
+
+  // 选择目标
+  let target = null;
+  if (opts.file) {
+    target = listing.archives.find((a) => a.name === opts.file) ?? null;
+    if (!target && opts.file.replace(/\/$/, "") === config.remoteName) target = listing.snapshot;
+    if (!target) {
+      return {
+        ok: false,
+        error: `找不到指定的备份：${opts.file}`,
+        available: listing.all.map((x) => x.name),
+      };
+    }
+  } else {
+    target = listing.archives[0] ?? listing.snapshot;
+  }
+
+  const workDir = mkdtempSync(join(tmpdir(), "pi-restore-"));
+  const destDir = opts.to ?? join(workDir, "restored");
+  mkdirSync(destDir, { recursive: true });
+
+  try {
+    if (target.type === "snapshot") {
+      return await restoreSnapshot({ client, config, target, destDir, log, workDir });
+    }
+    return await restoreArchive({ client, config, target, destDir, log, workDir });
+  } finally {
+    // 只在未指定目标目录时保留临时目录（用户需要去那里取文件）
+    if (!opts.to) {
+      log(`（临时文件保留在 ${workDir}，确认后可自行删除）`);
+    } else {
+      try {
+        rmSync(workDir, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+async function restoreArchive({ client, config, target, destDir, log, workDir }) {
+  const remotePath = `${config.remoteDir}/${target.name}`;
+  log(`下载 ${target.name} …`);
+  const blob = await client.get(remotePath);
+  if (!blob) return { ok: false, error: `下载失败：${remotePath} 不存在` };
+
+  const downloaded = join(workDir, target.name);
+  writeFileSync(downloaded, blob);
+  log(`已下载 ${(blob.length / 1024 / 1024).toFixed(2)} MB`);
+
+  let tarball = downloaded;
+  let header = null;
+  if (target.name.endsWith(".pibak")) {
+    if (!config.encryptKey) {
+      return {
+        ok: false,
+        error: "该备份是加密的，但配置里没有 encryptKey（或环境变量 PI_WEBDAV_BACKUP_KEY）",
+      };
+    }
+    log("解密中…");
+    const decFile = join(workDir, "payload.tar.gz");
+    const res = await decryptFile(downloaded, decFile, String(config.encryptKey));
+    header = res.header;
+    tarball = decFile;
+    if (header?.name && header.name !== target.name) {
+      log(`注意：归档头部记录的文件名是 ${header.name}`);
+    }
+  }
+
+  log("解压中…");
+  const rawTar = join(workDir, "payload.tar");
+  await pipeline(createReadStream(tarball), createGunzip({ chunkSize: 1024 * 1024 }), createWriteStreamImpl(rawTar));
+
+  log("解包中…");
+  const entries = await extractTar(rawTar, destDir);
+  const fileCount = entries.filter((e) => !e.dir).length;
+  log(`恢复完成：${fileCount} 个文件 → ${destDir}`);
+
+  return {
+    ok: true,
+    mode: "archive",
+    source: target.name,
+    dest: destDir,
+    files: fileCount,
+    encrypted: target.name.endsWith(".pibak"),
+    header,
+  };
+}
+
+async function restoreSnapshot({ client, config, target, destDir, log, workDir }) {
+  const manifestRaw = await client.get(`${target.remoteDir}/manifest.json`);
+  if (!manifestRaw) return { ok: false, error: "快照缺少 manifest.json" };
+  const manifest = JSON.parse(manifestRaw.toString("utf8"));
+  const files = manifest.files ?? [];
+
+  log(`快照包含 ${files.length} 个文件，开始下载…`);
+  let done = 0;
+  const failed = [];
+
+  for (const f of files) {
+    const buf = await client.get(`${target.remoteDir}/${f.rel}`);
+    if (!buf) {
+      failed.push(f.rel);
+      continue;
+    }
+    // 防穿越
+    const parts = String(f.rel).split("/").filter((s) => s && s !== "." && s !== "..");
+    const outPath = join(destDir, ...parts);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, buf);
+    done++;
+    if (done % 20 === 0) log(`  已恢复 ${done}/${files.length}`);
+  }
+
+  log(`恢复完成：${done} 个文件 → ${destDir}${failed.length ? `（${failed.length} 个失败）` : ""}`);
+  return {
+    ok: failed.length === 0,
+    mode: "snapshot",
+    source: target.name,
+    dest: destDir,
+    files: done,
+    failed,
+  };
+}

package/extensions/webdav-backup/run-tests.mjs

@@ -0,0 +1,41 @@
+/**
+ * run-tests.mjs — 依次运行所有测试文件并汇总
+ */
+import { spawn } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const files = readdirSync(here)
+  .filter((f) => /^test.*\.mjs$/.test(f) && f !== "run-tests.mjs")
+  .sort();
+
+let failed = 0;
+const summary = [];
+
+for (const f of files) {
+  const started = Date.now();
+  const res = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(here, f)], { cwd: here, windowsHide: true });
+    let out = "";
+    child.stdout.on("data", (d) => (out += d.toString("utf8")));
+    child.stderr.on("data", (d) => (out += d.toString("utf8")));
+    child.on("close", (code) => resolve({ code, out }));
+  });
+  const ms = Date.now() - started;
+  const failLines = res.out.split("\n").filter((l) => l.includes("❌"));
+  const resultLine = res.out.split("\n").filter((l) => /^结果：/.test(l)).pop() ?? "";
+  if (res.code !== 0) failed++;
+  summary.push(
+    `${res.code === 0 ? "✅" : "❌"} ${f.padEnd(20)} ${resultLine || "(no summary)"}  ${(ms / 1000).toFixed(1)}s`,
+  );
+  if (failLines.length) summary.push(...failLines.map((l) => `      ${l.trim()}`));
+  if (res.code !== 0 && !resultLine) {
+    summary.push("      " + res.out.split("\n").slice(0, 12).join("\n      "));
+  }
+}
+
+console.log(summary.join("\n"));
+console.log(`\n${files.length} 个测试文件，${failed} 个失败`);
+process.exit(failed ? 1 : 0);