pi-webdav-backup 1.0.0

package/extensions/webdav-backup/config.mjs

@@ -0,0 +1,199 @@
+/**
+ * config.mjs — 配置读取与校验
+ *
+ * 配置文件：~/.pi/agent/webdav-backup.json
+ * 兼容：环境变量 PI_WEBDAV_BACKUP_PASSWORD / PI_WEBDAV_BACKUP_PASS / PI_WEBDAV_BACKUP_KEY
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { resolveSecret, isPlaintextSecret, dpapiAvailable } from "./secrets.mjs";
+import {
+  AGENT_DIR_ENV,
+  resolveAgentDir,
+  getAgentDir,
+  configPath,
+  statePath,
+  logPath,
+} from "./config-paths.mjs";
+
+export { AGENT_DIR_ENV, resolveAgentDir, getAgentDir, configPath, statePath, logPath };
+
+function stripBom(text) {
+  return text.replace(/^\uFEFF/, "");
+}
+
+const DEFAULT_EXCLUDE = [
+  "tmp/**",
+  "web-search-cache/**",
+  "npm/node_modules/**",
+  "sessions/**",
+  "**/*.log",
+  "**/node_modules/**",
+  // 密钥相关，绝不能进备份
+  "secrets/**",
+  "secrets.dpapi.json",
+  // 迁移/编辑留下的备份副本可能含明文密钥
+  "**/*.bak-*",
+  "**/*.bak",
+  "**/*.orig",
+  "**/*.old",
+  "**/*.save",
+];
+
+/**
+ * 读取配置。返回 { ok, config, errors, warnings, raw }
+ */
+export function loadConfig() {
+  const errors = [];
+  const warnings = [];
+  const p = configPath();
+
+  if (!existsSync(p)) {
+    return {
+      ok: false,
+      config: null,
+      errors: [`配置文件不存在：${p}`],
+      warnings,
+      raw: null,
+    };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(stripBom(readFileSync(p, "utf8")));
+  } catch (e) {
+    return {
+      ok: false,
+      config: null,
+      errors: [`配置文件不是合法 JSON：${e.message}`],
+      warnings,
+      raw: null,
+    };
+  }
+
+  const remote = raw.remote ?? raw.webdav ?? {};
+
+  // ── 解析密钥引用（不明文落盘）
+  // password 回退链：配置值 → 专用环境变量
+  const passwordRaw =
+    remote.password ??
+    process.env.PI_WEBDAV_BACKUP_PASSWORD ??
+    process.env.PI_WEBDAV_BACKUP_PASS ??
+    "";
+  const passwordRes = resolveSecret(passwordRaw, { allowCommand: true, allowPlain: true });
+
+  const keyRaw = raw.encryptKey ?? process.env.PI_WEBDAV_BACKUP_KEY ?? "";
+  const keyRes = resolveSecret(keyRaw, { allowCommand: true, allowPlain: true });
+
+  const config = {
+    enabled: raw.enabled !== false,
+    url: String(remote.url ?? "").trim(),
+    username: String(remote.username ?? "").trim(),
+    password: passwordRes.value ?? "",
+    passwordSource: passwordRes.source,
+    remoteDir: String(remote.remoteDir ?? raw.remoteDir ?? "pi-backup").replace(/^\/+|\/+$/g, ""),
+    remoteName: String(remote.remoteName ?? raw.remoteName ?? "pi-agent").trim(),
+    scope: Array.isArray(raw.scope) && raw.scope.length > 0 ? raw.scope.map(String) : ["."],
+    exclude: Array.isArray(raw.exclude)
+      ? [...DEFAULT_EXCLUDE, ...raw.exclude.map(String)]
+      : DEFAULT_EXCLUDE,
+    includeSessions: raw.includeSessions === true,
+    snapshot: raw.snapshot === true,
+    encrypt: raw.encrypt === true,
+    encryptKey: keyRes.value ?? null,
+    encryptKeySource: keyRes.source,
+    backupOnExit: raw.backupOnExit !== false,
+    backupOnExitMinIntervalMinutes: Number(raw.backupOnExitMinIntervalMinutes ?? 30),
+    backupOnExitTimeoutMs: Number(raw.backupOnExitTimeoutMs ?? 10 * 60 * 1000),
+    timeoutMs: Number(raw.timeoutMs ?? 60_000),
+    insecureTls: raw.insecureTls === true,
+    keepVersions: Number(raw.keepVersions ?? 10),
+  };
+
+  if (!config.url) errors.push("缺少 remote.url（WebDAV 地址）");
+  else if (!/^https?:\/\//i.test(config.url)) errors.push("remote.url 必须以 http:// 或 https:// 开头");
+
+  // 密钥解析错误直接阻断（否则会拿空密码去连）
+  if (passwordRes.error) errors.push(`remote.password 解析失败：${passwordRes.error}`);
+  if (keyRes.error) errors.push(`encryptKey 解析失败：${keyRes.error}`);
+
+  // 明文告警
+  if (isPlaintextSecret(passwordRaw)) {
+    warnings.push(
+      "remote.password 是明文，建议改为 dpapi:webdav-password" +
+        (dpapiAvailable() ? "（/backup-setup 可自动转换）" : " 或 $PI_WEBDAV_BACKUP_PASSWORD"),
+    );
+  }
+  if (passwordRaw && isPlaintextSecret(passwordRaw) === false && passwordRes.source === "env") {
+    // 来自环境变量，无需告警
+  }
+
+  if (config.username && !config.password) {
+    const hint = passwordRaw
+      ? `（已配置 remote.password 引用但解析为空，来源：${passwordRes.source}）`
+      : "（可设置 remote.password 为 dpapi:名称，或环境变量 PI_WEBDAV_BACKUP_PASSWORD）";
+    warnings.push(`配置了 username 但没有可用 password ${hint}`);
+  }
+  if (!config.username && !config.password) {
+    warnings.push("未配置用户名/密码，将以匿名方式连接（部分服务端会拒绝）");
+  }
+
+  if (config.encrypt && !config.encryptKey) {
+    errors.push("encrypt 为 true，但缺少可用 encryptKey（可设为 dpapi:名称 或 $PI_WEBDAV_BACKUP_KEY）");
+  }
+  if (config.encryptKey && String(config.encryptKey).length < 16) {
+    errors.push("encryptKey 至少需要 16 个字符");
+  }
+  if (config.encryptKey && isPlaintextSecret(keyRaw)) {
+    warnings.push("encryptKey 是明文，建议改为 dpapi:backup-key");
+  }
+
+  return { ok: errors.length === 0, config, errors, warnings, raw, secrets: { passwordSource: passwordRes.source, encryptKeySource: keyRes.source, passwordWarning: passwordRes.warning, encryptKeyWarning: keyRes.warning } };
+}
+
+/** 生成一份带注释的配置模板（写盘时用，JSON 不支持注释故存为 _ 前缀键） */
+export function configTemplate() {
+  return {
+    _说明: "pi WebDAV 备份配置。修改后运行 /reload 或 /backup-setup 生效。",
+    enabled: true,
+    remote: {
+      _说明_url: "WebDAV 服务地址，例如坚果云 https://dav.jianguoyun.com/dav/",
+      url: "",
+      _说明_username: "登录邮箱 / 用户名",
+      username: "",
+      _说明_password:
+        "密钥引用，推荐 dpapi:webdav-password（Windows 用户级加密，无需主密码）；也可 $ENV_VAR 或 file:路径。留空则读环境变量 PI_WEBDAV_BACKUP_PASSWORD",
+      password: "",
+      _说明_remoteDir: "远端保存目录",
+      remoteDir: "pi-backup",
+      _说明_remoteName: "本次备份的目录名（生成 pi-agent-<时间戳>.tar.gz）",
+      remoteName: "pi-agent",
+    },
+    _说明_scope: "要备份的路径，相对 ~/.pi/agent",
+    scope: ["."],
+    _说明_exclude: "额外排除规则（glob），内置已排除 tmp/、sessions/、缓存、node_modules",
+    exclude: [],
+    _说明_includeSessions: "是否包含会话历史（可能很大）",
+    includeSessions: false,
+    _说明_snapshot: "true=逐文件快照上传（增量，可单文件恢复）；false=打包成单个 tar.gz（默认）",
+    snapshot: false,
+    _说明_encrypt: "是否加密（AES-256-GCM），强烈建议开启",
+    encrypt: false,
+    _说明_encryptKey: "密钥引用，推荐 dpapi:backup-key；至少 16 位",
+    encryptKey: "",
+    _说明_backupOnExit: "退出 pi 时自动备份",
+    backupOnExit: true,
+    _说明_backupOnExitMinIntervalMinutes: "两次自动备份的最小间隔（分钟），防止频繁开关 pi 造成重复上传",
+    backupOnExitMinIntervalMinutes: 30,
+    _说明_backupOnExitTimeoutMs: "自动备份最长等待时间（毫秒）",
+    backupOnExitTimeoutMs: 600000,
+    _说明_keepVersions: "保留最近 N 个备份，更早的自动删除（0 = 不清理）",
+    keepVersions: 10,
+    _说明_timeoutMs: "单次 HTTP 请求超时（毫秒）",
+    timeoutMs: 60000,
+    insecureTls: false,
+  };
+}

package/extensions/webdav-backup/cron.mjs

@@ -0,0 +1,90 @@
+/**
+ * cron.mjs — 安装/移除 Windows 计划任务（每日定时备份）
+ *
+ * 用 schtasks.exe。任务名默认 PiWebDavBackup。
+ */
+
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+export const TASK_NAME = "PiWebDavBackup";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(here, "cli.mjs");
+
+function run(exe, args) {
+  return new Promise((resolve) => {
+    execFile(exe, args, { windowsHide: true }, (err, stdout, stderr) => {
+      resolve({
+        ok: !err,
+        code: err?.code ?? 0,
+        stdout: String(stdout ?? ""),
+        stderr: String(stderr ?? ""),
+        error: err ? String(err.message) : null,
+      });
+    });
+  });
+}
+
+function findNode() {
+  // schtasks 需要绝对路径；优先用当前 node 可执行文件
+  return process.execPath;
+}
+
+export async function installCron({ time = "03:00", log = () => {} } = {}) {
+  if (process.platform !== "win32") {
+    return { ok: false, error: "自动安装计划任务目前仅支持 Windows；其他平台请自行用 cron/systemd 调用 cli.mjs backup" };
+  }
+  if (!existsSync(cliPath)) {
+    return { ok: false, error: `找不到 cli.mjs：${cliPath}` };
+  }
+  if (!/^\d{1,2}:\d{2}$/.test(time)) {
+    return { ok: false, error: `时间格式应为 HH:MM，收到：${time}` };
+  }
+
+  const node = findNode();
+  const cmd = `"${node}" "${cliPath}" backup --reason cron`;
+
+  log(`创建计划任务 ${TASK_NAME}（每日 ${time}）…`);
+  const create = await run("schtasks.exe", [
+    "/Create",
+    "/TN",
+    TASK_NAME,
+    "/TR",
+    cmd,
+    "/SC",
+    "DAILY",
+    "/ST",
+    time,
+    "/F",
+  ]);
+
+  if (!create.ok) {
+    const msg = `${create.stderr || create.stdout || create.error}`.trim();
+    // 常见原因：非管理员权限
+    return {
+      ok: false,
+      error: `创建计划任务失败：${msg}${/拒绝访问|Access is denied/i.test(msg) ? "（请以管理员身份运行）" : ""}`,
+    };
+  }
+  log(`已创建计划任务：${TASK_NAME}`);
+  return { ok: true, taskName: TASK_NAME, time, command: cmd };
+}
+
+export async function uninstallCron({ log = () => {} } = {}) {
+  if (process.platform !== "win32") {
+    return { ok: false, error: "仅支持 Windows" };
+  }
+  log(`删除计划任务 ${TASK_NAME} …`);
+  const r = await run("schtasks.exe", ["/Delete", "/TN", TASK_NAME, "/F"]);
+  if (!r.ok) {
+    const msg = `${r.stderr || r.stdout || r.error}`.trim();
+    if (/找不到|cannot find|does not exist/i.test(msg)) {
+      return { ok: true, taskName: TASK_NAME, removed: false, note: "任务本来就不存在" };
+    }
+    return { ok: false, error: `删除失败：${msg}` };
+  }
+  return { ok: true, taskName: TASK_NAME, removed: true };
+}

package/extensions/webdav-backup/crypto.mjs

@@ -0,0 +1,163 @@
+/**
+ * crypto.mjs — AES-256-GCM 加密（scrypt 派生密钥）
+ *
+ * 文件格式（*.pibak）：
+ *   magic  "PIBAK1\n"            7 字节
+ *   salt   16 字节
+ *   iv     12 字节
+ *   hdrLen 4 字节 (BE)
+ *   header JSON（明文，含文件名/大小/校验）
+ *   ciphertext
+ *   tag    16 字节
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+  scryptSync,
+  timingSafeEqual,
+} from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { open } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Transform } from "node:stream";
+
+const MAGIC = Buffer.from("PIBAK1\n", "utf8");
+const CHUNK = 1024 * 1024;
+
+function deriveKey(passphrase, salt) {
+  return scryptSync(passphrase, salt, 32, { N: 16384, r: 8, p: 1 });
+}
+
+/** 流式加密 srcFile -> dstFile，返回明文 sha256 与密文大小 */
+export async function encryptFile(srcFile, dstFile, passphrase, meta = {}) {
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const key = deriveKey(passphrase, salt);
+
+  const header = Buffer.from(
+    JSON.stringify({ v: 1, alg: "aes-256-gcm", createdAt: new Date().toISOString(), ...meta }),
+    "utf8",
+  );
+  const hdrLen = Buffer.alloc(4);
+  hdrLen.writeUInt32BE(header.length, 0);
+
+  const cipher = createCipheriv("aes-256-gcm", key, iv, { authTagLength: 16 });
+  const hash = createHash("sha256");
+  const out = createWriteStream(dstFile);
+
+  out.write(MAGIC);
+  out.write(salt);
+  out.write(iv);
+  out.write(hdrLen);
+  out.write(header);
+
+  const source = createReadStream(srcFile, { highWaterMark: CHUNK });
+  source.on("data", (c) => hash.update(c));
+
+  await pipeline(
+    source,
+    new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, cipher.update(chunk));
+      },
+      flush(cb) {
+        this.push(cipher.final());
+        this.push(cipher.getAuthTag());
+        cb();
+      },
+    }),
+    out,
+  );
+
+  return { sha256: hash.digest("hex"), header: JSON.parse(header.toString("utf8")) };
+}
+
+/** 流式解密 .pibak -> dstFile */
+export async function decryptFile(srcFile, dstFile, passphrase) {
+  const fh = await open(srcFile, "r");
+  let pos = 0;
+  const readExact = async (n) => {
+    const buf = Buffer.alloc(n);
+    const { bytesRead } = await fh.read(buf, 0, n, pos);
+    if (bytesRead !== n) throw new Error("文件损坏：读取头部失败");
+    pos += n;
+    return buf;
+  };
+
+  try {
+    const magic = await readExact(7);
+    if (!magic.equals(MAGIC)) throw new Error("不是有效的 .pibak 加密文件（magic 不匹配）");
+
+    const salt = await readExact(16);
+    const iv = await readExact(12);
+    const hdrLen = (await readExact(4)).readUInt32BE(0);
+    if (hdrLen <= 0 || hdrLen > 64 * 1024) throw new Error("文件损坏：头部长度异常");
+    const header = JSON.parse((await readExact(hdrLen)).toString("utf8"));
+
+    const key = deriveKey(passphrase, salt);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv, { authTagLength: 16 });
+
+    // 剩余流 = ciphertext + 末尾 16 字节 tag
+    const src = createReadStream(null, { fd: fh.fd, start: pos, autoClose: true });
+    let tail = Buffer.alloc(0);
+    const out = createWriteStream(dstFile);
+
+    await pipeline(
+      src,
+      new Transform({
+        transform(chunk, _enc, cb) {
+          const buf = Buffer.concat([tail, chunk]);
+          if (buf.length <= 16) {
+            tail = buf;
+            cb();
+            return;
+          }
+          tail = buf.subarray(buf.length - 16);
+          cb(null, decipher.update(buf.subarray(0, buf.length - 16)));
+        },
+        flush(cb) {
+          if (tail.length !== 16) return cb(new Error("文件损坏：认证标签缺失"));
+          decipher.setAuthTag(tail);
+          try {
+            this.push(decipher.final());
+            cb();
+          } catch (e) {
+            cb(new Error(`解密失败（密码错误或文件损坏）：${e.message}`));
+          }
+        },
+      }),
+      out,
+    );
+
+    return { header };
+  } finally {
+    await fh.close().catch(() => {});
+  }
+}
+
+export function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const h = createHash("sha256");
+    createReadStream(file)
+      .on("data", (c) => h.update(c))
+      .on("end", () => resolve(h.digest("hex")))
+      .on("error", reject);
+  });
+}
+
+export function sha256Buffer(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+export { MAGIC };
+
+/** 校验两个密码是否一致（常量时间），用于 /backup-setup 输入确认 */
+export function samePassphrase(a, b) {
+  const ba = Buffer.from(String(a), "utf8");
+  const bb = Buffer.from(String(b), "utf8");
+  if (ba.length !== bb.length) return false;
+  return timingSafeEqual(ba, bb);
+}

package/extensions/webdav-backup/dav-mock.mjs

@@ -0,0 +1,145 @@
+/**
+ * dav-mock.mjs — 内存 WebDAV 服务端（供测试使用）
+ * 支持 PROPFIND / MKCOL / PUT / GET / HEAD / DELETE + Basic Auth
+ */
+
+import http from "node:http";
+
+export function startDavServer({ username = "user", password = "pass" } = {}) {
+  /** @type {Map<string, Buffer>} */
+  const store = new Map();
+  const dirs = new Set(["/"]);
+  const expectedAuth = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+  let putCount = 0;
+  let getCount = 0;
+
+  const server = http.createServer((req, res) => {
+    const path = decodeURIComponent((req.url ?? "/").split("?")[0]);
+    const key = path.replace(/\/+$/, "") || "/";
+    const method = (req.method ?? "GET").toUpperCase();
+
+    if (req.headers.authorization !== expectedAuth) {
+      res.writeHead(401, { "WWW-Authenticate": 'Basic realm="dav"' });
+      res.end("unauthorized");
+      return;
+    }
+
+    if (method === "PROPFIND") {
+      const depth = req.headers.depth ?? "0";
+      if (!dirs.has(key) && !store.has(key)) {
+        res.writeHead(404).end("not found");
+        return;
+      }
+      const prefix = key === "/" ? "/" : `${key}/`;
+      const children = [];
+      if (depth !== "0") {
+        for (const d of dirs) {
+          if (d === key) continue;
+          if (d.startsWith(prefix)) {
+            const rest = d.slice(prefix.length);
+            if (rest && !rest.includes("/")) {
+              children.push({ href: d, isDir: true, size: 0, lm: new Date().toUTCString() });
+            }
+          }
+        }
+        for (const [p, buf] of store) {
+          if (p.startsWith(prefix)) {
+            const rest = p.slice(prefix.length);
+            if (rest && !rest.includes("/")) {
+              children.push({ href: p, isDir: false, size: buf.length, lm: new Date().toUTCString() });
+            }
+          }
+        }
+      }
+      const responses = [
+        { href: key, isDir: !store.has(key), size: store.get(key)?.length ?? 0, lm: new Date().toUTCString() },
+        ...children,
+      ];
+      const xml =
+        `<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:">\n` +
+        responses
+          .map(
+            (e) =>
+              `  <D:response><D:href>${e.href}</D:href><D:propstat><D:prop>` +
+              `<D:getcontentlength>${e.size}</D:getcontentlength>` +
+              `<D:getlastmodified>${e.lm}</D:getlastmodified>` +
+              `<D:resourcetype>${e.isDir ? "<D:collection/>" : ""}</D:resourcetype>` +
+              `</D:prop><D:status>HTTP/1.1 200 OK</D:status></D:propstat></D:response>`,
+          )
+          .join("\n") +
+        `\n</D:multistatus>`;
+      res.writeHead(207, { "Content-Type": "application/xml" }).end(xml);
+      return;
+    }
+
+    if (method === "MKCOL") {
+      if (dirs.has(key) || store.has(key)) {
+        res.writeHead(405).end("exists");
+        return;
+      }
+      dirs.add(key);
+      res.writeHead(201).end();
+      return;
+    }
+
+    if (method === "PUT") {
+      const chunks = [];
+      req.on("data", (c) => chunks.push(c));
+      req.on("end", () => {
+        putCount++;
+        store.set(key, Buffer.concat(chunks));
+        res.writeHead(201).end();
+      });
+      return;
+    }
+
+    if (method === "GET") {
+      if (!store.has(key)) {
+        res.writeHead(404).end();
+        return;
+      }
+      getCount++;
+      const buf = store.get(key);
+      res.writeHead(200, { "Content-Length": String(buf.length) }).end(buf);
+      return;
+    }
+
+    if (method === "HEAD") {
+      if (!store.has(key)) {
+        res.writeHead(404).end();
+        return;
+      }
+      res.writeHead(200, { "Content-Length": String(store.get(key).length) }).end();
+      return;
+    }
+
+    if (method === "DELETE") {
+      if (store.delete(key) || dirs.delete(key)) {
+        res.writeHead(204).end();
+        return;
+      }
+      res.writeHead(404).end();
+      return;
+    }
+
+    res.writeHead(405).end("method not allowed");
+  });
+
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      resolve({
+        server,
+        port,
+        store,
+        dirs,
+        stats: () => ({ putCount, getCount }),
+        reset: () => {
+          putCount = 0;
+          getCount = 0;
+        },
+      });
+    });
+  });
+}