dsh-config-manager 0.2.3 → 0.3.0

package/src/routes/recovery.test.ts

@@ -13,7 +13,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { utimesSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -22,6 +22,7 @@ import type { Server } from 'node:http';
 import { recoveryRoutes } from './recovery.ts';
 import { routeSpecOf, type WebRoute } from './kit.ts';
 import { DshProfileManager } from '../profiles/dsh-profile-manager.ts';
+import { parseZip } from '../utils/zip.ts';
 
 const BASE = '/api/dsh-config-manager/recovery';
 
@@ -569,3 +570,199 @@ test('t8 源码级：判据取自 preview 的 session.active，路由**不自己
   assert.match(source, /rewindTouchesWorkspace\(rewindInput\)/, '是否要动工作区必须有唯一判据');
   assert.equal((source.match(/sessionActiveGateApplies\(/g) ?? []).length, 3, '判定链位置只有一份判据（定义 + R1 + R2）');
 });
+
+/* ------------------------------------------------------------------ BK-01
+ * 反悔副本（pre-restore）只读出口：恢复覆盖前的原文落在 <snapshotDir>/pre-restore/<attempt>/
+ * （src/core/restore.ts 的 createPreRestoreAttemptDir / copyToPreRestore，命名 `NNNN-<label>`），
+ * 但此前 src/client、src/ui 零引用 ⇒ 用户既看不见也取不出来。这里只做两件只读的事：
+ *   ① GET  /recovery/pre-restore                      → 列出每个快照下的 attempt 目录与文件清单；
+ *   ② POST /recovery/pre-restore/export               → 把某个 attempt 目录打成 zip，落到用户指定目录。
+ * 硬约束：整条链路**不写快照目录一个字节**；zip 只写「用户显式指定的导出目录」，
+ * 且目标已存在 / 目标落在源目录内一律拒绝（禁止就地覆盖任何源文件）。
+ */
+
+interface PreRestoreFixture { root: string; out: string; cleanup: () => void }
+
+/** 造一个快照根：两个带反悔副本的快照 + 一个没有 pre-restore 的快照。 */
+function preRestoreFixture(): PreRestoreFixture {
+  const root = mkdtempSync(join(tmpdir(), 'dcm-bk01-snaps-'));
+  const out = mkdtempSync(join(tmpdir(), 'dcm-bk01-out-'));
+  const a = join(root, 'snap-a', 'pre-restore', '20261005-101010-123');
+  mkdirSync(a, { recursive: true });
+  writeFileSync(join(a, '0001-settings.yaml'), 'old-settings');
+  writeFileSync(join(a, '0002-sessions_x.jsonl'), 'old-session-line');
+  const b = join(root, 'snap-b', 'pre-restore', '20261006-090000-500');
+  mkdirSync(b, { recursive: true });
+  writeFileSync(join(b, '0001-plugins.yaml'), 'old-plugins');
+  mkdirSync(join(root, 'snap-c'), { recursive: true }); // 没有 pre-restore
+  return { root, out, cleanup: () => { rmSync(root, { recursive: true, force: true }); rmSync(out, { recursive: true, force: true }); } };
+}
+
+function envWithPreRestore(root: string, overrides: Record<string, unknown> = {}): unknown {
+  return {
+    dataDir: '/tmp/dcm-bk01-data',
+    snapshotsDir: root,
+    host: { homeDir: '/tmp/dcm-bk01-home', profile: 'web', log: { warn: () => {} } },
+    profiles: { listIncompleteCopies: () => [] },
+    recoveryOrchestrator: { status: async () => ({ status: 200, body: { incidents: [], running: [] } }) },
+    sessionHealth: {},
+    makeRecoveryExecutors: () => ({}),
+    tryAppendHistory: async () => undefined,
+    ...overrides,
+  };
+}
+
+test('BK-01/①：GET /recovery/pre-restore 列出每个快照下的 attempt 目录与文件清单（相对路径/大小/mtime）', async () => {
+  const f = preRestoreFixture();
+  try {
+    const route = routeOf(envWithPreRestore(f.root));
+    await withServer(route, async (base) => {
+      const res = await fetch(base + '/pre-restore');
+      assert.equal(res.status, 200);
+      const body = await res.json() as {
+        snapshots?: { snapshotId: string; attempts: { attempt: string; files: { relativePath: string; sizeBytes: number; mtimeMs: number }[] }[] }[];
+        unreadable?: unknown;
+      };
+      const ids = (body.snapshots ?? []).map((s) => s.snapshotId);
+      assert.deepEqual(ids.sort(), ['snap-a', 'snap-b'], '没有反悔副本的快照不必出现，但也不能凭空造');
+      const snapA = body.snapshots!.find((s) => s.snapshotId === 'snap-a')!;
+      assert.equal(snapA.attempts.length, 1, '同一快照下每次恢复一个新 attempt 目录');
+      assert.equal(snapA.attempts[0]!.attempt, '20261005-101010-123');
+      const files = snapA.attempts[0]!.files.map((x) => x.relativePath).sort();
+      assert.deepEqual(files, ['0001-settings.yaml', '0002-sessions_x.jsonl'], '文件清单按 attempt 目录内的相对路径给出');
+      const first = snapA.attempts[0]!.files.find((x) => x.relativePath === '0001-settings.yaml')!;
+      assert.equal(first.sizeBytes, 'old-settings'.length, '大小如实（反悔副本是原文）');
+      assert.equal(typeof first.mtimeMs, 'number');
+      assert.equal(body.unreadable, null, '读得动就必须如实说「没读不动」');
+    });
+  } finally {
+    f.cleanup();
+  }
+});
+
+test('BK-01/②：POST /recovery/pre-restore/export 把某个 attempt 打成 zip 落到指定目录，源目录字节不变', async () => {
+  const f = preRestoreFixture();
+  try {
+    const src = join(f.root, 'snap-a', 'pre-restore', '20261005-101010-123');
+    const before = { a: readFileSync(join(src, '0001-settings.yaml'), 'utf8'), b: readFileSync(join(src, '0002-sessions_x.jsonl'), 'utf8') };
+    const route = routeOf(envWithPreRestore(f.root));
+    await withServer(route, async (base) => {
+      const res = await fetch(base + '/pre-restore/export', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ snapshotId: 'snap-a', attempt: '20261005-101010-123', outputDir: f.out }),
+      });
+      const body = await res.json() as { ok?: boolean; zipPath?: string; entries?: number; code?: string };
+      assert.equal(res.status, 200, JSON.stringify(body));
+      assert.equal(body.ok, true);
+      const zipPath = body.zipPath!;
+      assert.equal(existsSync(zipPath), true, 'zip 必须真的落盘');
+      assert.equal(join(zipPath).startsWith(f.out), true, '只许写进用户指定的导出目录');
+      assert.equal(body.entries, 2);
+      const entries = parseZip(readFileSync(zipPath)).entries().map((e) => e.name).sort();
+      assert.deepEqual(entries, ['0001-settings.yaml', '0002-sessions_x.jsonl'], 'zip 里是 attempt 目录内的相对路径');
+    });
+    assert.equal(readFileSync(join(src, '0001-settings.yaml'), 'utf8'), before.a, '源文件字节不得变化');
+    assert.equal(readFileSync(join(src, '0002-sessions_x.jsonl'), 'utf8'), before.b);
+    assert.deepEqual(readdirSync(src).sort(), ['0001-settings.yaml', '0002-sessions_x.jsonl'], '不得在源目录里留任何产物');
+  } finally {
+    f.cleanup();
+  }
+});
+
+test('BK-01/③：snapshotId / attempt 带穿越（../、绝对路径）→ 400，零写入', async () => {
+  const f = preRestoreFixture();
+  try {
+    const route = routeOf(envWithPreRestore(f.root));
+    await withServer(route, async (base) => {
+      for (const body of [
+        { snapshotId: '../etc', attempt: '20261005-101010-123', outputDir: f.out },
+        { snapshotId: 'snap-a', attempt: '../snap-b', outputDir: f.out },
+        { snapshotId: 'snap-a', attempt: '20261005-101010-123', outputDir: '../escape' },
+      ]) {
+        const res = await fetch(base + '/pre-restore/export', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+        assert.equal(res.status, 400, JSON.stringify(body));
+      }
+      assert.deepEqual(readdirSync(f.out), [], '拒绝路径不得留下 zip');
+    });
+  } finally {
+    f.cleanup();
+  }
+});
+
+test('BK-01/④：导出目录不存在 / attempt 不存在 → 400 / 404，且绝不静默成功', async () => {
+  const f = preRestoreFixture();
+  try {
+    const route = routeOf(envWithPreRestore(f.root));
+    await withServer(route, async (base) => {
+      const missingDir = await fetch(base + '/pre-restore/export', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ snapshotId: 'snap-a', attempt: '20261005-101010-123', outputDir: join(f.out, 'nope') }),
+      });
+      assert.equal(missingDir.status, 400);
+      const missingAttempt = await fetch(base + '/pre-restore/export', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ snapshotId: 'snap-a', attempt: '20990101-000000-000', outputDir: f.out }),
+      });
+      assert.equal(missingAttempt.status, 404);
+      assert.deepEqual(readdirSync(f.out), [], '两种拒绝都不得留下产物');
+    });
+  } finally {
+    f.cleanup();
+  }
+});
+
+test('BK-01/⑤：目标 zip 已存在 → 409，绝不就地覆盖既有文件', async () => {
+  const f = preRestoreFixture();
+  try {
+    const route = routeOf(envWithPreRestore(f.root));
+    await withServer(route, async (base) => {
+      const body = JSON.stringify({ snapshotId: 'snap-a', attempt: '20261005-101010-123', outputDir: f.out });
+      const first = await fetch(base + '/pre-restore/export', { method: 'POST', headers: { 'content-type': 'application/json' }, body });
+      assert.equal(first.status, 200);
+      const zipPath = (await first.json() as { zipPath: string }).zipPath;
+      writeFileSync(zipPath, 'user-owned-bytes');
+      const second = await fetch(base + '/pre-restore/export', { method: 'POST', headers: { 'content-type': 'application/json' }, body });
+      assert.equal(second.status, 409);
+      assert.equal(readFileSync(zipPath, 'utf8'), 'user-owned-bytes', '已存在的目标文件必须原样保留');
+    });
+  } finally {
+    f.cleanup();
+  }
+});
+
+test('BK-01/⑥：导出目录落在 attempt 目录内 → 400，禁止往源目录里写', async () => {
+  const f = preRestoreFixture();
+  try {
+    const src = join(f.root, 'snap-a', 'pre-restore', '20261005-101010-123');
+    const route = routeOf(envWithPreRestore(f.root));
+    await withServer(route, async (base) => {
+      const res = await fetch(base + '/pre-restore/export', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ snapshotId: 'snap-a', attempt: '20261005-101010-123', outputDir: src }),
+      });
+      assert.equal(res.status, 400);
+      assert.deepEqual(readdirSync(src).sort(), ['0001-settings.yaml', '0002-sessions_x.jsonl'], '源目录里一个字节都不许新增');
+    });
+  } finally {
+    f.cleanup();
+  }
+});
+
+test('BK-01/⑦：快照根本身读不动 → 200 + readOnly + unreadable，不假装「没有反悔副本」', async () => {
+  const f = preRestoreFixture();
+  try {
+    // 指向一个不存在的根：readdir 失败 ⇒ 必须如实外露原因（"没有" 与 "读不到" 不能混为一谈）
+    const route = routeOf(envWithPreRestore(join(f.root, 'no-such-root')));
+    await withServer(route, async (base) => {
+      const res = await fetch(base + '/pre-restore');
+      assert.equal(res.status, 200, '读不动是「说不清」，不是 500');
+      const body = await res.json() as { readOnly?: boolean; snapshots?: unknown[]; unreadable?: unknown };
+      assert.equal(body.readOnly, true);
+      assert.deepEqual(body.snapshots, []);
+      assert.notEqual(body.unreadable, null, '读不动必须外露，不能返回空清单冒充「没有」');
+    });
+  } finally {
+    f.cleanup();
+  }
+});

