@xiaoyuyu6420/dsh-backup 0.13.4 → 0.14.0

package/lib/encrypt.js

@@ -0,0 +1,135 @@
+/**
+ * dsh-backup — 可选口令加密（P2 宿主半边）。
+ *
+ * 纯 node:crypto 实现，零外部依赖：scrypt（KDF，内存难哈希，抗口令穷举）派生
+ * 256 位密钥，AES-256-GCM（AEAD，密文自带认证）加密。每次加密随机生成
+ * salt 与 nonce（IV），GCM 的认证标签一并写入边车——口令错误或密文被篡改都会
+ * 让 final() 抛认证失败，绝无「解密出半个错文件」的可能。
+ *
+ * 安全边界（硬性）：
+ *  - 口令只作为函数入参在内存里流转，**绝不写 settings.yaml、绝不进日志、
+ *    绝不写盘**。调用方（backupPanel RPC）在客户端内存里持口令，传过来用完即弃。
+ *  - 密文布局：归档文件本身只存 ciphertext（不含 nonce/tag），nonce/tag/salt/
+ *    kdf 参数全在 `.encrypted.json` 边车里。边车是恢复时唯一需要的参数来源，
+ *    不含任何明文内容，可随密文一起备份/同步。
+ *
+ * 版本契约：sidecar.version 递增；读端对未知 version 一律拒绝（宁可不恢复，
+ * 也不拿不认识的参数猜着解）。
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  scrypt as scryptCb,
+} from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scrypt = promisify(scryptCb);
+
+/** 边车/密文格式版本。 */
+export const ENCRYPT_VERSION = 1;
+/** 加密算法标识（写进边车供读端核对，避免未来换算法时静默误解密）。 */
+export const CIPHER = 'aes-256-gcm';
+/** scrypt 参数：N=16384（2^14）、r=8、p=1——行业常见默认，约 16MB 内存、~50ms。 */
+export const KDF_PARAMS = Object.freeze({ algorithm: 'scrypt', N: 16384, r: 8, p: 1, keyLen: 32 });
+/** GCM 推荐 nonce 长度（12 字节）与认证标签长度（16 字节）。 */
+export const NONCE_BYTES = 12;
+export const SALT_BYTES = 16;
+export const TAG_BYTES = 16;
+
+/**
+ * 由口令 + 边车里的参数派生 AES 密钥。scrypt 的 maxmem 显式放宽到参数所需
+ * 内存的两倍余量（N=16384,r=8 → 128*N*r = 16MB），避免默认 32MB 上限在未来
+ * 参数升级时误杀。
+ */
+async function deriveKey(password, params) {
+  const N = Number(params?.N) || KDF_PARAMS.N;
+  const r = Number(params?.r) || KDF_PARAMS.r;
+  const p = Number(params?.p) || KDF_PARAMS.p;
+  const keyLen = Number(params?.keyLen) || KDF_PARAMS.keyLen;
+  const maxmem = 128 * N * r * 2 + 1024 * 1024;
+  return scrypt(password, params.salt, keyLen, { N, r, p, maxmem });
+}
+
+/**
+ * 加密一段明文，返回 { ciphertext, sidecar }。
+ *
+ * @param {Buffer|Uint8Array} plaintext 明文（tar.gz 字节）
+ * @param {string} password 口令（内存态，绝不落盘）
+ * @returns {Promise<{ ciphertext: Buffer, sidecar: object }>}
+ */
+export async function encryptBuffer(plaintext, password) {
+  if (typeof password !== 'string' || !password) {
+    throw new Error('加密需要非空口令（口令只经内存传入，绝不写盘）');
+  }
+  const salt = randomBytes(SALT_BYTES);
+  const nonce = randomBytes(NONCE_BYTES);
+  const key = await deriveKey(password, { ...KDF_PARAMS, salt });
+  const cipher = createCipheriv(CIPHER, key, nonce);
+  const body = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext);
+  const ciphertext = Buffer.concat([cipher.update(body), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return {
+    ciphertext,
+    sidecar: {
+      version: ENCRYPT_VERSION,
+      cipher: CIPHER,
+      kdf: KDF_PARAMS.algorithm,
+      kdfParams: {
+        N: KDF_PARAMS.N,
+        r: KDF_PARAMS.r,
+        p: KDF_PARAMS.p,
+        keyLen: KDF_PARAMS.keyLen,
+      },
+      salt: salt.toString('base64'),
+      nonce: nonce.toString('base64'),
+      authTag: authTag.toString('base64'),
+      ciphertextSize: ciphertext.length,
+    },
+  };
+}
+
+/**
+ * 解密一段密文。口令错误 / 密文被篡改时 AES-GCM 认证失败，抛出口令错误人话报错
+ * （调用方可直接展示）；未知版本 / 未知算法 / 边车字段缺失一律拒绝，不猜着解。
+ *
+ * @param {Buffer|Uint8Array} ciphertext 密文（归档文件内容）
+ * @param {object} sidecar `.encrypted.json` 解析出的对象
+ * @param {string} password 口令（内存态）
+ * @returns {Promise<Buffer>} 明文（tar.gz 字节）
+ */
+export async function decryptBuffer(ciphertext, sidecar, password) {
+  if (typeof password !== 'string' || !password) {
+    throw new Error('这份备份已加密，恢复需要口令（口令只经内存传入，绝不写盘）');
+  }
+  if (!sidecar || typeof sidecar !== 'object') {
+    throw new Error('加密边车缺失或损坏，无法解密（请核对备份是否完整）');
+  }
+  if (Number(sidecar.version) !== ENCRYPT_VERSION) {
+    throw new Error(`加密格式版本不兼容（边车 version=${sidecar.version}，本机支持 ${ENCRYPT_VERSION}）——请用更新版本的插件恢复`);
+  }
+  // 算法门：未知/缺失 cipher 一律拒绝（严格 !==，宁可不可恢复也不拿错误算法猜着解）。
+  if (sidecar.cipher !== CIPHER) {
+    throw new Error(`不支持的加密算法: ${sidecar.cipher ?? '（缺失）'}（本机只支持 ${CIPHER}）`);
+  }
+  const salt = sidecar.salt ? Buffer.from(sidecar.salt, 'base64') : null;
+  const nonce = sidecar.nonce ? Buffer.from(sidecar.nonce, 'base64') : null;
+  const authTag = sidecar.authTag ? Buffer.from(sidecar.authTag, 'base64') : null;
+  if (!salt || !nonce || !authTag) {
+    throw new Error('加密边车字段缺失（salt/nonce/authTag），无法解密');
+  }
+  const key = await deriveKey(password, { ...(sidecar.kdfParams || KDF_PARAMS), salt });
+  const decipher = createDecipheriv(CIPHER, key, nonce);
+  decipher.setAuthTag(authTag);
+  const body = Buffer.isBuffer(ciphertext) ? ciphertext : Buffer.from(ciphertext);
+  try {
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+  } catch (err) {
+    // GCM final() 认证失败：口令错或密文被改。两条都指向同一句人话，不泄露具体原因。
+    if (/unable to authenticate|authentication/i.test(String(err && err.message ? err.message : err))) {
+      throw new Error('口令错误或归档已损坏（AES-GCM 认证失败）——请核对口令后重试');
+    }
+    throw err;
+  }
+}

package/lib/gfs.js

@@ -0,0 +1,52 @@
+/**
+ * dsh-backup — GFS 保留策略（P3 宿主半边，纯函数，可独立自检）。
+ *
+ * 在现有「最近 keep N」之外补 GFS 两个长尾分层：
+ *  - monthly：keep 窗口之外的尾巴里，每个自然月保留**一份**（最早那份），最多
+ *    `monthly` 个不同月份；
+ *  - yearly：同理，每个自然年保留一份，最多 `yearly` 个不同年份。
+ *
+ * 默认 `{ monthly: 0, yearly: 0 }` 即等价旧行为（只 keep N + 既有日/周分层），
+ * 设置侧由 `gfsMonthly` / `gfsYearly` 两个字段支配，缺省 0 完全不改变现状。
+ * 旧 keep 语义不回退：keep 仍是「最近窗口份数」的唯一依据。
+ *
+ * 与 index.js 的 tierProtectedSet（日/周分层）互补——GFS 只负责月/年两层，
+ * 最终受保护集 = tierProtectedSet ∪ gfsProtectedSet。
+ */
+
+/** 从归档名解析自然日（YYYY-MM-DD）；解析不出返回 null。 */
+function dayOf(name) {
+  const m = /^dsh-(?:t-)?(\d{4})(\d{2})(\d{2})-\d{6}\d{3}\.tar\.gz$/.exec(name);
+  return m ? `${m[1]}-${m[2]}-${m[3]}` : null;
+}
+
+/**
+ * 计算 GFS 月/年分层应保护的归档名集合。
+ *
+ * @param {Array<{name:string}>} tailDesc keep 窗口外、新→旧排序的归档
+ * @param {string|null} newestName 最新归档名（用于跳过「今日」的档内冗余）
+ * @param {{monthly?:number, yearly?:number}} opts 月/年分层各保留多少个桶（0=关）
+ * @returns {Set<string>} 受保护的归档名
+ */
+export function gfsProtectedSet(tailDesc, newestName, { monthly = 0, yearly = 0 } = {}) {
+  const protectedNames = new Set();
+  if ((!monthly || monthly <= 0) && (!yearly || yearly <= 0)) return protectedNames;
+  const monthSeen = new Set();
+  const yearSeen = new Set();
+  const today = newestName ? dayOf(newestName) : null;
+  for (const b of tailDesc) {
+    const d = dayOf(b.name);
+    if (!d || d === today) continue;
+    const month = d.slice(0, 7); // YYYY-MM
+    const year = d.slice(0, 4); // YYYY
+    if (monthly > 0 && !monthSeen.has(month)) {
+      monthSeen.add(month);
+      if (monthSeen.size <= monthly) protectedNames.add(b.name);
+    }
+    if (yearly > 0 && !yearSeen.has(year)) {
+      yearSeen.add(year);
+      if (yearSeen.size <= yearly) protectedNames.add(b.name);
+    }
+  }
+  return protectedNames;
+}