package/src/routes/recovery.ts

@@ -21,7 +21,11 @@ import { EnvironmentLockUnavailableError, runWithMutationLock } from '../utils/e
 import { scanSessionHealth } from '../utils/session-health-scan.ts'
 import { applySessionTitles } from '../core/session-meta.ts'
 import { applySessionLogTitles } from '../core/session-title.ts'
-import { join } from 'node:path'
+import { isAbsolute, join, resolve } from 'node:path'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { isPathSafe, isSameOrChild } from '../utils/paths.ts'
+import { writeZip, type ZipWriteEntry } from '../utils/zip.ts'
+import { isValidSnapshotId } from '../core/restore.ts'
 import {
   applySessionRepair,
   listSessionRepairs,
@@ -312,6 +316,160 @@ function incompleteCopiesOf(profiles: {
   }
 }
 
+/* ------------------------------------------------------------------ BK-01
+ * 反悔副本（pre-restore）只读出口。
+ *
+ * 恢复链路在覆盖/删除任何文件前，会把当前原文复制到
+ * `<snapshotsDir>/<snapshotId>/pre-restore/<attempt>/`（src/core/restore.ts 的
+ * createPreRestoreAttemptDir / copyToPreRestore，文件名 `NNNN-<label>`）。
+ * BK-01：这份数据此前在 host 侧零出口 —— 用户既看不见、也取不出来，等于「存在但不可达」。
+ * 这里只做两件**零写入**的事：列清单（GET）与把某个 attempt 打成 zip 落到用户指定的导出目录（POST）。
+ *
+ * 硬边界：
+ *  - 整条链路不写快照目录一个字节（源目录里连临时文件都不许留）；
+ *  - zip 只落用户显式给出的**已存在**目录，目标同名文件已存在即 409（绝不就地覆盖任何既有文件）；
+ *  - 导出目录落在源目录之内（或源目录落在导出目录之内）一律 400。
+ */
+const PRE_RESTORE_DIR = 'pre-restore'
+/** 单次枚举的上限：attempt 数 / 文件数 / 递归深度 / 单次导出总字节。防一个坏目录把首屏拖垮。 */
+const PRE_RESTORE_MAX_ATTEMPTS = 200
+const PRE_RESTORE_MAX_FILES = 2000
+const PRE_RESTORE_MAX_DEPTH = 8
+const PRE_RESTORE_EXPORT_MAX_BYTES = 256 * 1024 * 1024
+/** attempt 目录名 = 恢复时间戳 `YYYYMMDD-HHMMSS-mmm`（restore.ts 的 preRestoreStamp），可选 `-N` 去重后缀。 */
+const PRE_RESTORE_ATTEMPT_RE = /^[0-9]{8}-[0-9]{6}-[0-9]{3}(-[0-9]+)?$/
+
+interface PreRestoreFile { relativePath: string; sizeBytes: number; mtimeMs: number }
+interface PreRestoreAttempt { attempt: string; files: PreRestoreFile[]; totalBytes: number; skippedLinks: number; truncated: boolean }
+interface PreRestoreSnapshot { snapshotId: string; attempts: PreRestoreAttempt[]; unreadable?: string; truncated?: true }
+interface PreRestoreListing { readOnly: true; snapshots: PreRestoreSnapshot[]; unreadable: string | null }
+
+function isPreRestoreAttemptName(name: unknown): name is string {
+  return typeof name === 'string' && PRE_RESTORE_ATTEMPT_RE.test(name)
+}
+
+interface PreRestoreWalk { files: PreRestoreFile[]; totalBytes: number; skippedLinks: number; truncated: boolean }
+
+/**
+ * 递归走一遍 attempt 目录，只**读元数据**（readdir + stat），不读文件内容。
+ * symlink 不跟随（只计数）：反悔副本里出现链接本身就可疑，跟过去会把 home 外的东西带进 zip。
+ * 超深度 / 超文件数 / 超字节即 `truncated` —— 调用方必须把截断当成「没说全」，不能当成「就这么多」。
+ */
+async function walkPreRestore(dir: string, maxBytes?: number): Promise<PreRestoreWalk> {
+  const files: PreRestoreFile[] = []
+  let totalBytes = 0
+  let skippedLinks = 0
+  let truncated = false
+  const walk = async (current: string, rel: string, depth: number): Promise<void> => {
+    if (truncated) return
+    if (depth > PRE_RESTORE_MAX_DEPTH) { truncated = true; return }
+    const entries = await readdir(current, { withFileTypes: true }).catch(() => null)
+    if (entries === null) { truncated = true; return }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    for (const entry of entries) {
+      if (truncated) return
+      const abs = join(current, entry.name)
+      const relativePath = rel === '' ? entry.name : rel + '/' + entry.name
+      if (entry.isSymbolicLink()) { skippedLinks += 1; continue }
+      if (entry.isDirectory()) { await walk(abs, relativePath, depth + 1); continue }
+      if (!entry.isFile()) { skippedLinks += 1; continue }
+      const info = await stat(abs).catch(() => null)
+      if (info === null || !info.isFile()) { skippedLinks += 1; continue }
+      if (files.length >= PRE_RESTORE_MAX_FILES) { truncated = true; return }
+      if (maxBytes !== undefined && totalBytes + info.size > maxBytes) { truncated = true; return }
+      files.push({ relativePath, sizeBytes: info.size, mtimeMs: info.mtimeMs })
+      totalBytes += info.size
+    }
+  }
+  await walk(dir, '', 0)
+  return { files, totalBytes, skippedLinks, truncated }
+}
+
+/** 列出快照根下每个快照的 pre-restore attempt 与文件清单。只读；快照根读不动如实外露。 */
+async function listPreRestore(snapshotsDir: string): Promise<PreRestoreListing> {
+  const roots = await readdir(snapshotsDir, { withFileTypes: true }).catch(() => null)
+  if (roots === null) {
+    // 与 listSnapshots 同口径：读不动就如实说「读不动」，不抛 500、也不假装「没有反悔副本」
+    return { readOnly: true, snapshots: [], unreadable: snapshotsDir }
+  }
+  const snapshots: PreRestoreSnapshot[] = []
+  const ids = roots.filter((e) => e.isDirectory()).map((e) => e.name).sort()
+  for (const snapshotId of ids) {
+    if (!isValidSnapshotId(snapshotId)) continue
+    const base = join(snapshotsDir, snapshotId, PRE_RESTORE_DIR)
+    const entries = await readdir(base, { withFileTypes: true }).catch((error: unknown) => error)
+    if (!Array.isArray(entries)) {
+      const code = (entries as { code?: unknown }).code
+      // ENOENT = 这个快照从未做过恢复（正常态，不列）；其余读不动如实标注
+      if (code === 'ENOENT' || code === 'ENOTDIR') continue
+      snapshots.push({ snapshotId, attempts: [], unreadable: entries instanceof Error ? entries.message : String(entries) })
+      continue
+    }
+    const attempts = entries.filter((e) => e.isDirectory() && isPreRestoreAttemptName(e.name)).map((e) => e.name)
+    if (attempts.length === 0) continue
+    attempts.sort((a, b) => (a < b ? 1 : a > b ? -1 : 0)) // 新 → 旧
+    const kept = attempts.slice(0, PRE_RESTORE_MAX_ATTEMPTS)
+    const list: PreRestoreAttempt[] = []
+    for (const attempt of kept) {
+      const walked = await walkPreRestore(join(base, attempt))
+      list.push({ attempt, ...walked })
+    }
+    snapshots.push({ snapshotId, attempts: list, ...(attempts.length > kept.length ? { truncated: true as const } : {}) })
+  }
+  return { readOnly: true, snapshots, unreadable: null }
+}
+
+type PreRestoreExportResult =
+  | { ok: true; zipPath: string; entries: number; totalBytes: number; skippedLinks: number }
+  | { ok: false; status: number; code: string; detail?: string }
+
+/**
+ * 把某个 attempt 目录打成 zip 落到用户指定目录。
+ * 码表（界面按 code 出文案，不靠状态码猜原因）：
+ *   invalid-input 400 / attempt-not-found 404 / export-dir-missing 400 /
+ *   export-inside-source 400 / export-target-exists 409 / export-too-large 413
+ */
+async function exportPreRestoreZip(snapshotsDir: string, body: Record<string, unknown>): Promise<PreRestoreExportResult> {
+  const fail = (status: number, code: string, detail?: string): PreRestoreExportResult =>
+    ({ ok: false, status, code, ...(detail !== undefined ? { detail } : {}) })
+  const { snapshotId, attempt, outputDir } = body
+  if (!isValidSnapshotId(snapshotId)) return fail(400, 'invalid-input', 'snapshotId')
+  if (!isPreRestoreAttemptName(attempt)) return fail(400, 'invalid-input', 'attempt')
+  // 导出目录必须是**绝对路径**且不带上跳段：相对路径会按宿主进程 cwd 解析，用户根本不知道写到哪去了
+  if (typeof outputDir !== 'string' || outputDir.trim() === '' || !isAbsolute(outputDir) || outputDir.split(/[\\/]+/).includes('..')) {
+    return fail(400, 'invalid-input', 'outputDir')
+  }
+  const outDir = resolve(outputDir)
+  const attemptDir = resolve(join(snapshotsDir, snapshotId, PRE_RESTORE_DIR, attempt))
+  // 双保险：id / attempt 已过白名单，再按解析后的路径确认没跳出快照根
+  if (!isSameOrChild(attemptDir, resolve(snapshotsDir))) return fail(400, 'invalid-input', 'attempt')
+  const srcInfo = await stat(attemptDir).catch(() => null)
+  if (srcInfo === null || !srcInfo.isDirectory()) return fail(404, 'attempt-not-found')
+  // 导出目录必须已存在：不替用户造目录（造出来的目录没人认，还可能落在错的盘上）
+  const outInfo = await stat(outDir).catch(() => null)
+  if (outInfo === null || !outInfo.isDirectory()) return fail(400, 'export-dir-missing')
+  // 双向 containment 都是「往源里写」：导出目录在 attempt 内 / attempt 在导出目录内（含快照根本身）
+  if (isSameOrChild(outDir, attemptDir) || isSameOrChild(attemptDir, outDir)) return fail(400, 'export-inside-source')
+  const zipPath = join(outDir, `pre-restore-${snapshotId}-${attempt}.zip`)
+  const walked = await walkPreRestore(attemptDir, PRE_RESTORE_EXPORT_MAX_BYTES)
+  if (walked.truncated) return fail(413, 'export-too-large')
+  // 目标已存在 ⇒ 409：writeZip 内部会 rename 覆盖，绝不能让「导出」顺手抹掉用户已有的文件
+  if ((await stat(zipPath).catch(() => null)) !== null) return fail(409, 'export-target-exists')
+  const entries: ZipWriteEntry[] = []
+  for (const file of walked.files) {
+    if (!isPathSafe(file.relativePath)) return fail(400, 'invalid-input', 'entry')
+    const data = await readFile(join(attemptDir, file.relativePath)).catch(() => null)
+    if (data === null) return fail(500, 'read-failed', file.relativePath)
+    entries.push({ name: file.relativePath, data: new Uint8Array(data) })
+  }
+  try {
+    await writeZip(zipPath, entries, { maxEntries: PRE_RESTORE_MAX_FILES })
+  } catch (error) {
+    return fail(500, 'zip-write-failed', error instanceof Error ? error.message : String(error))
+  }
+  return { ok: true, zipPath, entries: entries.length, totalBytes: walked.totalBytes, skippedLinks: walked.skippedLinks }
+}
+
 export function recoveryRoutes(env: RoutesEnv): WebRoute[] {
   const {
     dataDir,
@@ -320,6 +478,7 @@ export function recoveryRoutes(env: RoutesEnv): WebRoute[] {
     profiles,
     recoveryOrchestrator,
     sessionHealth,
+    snapshotsDir,
     tryAppendHistory,
   } = env
   return [
@@ -521,6 +680,40 @@ export function recoveryRoutes(env: RoutesEnv): WebRoute[] {
         }
         return
       }
+      // ------------------------------- BK-01：反悔副本（pre-restore）只读出口
+      // 挂在既有 recovery prefix 内，按 segments 分发 —— **不新增 endpoint 注册点**（本族本就是 prefix
+      // 路由，路由总数仍是 83；窗口守卫钉住那 7 条不受影响）。
+      // 零写入：GET 只读元数据；POST 只往用户显式指定的导出目录写一个 zip，快照目录一字节不动。
+      if (segments[0] === 'pre-restore') {
+        const sub = segments.slice(1)
+        if (sub.length === 0) {
+          if (req.method !== 'GET') { writeJson(res, 405, { error: 'method not allowed', code: 'method-not-allowed' }); return }
+          writeJson(res, 200, await listPreRestore(snapshotsDir))
+          return
+        }
+        if (sub.length === 1 && sub[0] === 'export') {
+          if (req.method !== 'POST') { writeJson(res, 405, { error: 'method not allowed', code: 'method-not-allowed' }); return }
+          const body = await readJsonBody(req)
+          if (body === undefined) { writeJson(res, 400, { error: 'invalid-input', code: 'invalid-input' }); return }
+          const result = await exportPreRestoreZip(snapshotsDir, body)
+          if (!result.ok) {
+            writeJson(res, result.status, { error: result.code, code: result.code, ...(result.detail !== undefined ? { detail: result.detail } : {}) })
+            return
+          }
+          // 导出是「用户拿到了一份文件」这件事实，照既有 recovery 子路径的口径落一条历史
+          await tryAppendHistory({
+            kind: 'recovery',
+            result: 'success',
+            sections: [],
+            source: 'recovery',
+            summary: engineMsg('route.recoveryOperationSummary', { action: 'export-pre-restore' }),
+          }).catch(() => undefined)
+          writeJson(res, 200, result)
+          return
+        }
+        writeJson(res, 404, { error: 'not found' })
+        return
+      }
       // ---------------------------------------- S1–S8：工作区 + 会话回滚点
       // 回滚点 = 工作区快照 + 会话游标（宿主按回合自动留点）。**没有手动「拍点」表单**，
       // 因此这里没有 capture 子路径 —— 留点由宿主订阅 session/event 后走引擎。

package/src/routes/sync.ts

@@ -49,7 +49,7 @@ import { shouldRunOnEnable, readAutosyncConfig, writeAutosyncConfig, clampRemote
 import { isValidExportFileName } from '../sync/backup-files.ts'
 import { DeviceFlowStore } from '../sync/github-auth.ts'
 import { channelOf, clearSyncChannel, isWebDavConfig, listCloudConfiguredProviders, parseSyncChannel, readFullSyncConfig, writeSyncConfig, gistChannelView, s3ChannelView, cloudSecretRef, S3_COMPAT_PROVIDERS, GIST_PROVIDER } from '../sync/sync-config.ts'
-import type { CloudS3ChannelView, CloudGistChannelView, CloudSecretWriter, FullSyncConfig, SyncConfig, SyncTransportType } from '../sync/sync-config.ts'
+import type { CloudS3ChannelView, CloudGistChannelView, CloudSecretWriter, FullSyncConfig, SyncConfig, SyncConfigIssue, SyncTransportType } from '../sync/sync-config.ts'
 import { SyncEngine } from '../sync/sync-engine.ts'
 import { isProbeUnsupported } from '../sync/transport.ts'
 import type { ApplyItemsReport } from '../sync/sync-engine.ts'
@@ -198,8 +198,12 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
    */
   const collectSyncStatus = async (opts: { workDirDetail: boolean }): Promise<Record<string, unknown>> => {
     // 完整双命名空间配置：repoUrl / webdav.url 无论当前通道都回填，
-    // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失
-    const full = await readFullSyncConfig(syncDir)
+    // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失。
+    // SEC-03 读侧可见性：已落盘但过不了白名单的 repoUrl 会被 readFullSyncConfig 丢弃
+    // （绝不交给凭据注入/git 子进程），但**必须把成因带出去** —— 否则界面显示「未配置」，
+    // 用户永远看不出自己保存过的地址是被安全校验拒掉，而不是从来没存过。
+    const configIssues: SyncConfigIssue[] = []
+    const full = await readFullSyncConfig(syncDir, configIssues)
     const state = await loadSyncState(syncDir)
     const [cred, webdavCred] = await Promise.all([
       credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
@@ -231,6 +235,9 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       configured: full !== null,
       transport,
       repoUrl: full?.git?.repoUrl,
+      // 被丢弃的通道配置成因（默认空数组：字段恒在，客户端不必判 undefined；
+      // 合法配置不产生幻影告警）。code 是机读 token，message 可直接展示。
+      configIssues,
       credentialConfigured: cred.configured,
       credentialWritable: cred.writable === true,
       // webdav 配置状态（无 secret 值：口令用 passwordConfigured 布尔标记）
@@ -302,10 +309,17 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           writeJson(res, 400, { error: msg('sync.workdirRecloneNeedsConfirm') })
           return
         }
-        const full = await readFullSyncConfig(syncDir)
+        const configIssues: SyncConfigIssue[] = []
+        const full = await readFullSyncConfig(syncDir, configIssues)
         const repoUrl = full?.git?.repoUrl ?? ''
         if (repoUrl === '') {
-          writeJson(res, 400, { error: msg('sync.workdirNotConfigured') })
+          // SEC-03：区分「地址被安全校验拒掉」与「从来就没配」。两者都 400、都不重建，
+          // 但文案必须说实话 —— 说成「尚未配置」会让用户反复重填同一个被拒地址。
+          const rejected = configIssues.find((issue) => issue.channel === 'git')
+          writeJson(res, 400, {
+            error: rejected === undefined ? msg('sync.workdirNotConfigured') : rejected.message,
+            configIssues,
+          })
           return
         }
         const rebuilt = await syncWorkDir.rebuild(repoUrl, mode)
@@ -373,11 +387,15 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
           credentials.describe(credentialRef(SYNC_WEBDAV_CREDENTIAL_REF)),
         ])
-        const cloud = await cloudChannelViews(await readFullSyncConfig(syncDir), credentials)
+        // SEC-03：写完就把落盘结果再读一遍（writeSyncConfig 可能因命名空间合并保留旧值），
+        // 成因而非「写成功」才是客户端要显示的真相；字段恒在（默认空数组）。
+        const configIssues: SyncConfigIssue[] = []
+        const cloud = await cloudChannelViews(await readFullSyncConfig(syncDir, configIssues), credentials)
         writeJson(res, 200, {
           ok: true,
           configured: true,
           transport: syncCfg.transport,
+          configIssues,
           credentialConfigured: cred.configured,
           // 通道判定消费单一来源 channelOf（B7 守卫扩到覆盖该谓词形态；此前是裸 isWebDavConfig 分支）
           webdav: channelOf(syncCfg) === 'webdav' ? describeWebDavSlot(syncCfg, webdavCred.configured) : undefined,
@@ -823,8 +841,9 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
         }
         const syncCfg = await prepareSync(body)
         const engine = makeSyncEngine(syncCfg)
-        await withTimeout(engine.deleteSnapshot(snapshotId), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'))
-        writeJson(res, 200, { ok: true, snapshotId })
+        const deleted = await withTimeout(engine.deleteSnapshot(snapshotId), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'))
+        // 远端孤儿 blob 回收被放弃时要能看见（RV1-F3）：空数组 = 本轮什么都没被放弃。
+        writeJson(res, 200, { ok: true, snapshotId, warnings: deleted.warnings })
       } catch (error) {
         writeSyncRouteError(res, error)
       }

package/src/security/integrity.ts

@@ -10,6 +10,8 @@
  *    危险键（防 prototype pollution）；解析失败抛错 → 导入方归为「Backup integrity check failed」。
  *  - 一步到位 `verifyChecksumsJson`：解析 + 校验合并，供 m5/导入管线直接调用。
  *  - 校验语义：表内每个路径必须在条目集合中存在且 SHA-256 一致；缺失与不符均计入 mismatches。
+ *  - 反向覆盖（SEC-05）：`unverifiedEntries` 算出「ZIP 有、表里没登记」的条目 —— 正向校验看不到
+ *    它们，而文件类分区按归档名原样落盘，缺了这条判定就等于「完整性只覆盖一半」。
  */
 import { parseJsonSafe } from '../utils/json.ts';
 import {
@@ -92,6 +94,41 @@ export function verifyChecksumsJson(
   return verifyChecksums(entries, table);
 }
 
+/**
+ * 会落盘的文件分区条目「未登记进校验表」时的错误码（写进 `PlanItem.detail`，也进执行报告）。
+ *
+ * 语义不是「哈希不符」（那由 `import.integrityFailed` 表示，且直接失败），而是
+ * 「这个条目根本没被校验表覆盖」—— 完整性声明对它零约束（SEC-05）。
+ */
+export const UNVERIFIED_FILE_ENTRY_CODE = 'unverified-file-entry';
+
+/**
+ * 上述状态的文案键。字典条目由维护方补齐；缺失时 messages 回退成键名本身、绝不抛错，
+ * 所以导入流程不会因为缺一条文案而中断。
+ */
+export const UNVERIFIED_FILE_ENTRY_KEY = 'import.unverifiedFileEntry';
+
+/**
+ * 校验表的**反向覆盖**：entries 里存在、校验表里没登记的路径。
+ *
+ * `verifyChecksums` 只正向遍历表里的键（登记的必须存在且 SHA-256 一致），**表外条目它不看**；
+ * 而文件类分区是按归档名原样落盘的（`adapters/file-collection.ts` 的 applyItem），
+ * 于是「ZIP 里有、checksums 没登记」的文件照样写进目标目录 —— 完整性声明只约束了登记过的那一半。
+ *
+ * 本函数是「谁没被覆盖」的**单一事实源**：loadBundle 的告警与导入侧的阻断判定共用它，
+ * 不各算一遍（两份实现迟早分叉）。判据与既有告警逐字一致：
+ * 跳过目录条目（以 `/` 结尾）与调用方给出的结构文件（manifest.json / integrity/checksums.json）。
+ */
+export function unverifiedEntries(
+  names: readonly string[],
+  table: Record<string, string>,
+  exclude: readonly string[] = [],
+): string[] {
+  const skip = new Set(exclude);
+  const covered = new Set(Object.keys(table));
+  return names.filter((name) => !name.endsWith('/') && !skip.has(name) && !covered.has(name));
+}
+
 /** 人类可读的不匹配摘要（给「Backup integrity check failed」错误消息用） */
 export function describeMismatches(result: ChecksumVerifyResult): string {
   const parts = [