dsh-config-manager 0.2.3 → 0.3.0

package/lib/core/analyzer.d.ts

@@ -31,6 +31,8 @@ export interface AnalyzerOptions {
         relativePath: string;
         data: Uint8Array;
     }[]) => SessionFormatProbeResult;
+    /** SEC-05：按分区豁免「表外条目阻断」（缺省空 = 严格）；判据见 security/unverified-file-blocks.ts */
+    extraEntryExemptSections?: readonly SectionId[];
 }
 /** m1：每完成一个计划项的进度回调信息（Host 侧 run 状态更新用） */
 export interface PlanItemProgress {
@@ -55,6 +57,7 @@ export declare class Analyzer {
     private readonly parseZipFn;
     private readonly msg;
     private readonly sessionFormatProbe?;
+    private readonly extraEntryExemptSections;
     /**
      * 会话内 bundle 缓存（zipPath → { 身份, 解析结果 }）。
      *

package/lib/core/analyzer.js

@@ -10,13 +10,14 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { sha256Hex } from '../utils/hashing.js';
-import { parseJsonSafe } from '../utils/json.js';
 import { SECTION_FILE_PREFIXES, SECTION_IDS, SECTION_JSON_PATHS, isFileSection, validateSectionData, } from '../schema/config.js';
-import { CHECKSUMS_FILE, MANIFEST_FILE, parseManifest } from '../schema/manifest.js';
+import { MANIFEST_FILE, parseManifest } from '../schema/manifest.js';
 import { CURRENT_SCHEMA_VERSION, canImport, describeVersion, isSupported, isTooNew, needsMigration, } from '../schema/versions.js';
 import { parseZip } from '../utils/zip.js';
 import { loadTombstones } from '../schema/tombstones.js';
 import { DEFAULT_SENSITIVE_RELS, restoreVaultFiles } from '../security/vault.js';
+import { applyUnverifiedFileBlocks, scanArchiveIntegrity, unverifiedNoticeText } from '../security/unverified-file-blocks.js';
+import { UNVERIFIED_FILE_ENTRY_CODE } from '../security/integrity.js';
 import { createSnapshot, fsForSection, planItemWritesTarget, resolveFileTarget, resolveFileTargetRel } from './backup.js';
 import { isCredentialConfigured } from './credential-status.js';
 import { rollback } from './rollback.js';
@@ -127,6 +128,7 @@ export class Analyzer {
     parseZipFn;
     msg;
     sessionFormatProbe;
+    extraEntryExemptSections;
     /**
      * 会话内 bundle 缓存（zipPath → { 身份, 解析结果 }）。
      *
@@ -149,6 +151,7 @@ export class Analyzer {
         this.parseZipFn = opts.parseZipOverride ?? parseZip;
         this.msg = opts.msg ?? msgOf(opts.ctx);
         this.sessionFormatProbe = opts.sessionFormatProbe;
+        this.extraEntryExemptSections = opts.extraEntryExemptSections ?? [];
     }
     /* ---------------- 第 1-6 步：ZIP 读入 → 安全解析 → manifest → 完整性 → schema ---------------- */
     /**
@@ -195,55 +198,13 @@ export class Analyzer {
         catch (err) {
             throw new Error(this.msg('import.manifestParseFailed', { reason: err instanceof Error ? err.message : String(err) }));
         }
-        // 4. 完整性（integrity/checksums.json 逐一 SHA-256）
+        // 4. 完整性（checksums.json 逐一 SHA-256）+ 4b 反向覆盖（表外条目）：判据下沉在 security 侧。
         const zipWarnings = [];
-        let checksums = { ok: true, mismatches: [], missing: [] };
-        // 4a. H2：校验表**缺失**或**为空**时，全部条目都处于「未登记 ⇒ 未被校验」状态。
-        //     此前整段完整性逻辑（含下面的反向检查）都嵌在 `if (archive.has(CHECKSUMS_FILE))` 内，
-        //     于是「剥掉 checksums.json」或「把它置为 {}」= 一个条目都不校验，却 valid=true / 零告警。
-        //     两种形态对用户是同一件事（没有任何条目被校验），故共用同一条告警，不制造近重复文案。
-        const table = archive.has(CHECKSUMS_FILE)
-            ? parseJsonSafe(archive.readEntryText(CHECKSUMS_FILE))
-            : null;
-        if (table === null || Object.keys(table).length === 0) {
-            zipWarnings.push(this.msg('import.checksumsMissing'));
-        }
-        if (table !== null && Object.keys(table).length > 0) {
-            const entries = new Map();
-            for (const name of archive.names()) {
-                if (name === MANIFEST_FILE || name === CHECKSUMS_FILE)
-                    continue;
-                try {
-                    // 异步解压：这是全仓**唯一**逐条解压全部条目的地方，`inflateRawSync` 会整段阻塞
-                    // 事件循环（实测 29 MiB 归档 108 ms，大备份就是几秒的界面冻结）。判据与同步版逐字相同。
-                    entries.set(name, await archive.readEntryAsync(name));
-                }
-                catch {
-                    entries.delete(name); // 损坏条目在完整性阶段即失败
-                    checksums.ok = false;
-                    checksums.mismatches.push(name);
-                }
-            }
-            const result = await verifyAgainstTable(entries, table);
-            checksums = result;
-            if (!checksums.ok) {
-                throw new Error(this.msg('import.integrityFailed', {
-                    entries: [...checksums.mismatches, ...checksums.missing].map((m) => `"${m}"`).join(', '),
-                }));
-            }
-            // 4b. G-04：反向完整性——ZIP 内**不在**校验表里的条目（未登记 ⇒ 未被校验）。
-            //     verifyAgainstTable 只遍历表里的键，所以 ZIP 里多出的条目此前既不校验也不告知；
-            //     这里把它变成显式 warning（不阻断：未知 ZIP 条目不参与校验是格式 v1 的既定语义）。
-            //     排除 manifest.json / checksums.json 自身与目录条目（以 "/" 结尾）。
-            const tableKeys = new Set(Object.keys(table));
-            const extraEntries = archive.names().filter((name) => name !== MANIFEST_FILE && name !== CHECKSUMS_FILE
-                && !name.endsWith('/') && !tableKeys.has(name));
-            if (extraEntries.length > 0) {
-                zipWarnings.push(this.msg('import.extraEntries', {
-                    entries: extraEntries.map((e) => `"${e}"`).join(', '),
-                }));
-            }
-        }
+        const integrity = await scanArchiveIntegrity(archive, this.msg);
+        if (integrity.failure !== undefined)
+            throw new Error(integrity.failure);
+        zipWarnings.push(...integrity.warnings);
+        const { checksums, unverified } = integrity;
         // 5. schema 版本判定（集中）：过新（isTooNew）或过旧（低于 MIN_SUPPORTED）→ 一律硬失败（行为不变）
         if (isTooNew(manifest.schemaVersion) || !isSupported(manifest.schemaVersion)) {
             throw new Error(this.msg('import.schemaUnsupported', { version: describeVersion(manifest.schemaVersion) }));
@@ -265,7 +226,7 @@ export class Analyzer {
                 zipWarnings.push(this.msg('import.executableWarning', { name }));
             }
         }
-        const bundle = { archive, manifest, checksums, zipWarnings, migrationWarnings };
+        const bundle = { archive, manifest, checksums, unverifiedEntries: unverified, zipWarnings, migrationWarnings };
         // 身份读得到才入实例缓存（与跨请求缓存同一判据：不拿未知身份签结果）。
         if (identity !== null)
             this.bundleCache.set(zipPath, { stamp: identity.stamp, bundle });
@@ -493,6 +454,9 @@ export class Analyzer {
         }
         // 会话格式体检只跑一次：告警、计划项标记、ImportAnalysis 摘要共用（探针要解首帧，别重复跑）。
         const sessionFormats = this.resolveSessionFormats(sections);
+        // SEC-05：会落盘的文件分区条目必须在校验表内（表外条目此前照样被原样写进目标目录）。
+        // 阻断结果就在计划项自己身上（kind:'Error' + description），不另存一份名单（单一事实）。
+        applyUnverifiedFileBlocks(bundle.unverifiedEntries, adapterItems, this.fileCollectionIds(), this.extraEntryExemptSections, this.msg);
         return {
             ...bundle,
             sections,
@@ -533,7 +497,13 @@ export class Analyzer {
         const { manifest, zipWarnings } = bundle;
         const analyzed = await this.analyzeBundle(bundle);
         const errors = [...analyzed.adapterIssues];
-        const warnings = [...zipWarnings, ...bundle.migrationWarnings, ...analyzed.sectionWarnings];
+        // SEC-05：未覆盖条目（表外 + 校验表缺失时的全部文件分区条目）≠ 被篡改 —— 逐条 Error 已保证零写入，
+        // 不再把整包判死。全仓只此一条 warning（RV1-F11：与 scanArchiveIntegrity 的 import.extraEntries 合并）；
+        // 名单取**全部**未覆盖条目而非「被阻断」子集：豁免分区（历史包兼容）不阻断但仍必须被说出来。
+        const blockedCount = analyzed.adapterItems.filter((i) => i.detail === UNVERIFIED_FILE_ENTRY_CODE).length;
+        const unverifiedNotice = analyzed.unverifiedEntries.length > 0
+            ? [unverifiedNoticeText(this.msg, analyzed.unverifiedEntries, blockedCount)] : [];
+        const warnings = [...zipWarnings, ...bundle.migrationWarnings, ...analyzed.sectionWarnings, ...unverifiedNotice];
         warnings.push(...this.secretsPayloadWarnings(manifest, opts.decryptedCredentials));
         if (!canImport(manifest.schemaVersion)) {
             errors.push(this.msg('import.versionUnsupported', { version: describeVersion(manifest.schemaVersion) }));
@@ -915,14 +885,20 @@ export class Analyzer {
                         message: outcome.executed.message ?? null,
                     });
                 }
-                // 仅硬失败计入 anyFailed（warning 属非致命：目标不可达等，不触发回滚，§34.17）
-                if (outcome.executed.status === 'failed')
+                // 仅硬失败计入 anyFailed（warning 属非致命：目标不可达等，不触发回滚，§34.17）。
+                // 「硬失败」= 真的尝试过写、并且失败了（applyOne/adapter 抛错、applyItem 返回 failed、写一半的
+                // 目标不可达）。执行前就被策略拦下的项（kind 'Error'：安全白名单 / SEC-05 未覆盖条目）**根本没
+                // 碰目标** —— 它连一个字节都没写，把它算成失败只会让 rollbackOnError（IE-02 缺省 true）在
+                // 「本来能导入的部分」上做一次整笔回滚，等于用安全策略制造数据损失；它也没留下半套状态可回滚。
+                // 因此这类预判阻断只记账（executed 里 status 'failed'，用户可见），不触发回滚、不中断后续条目。
+                const hardFailed = outcome.executed.status === 'failed' && item.kind !== 'Error';
+                if (hardFailed)
                     anyFailed = true;
                 if (outcome.needsRestart)
                     needsRestart = true;
                 if (outcome.warning)
                     warnings.push(outcome.warning);
-                if (opts.rollbackOnError && outcome.executed.status === 'failed')
+                if (opts.rollbackOnError && hardFailed)
                     break;
             }
             // 分区收尾（issue #45 ④）：会话位置护栏等必须等本分区全部写完才做的动作。
@@ -1334,7 +1310,7 @@ export class Analyzer {
 // analyzer 只保留三段式引擎本体；路径重定基/映射、schema 迁移校验、逐路径 issue、凭据计划项、
 // 墓碑过滤、journal 上报这些**纯计算**都搬去 `./import-planning.ts`（本文件 1824 → 约 1490 行）。
 // 依赖方向单行：analyzer → import-planning，后者绝不 import 本文件（避免第二个入口环）。
-import { applyMappingsToSections, applyTombstoneFilter, buildCredentialPlanItems, detectPathIssues, mergePathMappings, rebaseMapping, reportRollbackToJournal, runSchemaMigration, sessionUnitVersion, usableSecretValue, verifyAgainstTable, } from './import-planning.js';
+import { applyMappingsToSections, applyTombstoneFilter, buildCredentialPlanItems, detectPathIssues, mergePathMappings, rebaseMapping, reportRollbackToJournal, runSchemaMigration, sessionUnitVersion, usableSecretValue, } from './import-planning.js';
 // 对外导入面保持不变（core/index.ts 与既有测试按 './analyzer.ts' 取这三个名字）。
 export { applyMappingsToSections, rebaseMapping, runSchemaMigration } from './import-planning.js';
 //# sourceMappingURL=analyzer.js.map

package/lib/core/backup.d.ts

@@ -145,6 +145,28 @@ export type PruneSelector = (metas: ReadonlyArray<{
  * 行为等价于改造前（安全侧：宁可少删，绝不因缺实现而多删）。
  */
 export declare const fallbackPruneSelector: PruneSelector;
+export declare const PRE_RESTORE_KEEP_ATTEMPTS = 5;
+export declare const PRE_RESTORE_KEEP_DAYS = 30;
+/** 一条反悔副本 attempt 的淘汰计划（删除**前**就进 PrunePlan，供审计与界面展示）。 */
+export interface PrunePreRestoreDrop {
+    snapshotId: string;
+    attempt: string;
+    /** count = 超出份数上限；over-age = 超过保留天数 */
+    reason: 'count' | 'over-age';
+    /** 该 attempt 目录里的文件数（用户能看出「删了多少份原文」） */
+    files: number;
+}
+/** 一轮保留清理的**计划**（在真正 rm 之前回调出去；也是 pruneNow 的返回值）。 */
+export interface PrunePlan {
+    /** 将回收的快照 id（目录内的快照本体，不含 pre-restore 子树） */
+    removeSnapshots: string[];
+    /** 因存在反悔副本而**不**整目录删的快照 id（只删本体内容、留下 pre-restore/） */
+    keepPreRestoreFor: string[];
+    /** 反悔副本 attempt 级淘汰计划 */
+    dropPreRestore: PrunePreRestoreDrop[];
+    /** 计划删除的具体路径（相对快照根、'/' 分隔；审计「到底删了什么」） */
+    paths: string[];
+}
 export interface FileSnapshotStoreOptions {
     /** 快照根目录（宿主决定，如 ~/.dsh/dsh-config-manager/snapshots） */
     dir: string;
@@ -160,6 +182,8 @@ export interface FileSnapshotStoreOptions {
      * 缺省 = 不记录（不改变 prune 行为、不污染核心引擎）。
      */
     onPrune?: (removedIds: string[]) => void;
+    /** BK-05：保留清理的**计划**回调（在真正删除之前，best-effort；抛错不影响清理） */
+    onPrunePlan?: (plan: PrunePlan) => void;
     /**
      * m-retention：快照保留策略提供者（GFS 分层；可配置）。
      * 缺省 = `SNAPSHOT_RETENTION_LIMIT`（= 既有的「保留最近 10 个」，行为不变）。
@@ -209,6 +233,18 @@ export declare class FileSnapshotStore implements SnapshotStore {
    *  Phase 4 F3：被 active/quarantine 未收敛 journal 引用的 snapshot（recovery 回滚点）
    *  必须豁免——引用提供者（referencedSnapshotIds）返回的 id 绝不自动清理。 */
     private prune;
+    /**
+     * BK-05：反悔副本（pre-restore）淘汰计划 —— 只看**份数与天数**，与快照本体的保留策略无关。
+     *
+     * 为什么单独一套：快照本体是「历史回滚点」，可被 GFS 策略批量回收；反悔副本是用户把
+     * 刚才那次恢复撤回去的**唯一**原文（不在 blobs、不进同步、不进导出），它只需要「别无限长」，
+     * 不需要也不该受 keepLast/keepMonthly 影响 —— 否则一次批量淘汰会把最近几次恢复的反悔点一起抹掉。
+     * attempt 名即恢复时间戳（restore.ts 的 preRestoreStamp，本地时间 yyyyMMdd-HHmmss-SSS[-序号]）；
+     * 解析不出来回落目录 mtime（手工改名的残留也能被淘汰，不会永久占位）。
+     */
+    private collectPreRestorePlan;
+    /** BK-05：手动触发一轮保留清理（与 save 后的自动清理同一实现）。 */
+    pruneNow(): Promise<PrunePlan>;
     load(id: string): Promise<Snapshot>;
     readBlob(id: string, blobPath: string): Promise<Uint8Array>;
     /** 标记快照生命周期状态：重写 <dir>/<id>/snapshot.json（保留其余字段）。 */

package/lib/core/backup.js

@@ -474,6 +474,27 @@ export function selectPruneCandidates(metas, limit = SNAPSHOT_RETENTION_LIMIT) {
  * 行为等价于改造前（安全侧：宁可少删，绝不因缺实现而多删）。
  */
 export const fallbackPruneSelector = (metas, policy) => selectPruneCandidates(metas, policy.keepLast);
+/* ---------------- BK-05：反悔副本（pre-restore）保留策略 ----------------
+ *
+ * 反悔副本 = 恢复链路在覆盖/删除前落的原文副本（restore.ts:888 起写 <snapshotDir>/pre-restore/<attempt>/）。
+ * 它与快照本体的生命周期**不是一回事**：本体可以按保留策略回收（历史回滚点），
+ * 反悔副本却是用户「把刚才这次恢复撤回去」的最后一份原文，整条链路上没有第二份
+ * （不在 blobs 里、不进同步、不进导出）。所以两套策略分开：
+ *  - 快照本体：既有 RetentionPolicyLike（宿主可注入 GFS）；
+ *  - 反悔副本：只按「份数 + 天数」淘汰，常量在 core 内固定（无宿主可调项 —— 少了它等于没有反悔能力）。
+ */
+export const PRE_RESTORE_KEEP_ATTEMPTS = 5;
+export const PRE_RESTORE_KEEP_DAYS = 30;
+/** 反悔副本目录名（restore.ts 写入侧同一常量值；这里是读侧，绝不与写侧分叉） */
+const PRE_RESTORE_DIR_NAME = 'pre-restore';
+/** 解析反悔副本 attempt 目录名里的时间戳（本地时间 yyyyMMdd-HHmmss-SSS，可选 -N 去重后缀）。 */
+function parsePreRestoreStamp(name) {
+    const m = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})-(\d{3})(?:-\d+)?$/.exec(name);
+    if (m === null)
+        return null;
+    const at = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6]), Number(m[7])).getTime();
+    return Number.isFinite(at) ? at : null;
+}
 /** 文件快照存储：<dir>/<id>/snapshot.json + <dir>/<id>/blobs/* */
 export class FileSnapshotStore {
     options;
@@ -565,6 +586,7 @@ export class FileSnapshotStore {
    *  Phase 4 F3：被 active/quarantine 未收敛 journal 引用的 snapshot（recovery 回滚点）
    *  必须豁免——引用提供者（referencedSnapshotIds）返回的 id 绝不自动清理。 */
     async prune() {
+        const emptyPlan = { removeSnapshots: [], keepPreRestoreFor: [], dropPreRestore: [], paths: [] };
         const dir = this.options.dir;
         const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
         // F3：被未收敛 journal 引用的快照**绝不自动清理**。判据是「读不到 ≠ 没有引用」——
@@ -577,7 +599,7 @@ export class FileSnapshotStore {
             }
             catch (err) {
                 this.options.onWarn?.(engineMsg('core.backup.pruneAbandoned', { reason: err instanceof Error ? err.message : String(err) }));
-                return;
+                return emptyPlan;
             }
         }
         // m-retention：策略读取失败 → 回退缺省（绝不因策略提供者异常而误删/崩溃）
@@ -610,13 +632,66 @@ export class FileSnapshotStore {
                 // 损坏 / 非快照目录：跳过（与 listSnapshots 语义一致）
             }
         }
-        const removedIds = [];
+        // --- BK-05：先出计划，再删 ---
+        // 快照本体与反悔副本是两套生命周期：本体按保留策略回收，pre-restore 按「份数 + 天数」淘汰。
+        // 计划必须在 rm **之前**成型并回调出去——删完再报等于审计拿不到原始状态。
+        const plan = {
+            removeSnapshots: [],
+            keepPreRestoreFor: [],
+            dropPreRestore: await this.collectPreRestorePlan(),
+            paths: [],
+        };
+        /** 每个待回收快照：目录名 → 要删的子项（保持 pre-restore 不动） */
+        const removals = [];
         for (const id of selector(metas, policy)) {
             const target = path.join(dir, id);
             if (!target.startsWith(dir))
                 continue; // 越界 id 跳过（不删、不抛，同 save/readBlob 包含性约定）
+            const children = await fs.readdir(target).catch(() => []);
+            const hasPre = children.includes(PRE_RESTORE_DIR_NAME);
+            removals.push({ id, children, hasPre });
+            plan.removeSnapshots.push(id);
+            for (const child of children) {
+                if (child === PRE_RESTORE_DIR_NAME)
+                    continue;
+                plan.paths.push(id + '/' + child);
+            }
+        }
+        for (const drop of plan.dropPreRestore)
+            plan.paths.push(drop.snapshotId + '/pre-restore/' + drop.attempt + '/');
+        this.options.onPrunePlan?.(plan);
+        if (plan.removeSnapshots.length === 0 && plan.dropPreRestore.length === 0)
+            return plan;
+        // 1) 回收快照本体：有反悔副本的快照**不整目录删**（否则唯一那份原文跟着消失），逐项删其余内容
+        const removedIds = [];
+        for (const removal of removals) {
+            const target = path.join(dir, removal.id);
+            for (const child of removal.children) {
+                if (child === PRE_RESTORE_DIR_NAME)
+                    continue;
+                await fs.rm(path.join(target, child), { recursive: true, force: true });
+            }
+            if (removal.hasPre)
+                plan.keepPreRestoreFor.push(removal.id);
+            else
+                await fs.rm(target, { recursive: true, force: true });
+            removedIds.push(removal.id);
+        }
+        // 2) 反悔副本 attempt 级淘汰（份数超限 / 超过保留天数）
+        for (const drop of plan.dropPreRestore) {
+            await fs.rm(path.join(dir, drop.snapshotId, PRE_RESTORE_DIR_NAME, drop.attempt), { recursive: true, force: true });
+        }
+        // 3) 收尾：快照本体已回收（无 snapshot.json）且反悔副本也空了 ⇒ 不留空壳目录
+        const touched = new Set([...plan.keepPreRestoreFor, ...plan.dropPreRestore.map((d) => d.snapshotId)]);
+        for (const id of touched) {
+            const target = path.join(dir, id);
+            const hasSnapshot = await fs.stat(path.join(target, 'snapshot.json')).catch(() => null) !== null;
+            if (hasSnapshot)
+                continue;
+            const left = await fs.readdir(path.join(target, PRE_RESTORE_DIR_NAME)).catch(() => null);
+            if (left !== null && left.length > 0)
+                continue;
             await fs.rm(target, { recursive: true, force: true });
-            removedIds.push(id);
         }
         // Phase 6：自动保留清理历史回调（best-effort；不改变 prune 行为）
         if (removedIds.length > 0) {
@@ -625,6 +700,53 @@ export class FileSnapshotStore {
             }
             catch { /* 历史回调失败不阻断 */ }
         }
+        return plan;
+    }
+    /**
+     * BK-05：反悔副本（pre-restore）淘汰计划 —— 只看**份数与天数**，与快照本体的保留策略无关。
+     *
+     * 为什么单独一套：快照本体是「历史回滚点」，可被 GFS 策略批量回收；反悔副本是用户把
+     * 刚才那次恢复撤回去的**唯一**原文（不在 blobs、不进同步、不进导出），它只需要「别无限长」，
+     * 不需要也不该受 keepLast/keepMonthly 影响 —— 否则一次批量淘汰会把最近几次恢复的反悔点一起抹掉。
+     * attempt 名即恢复时间戳（restore.ts 的 preRestoreStamp，本地时间 yyyyMMdd-HHmmss-SSS[-序号]）；
+     * 解析不出来回落目录 mtime（手工改名的残留也能被淘汰，不会永久占位）。
+     */
+    async collectPreRestorePlan() {
+        const dir = this.options.dir;
+        const drops = [];
+        const now = Date.now();
+        const maxAgeMs = PRE_RESTORE_KEEP_DAYS * 24 * 60 * 60 * 1000;
+        for (const entry of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            if (!entry.isDirectory())
+                continue;
+            const preRoot = path.join(dir, entry.name, PRE_RESTORE_DIR_NAME);
+            const attempts = await fs.readdir(preRoot, { withFileTypes: true }).catch(() => null);
+            if (attempts === null)
+                continue;
+            const rows = [];
+            for (const a of attempts) {
+                if (!a.isDirectory())
+                    continue;
+                const at = parsePreRestoreStamp(a.name)
+                    ?? (await fs.stat(path.join(preRoot, a.name)).then((s) => s.mtimeMs).catch(() => now));
+                const names = await fs.readdir(path.join(preRoot, a.name), { recursive: true }).catch(() => []);
+                rows.push({ attempt: a.name, at, files: names.length });
+            }
+            rows.sort((x, y) => y.at - x.at); // 新 → 旧
+            rows.forEach((row, index) => {
+                if (index >= PRE_RESTORE_KEEP_ATTEMPTS) {
+                    drops.push({ snapshotId: entry.name, attempt: row.attempt, reason: 'count', files: row.files });
+                }
+                else if (now - row.at > maxAgeMs) {
+                    drops.push({ snapshotId: entry.name, attempt: row.attempt, reason: 'over-age', files: row.files });
+                }
+            });
+        }
+        return drops;
+    }
+    /** BK-05：手动触发一轮保留清理（与 save 后的自动清理同一实现）。 */
+    async pruneNow() {
+        return this.prune();
     }
     async load(id) {
         const raw = await fs.readFile(path.join(this.snapshotDir(id), 'snapshot.json'), 'utf8');

package/lib/core/import-defaults.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 导入执行策略的**唯一缺省**（IE-02）。
+ *
+ * 为什么单独一个零依赖模块：这个缺省必须被四处引用 —— 引擎 `src/core/importer.ts`、
+ * HTTP 路由 `src/routes/import.ts`、UI 向导 `src/ui/import-wizard.ts`、同步通道
+ * `src/sync/sync-engine.ts`。而 `src/ui/import-wizard.ts` 会被 `src/client/run-store.ts`
+ * 作为**值**导入并打进浏览器 bundle，所以它不能从 `src/core/importer.ts` 取这个值
+ * （那条路径经 Analyzer 拖进 node 内建与 ZIP 依赖）。本文件零依赖，两端都能安全引入。
+ *
+ * 语义：任一计划项失败立即整体回滚（安全侧，也就是 UI 文案「失败时整体回滚（推荐）」）。
+ * 要「单项失败如实记录并继续其余项」必须显式传 `false`，不再靠各入口各写一份缺省。
+ */
+export declare const DEFAULT_ROLLBACK_ON_ERROR = true;

package/lib/core/import-defaults.js

@@ -0,0 +1,14 @@
+/**
+ * 导入执行策略的**唯一缺省**（IE-02）。
+ *
+ * 为什么单独一个零依赖模块：这个缺省必须被四处引用 —— 引擎 `src/core/importer.ts`、
+ * HTTP 路由 `src/routes/import.ts`、UI 向导 `src/ui/import-wizard.ts`、同步通道
+ * `src/sync/sync-engine.ts`。而 `src/ui/import-wizard.ts` 会被 `src/client/run-store.ts`
+ * 作为**值**导入并打进浏览器 bundle，所以它不能从 `src/core/importer.ts` 取这个值
+ * （那条路径经 Analyzer 拖进 node 内建与 ZIP 依赖）。本文件零依赖，两端都能安全引入。
+ *
+ * 语义：任一计划项失败立即整体回滚（安全侧，也就是 UI 文案「失败时整体回滚（推荐）」）。
+ * 要「单项失败如实记录并继续其余项」必须显式传 `false`，不再靠各入口各写一份缺省。
+ */
+export const DEFAULT_ROLLBACK_ON_ERROR = true;
+//# sourceMappingURL=import-defaults.js.map

package/lib/core/importer.d.ts

@@ -10,6 +10,12 @@
  */
 import type { ZipArchive, ZipSafetyLimits } from '../utils/zip.ts';
 import type { MsgFunc } from './messages.ts';
+import { DEFAULT_ROLLBACK_ON_ERROR } from './import-defaults.ts';
+/**
+ * 缺省值的规范定义在 `./import-defaults.ts`（零依赖，UI 向导与浏览器 bundle 也引入它）；
+ * 这里再导出一份，宿主侧调用方（路由、同步通道、CLI）可以从引擎门面拿，不必记两个路径。
+ */
+export { DEFAULT_ROLLBACK_ON_ERROR };
 import type { PlanItemProgress } from './analyzer.ts';
 import type { BootSafetyReport } from './boot-safety.ts';
 import type { ConfigAdapter, HostContext, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult, SessionFormatProbeResult, SnapshotStore, TransactionSnapshotContext } from './types.ts';
@@ -38,7 +44,10 @@ export interface ExecuteOptions {
     secretInputs?: Record<string, string>;
     /** 加密备份解密结果（仅内存；解密必须经 m4 encryption provider） */
     decryptedCredentials?: Map<string, string>;
-    /** 任一项失败立即整体回滚（默认 false：单项失败如实记录并继续其余项） */
+    /**
+     * 任一项失败立即整体回滚。缺省 = `DEFAULT_ROLLBACK_ON_ERROR`（`./import-defaults.ts`，全仓唯一一份）；
+     * 要「单项失败如实记录并继续其余项」必须显式传 `false`。
+     */
     rollbackOnError?: boolean;
     /** m1：每完成一个计划项的进度回调（透传给 Analyzer；不传则无埋点） */
     onItem?: (info: PlanItemProgress) => void;

package/lib/core/importer.js

@@ -1,4 +1,10 @@
 import { Analyzer } from './analyzer.js';
+import { DEFAULT_ROLLBACK_ON_ERROR } from './import-defaults.js';
+/**
+ * 缺省值的规范定义在 `./import-defaults.ts`（零依赖，UI 向导与浏览器 bundle 也引入它）；
+ * 这里再导出一份，宿主侧调用方（路由、同步通道、CLI）可以从引擎门面拿，不必记两个路径。
+ */
+export { DEFAULT_ROLLBACK_ON_ERROR };
 export class Importer {
     analyzer;
     constructor(opts) {
@@ -26,7 +32,7 @@ export class Importer {
             confirm: opts.confirm,
             secretInputs: opts.secretInputs,
             decryptedCredentials: opts.decryptedCredentials,
-            rollbackOnError: opts.rollbackOnError,
+            rollbackOnError: opts.rollbackOnError ?? DEFAULT_ROLLBACK_ON_ERROR,
             onItem: opts.onItem,
             onItemStart: opts.onItemStart,
             onLog: opts.onLog,

package/lib/core/messages.d.ts

@@ -59,6 +59,7 @@ export declare const zh: {
     readonly 'import.unsupportedSectionVersion': '分区 {section} 的数据版本 {version} 高于本版本支持的 1（已跳过该分区）';
     readonly 'import.checksumsMissing': '备份未提供完整性校验表，全部条目未被校验';
     readonly 'import.extraEntries': 'ZIP 内含未登记进校验表的条目: {entries}（未被校验）';
+    readonly 'import.unverifiedFileEntry': '以下条目不在校验表内，无法校验，已逐条阻断写入（其余条目照常导入）: {entries}';
     readonly 'import.undeclaredSectionContent': '备份包含未声明的分区内容（清单里标为不包含，这些条目不会被导入）: {sections}；示例条目: {entries}';
     readonly 'import.secretsPayloadEmpty': '备份声明携带凭据值，但解出的凭据清单为空：这不是「没有凭据」，而是没读到（请确认备份密码与导出机的凭据库布局）';
     readonly 'import.migrated': '备份 schema 已从 v{from} 迁移到 v{to}';
@@ -329,6 +330,7 @@ export declare const zh: {
     readonly 'adapter.workspaceSessionsOutsideBundle': '另有 {count} 个会话不在此备份包内（本次未导入其数据），未登记；目标机本来就有这些会话则不受影响';
     readonly 'adapter.workspaceSessionsManual': '本机工作区服务不支持会话登记，{count} 个会话未登记：启动 DSH 后可在设置里重新导入，或用离线修复工具 sessions repair';
     readonly 'adapter.workspaceSessionsOwnerMissing': '找不到对应的目标工作区记录，{count} 个会话未登记：请确认备份里包含该工作区（导出会话时会自动连带其工作区）';
+    readonly 'adapter.selfImportBlocked': '包内含 {path}（同步目标配置）：已拒绝写入，本机同步目标保持不变';
     readonly 'adapter.providerMissing': '导入数据缺少 provider {route}';
     readonly 'adapter.namespaceMissing': '导入数据缺少 namespace {ref}';
     readonly 'adapter.validate.object': '{subject} 数据必须是对象';
@@ -375,6 +377,7 @@ export declare const zh: {
     readonly 'sync.changesSummary': 'compatibility={compatibility}，共 {count} 项变更';
     readonly 'sync.configWhitespace': '仓库地址不能包含空白字符';
     readonly 'sync.configUnparseable': '无法解析仓库地址: {url}';
+    readonly 'sync.configPrivateHost': '仓库地址指向本机或内网地址，不作为同步目标: {url}';
     readonly 'sync.configUserinfo': '请勿在仓库地址中包含用户名/密码（认证 token 请使用凭据字段，不会拼入地址）';
     readonly 'sync.state.notObject': 'sync-state.json 损坏：必须是对象';
     readonly 'sync.state.schemaUnsupported': 'sync-state.json schemaVersion 不支持: {version}（期望 {expected}）';
@@ -427,6 +430,7 @@ export declare const zh: {
     readonly 'sync.webdav.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}';
     readonly 'sync.pruneListFailed': '远端快照裁剪失败：无法列出远端快照，{reason}';
     readonly 'sync.pruneDeleteFailed': '远端快照裁剪失败：删除快照 {id} 失败，{reason}';
+    readonly 'sync.gcSkipped': '本轮已放弃回收远端孤立文件（{code}）：本轮不做回收，快照本身不受影响';
     readonly 'market.invalidItemId': '非法市场条目 id: {id}（仅允许字母数字开头，字符限 . _ -）';
     readonly 'market.urlWhitespace': '市场仓库地址不能包含空白字符';
     readonly 'market.urlUnparseable': '无法解析市场仓库地址: {url}';

package/lib/core/messages.js

@@ -44,6 +44,7 @@ export const zh = {
     'import.unsupportedSectionVersion': '分区 {section} 的数据版本 {version} 高于本版本支持的 1（已跳过该分区）',
     'import.checksumsMissing': '备份未提供完整性校验表，全部条目未被校验',
     'import.extraEntries': 'ZIP 内含未登记进校验表的条目: {entries}（未被校验）',
+    'import.unverifiedFileEntry': '以下条目不在校验表内，无法校验，已逐条阻断写入（其余条目照常导入）: {entries}',
     'import.undeclaredSectionContent': '备份包含未声明的分区内容（清单里标为不包含，这些条目不会被导入）: {sections}；示例条目: {entries}',
     'import.secretsPayloadEmpty': '备份声明携带凭据值，但解出的凭据清单为空：这不是「没有凭据」，而是没读到（请确认备份密码与导出机的凭据库布局）',
     'import.migrated': '备份 schema 已从 v{from} 迁移到 v{to}',
@@ -321,6 +322,7 @@ export const zh = {
     'adapter.workspaceSessionsOutsideBundle': '另有 {count} 个会话不在此备份包内（本次未导入其数据），未登记；目标机本来就有这些会话则不受影响',
     'adapter.workspaceSessionsManual': '本机工作区服务不支持会话登记，{count} 个会话未登记：启动 DSH 后可在设置里重新导入，或用离线修复工具 sessions repair',
     'adapter.workspaceSessionsOwnerMissing': '找不到对应的目标工作区记录，{count} 个会话未登记：请确认备份里包含该工作区（导出会话时会自动连带其工作区）',
+    'adapter.selfImportBlocked': '包内含 {path}（同步目标配置）：已拒绝写入，本机同步目标保持不变',
     'adapter.providerMissing': '导入数据缺少 provider {route}',
     'adapter.namespaceMissing': '导入数据缺少 namespace {ref}',
     // ---------- 适配器：结构校验（validate） ----------
@@ -369,6 +371,7 @@ export const zh = {
     'sync.changesSummary': 'compatibility={compatibility}，共 {count} 项变更',
     'sync.configWhitespace': '仓库地址不能包含空白字符',
     'sync.configUnparseable': '无法解析仓库地址: {url}',
+    'sync.configPrivateHost': '仓库地址指向本机或内网地址，不作为同步目标: {url}',
     'sync.configUserinfo': '请勿在仓库地址中包含用户名/密码（认证 token 请使用凭据字段，不会拼入地址）',
     'sync.state.notObject': 'sync-state.json 损坏：必须是对象',
     'sync.state.schemaUnsupported': 'sync-state.json schemaVersion 不支持: {version}（期望 {expected}）',
@@ -428,6 +431,7 @@ export const zh = {
     'sync.webdav.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}',
     'sync.pruneListFailed': '远端快照裁剪失败：无法列出远端快照，{reason}',
     'sync.pruneDeleteFailed': '远端快照裁剪失败：删除快照 {id} 失败，{reason}',
+    'sync.gcSkipped': '本轮已放弃回收远端孤立文件（{code}）：本轮不做回收，快照本身不受影响',
     // ---------- 配置市场（m-market：只读公开仓库目录读取 + 校验） ----------
     'market.invalidItemId': '非法市场条目 id: {id}（仅允许字母数字开头，字符限 . _ -）',
     'market.urlWhitespace': '市场仓库地址不能包含空白字符',
@@ -537,6 +541,7 @@ export const en = {
     'import.unsupportedSectionVersion': 'Section {section} data version {version} is higher than the supported version 1 (section skipped)',
     'import.checksumsMissing': 'Backup provides no integrity checksum table; no entry was verified',
     'import.extraEntries': 'ZIP contains entries not registered in the checksum table: {entries} (not verified)',
+    'import.unverifiedFileEntry': 'These entries are not covered by the checksum table and cannot be verified, so each was blocked (the rest import normally): {entries}',
     'import.undeclaredSectionContent': 'Backup contains content for undeclared sections (not marked as included; these entries will not be imported): {sections}; sample entries: {entries}',
     'import.secretsPayloadEmpty': 'The backup declares embedded secret values, but no credential ref could be read out of it: this is not "no credentials", it means they were not read (check the backup password and the source machine credential-store layout)',
     'import.migrated': 'Backup schema migrated from v{from} to v{to}',
@@ -814,6 +819,7 @@ export const en = {
     'adapter.workspaceSessionsOutsideBundle': 'A further {count} session(s) are not part of this backup (their data was not imported) and stay unregistered; sessions that already exist on this machine are unaffected',
     'adapter.workspaceSessionsManual': 'The host workspace service cannot attach sessions; {count} session(s) are unregistered: re-import from Settings once DSH is up, or use the offline tool: sessions repair',
     'adapter.workspaceSessionsOwnerMissing': 'No matching target workspace record, {count} session(s) unregistered: make sure the backup contains that workspace (exporting sessions now carries their workspaces automatically)',
+    'adapter.selfImportBlocked': 'Package contains {path} (sync target config): write refused, local sync target unchanged',
     'adapter.providerMissing': 'Import data is missing provider {route}',
     'adapter.namespaceMissing': 'Import data is missing namespace {ref}',
     // ---------- adapters: structural validation ----------
@@ -862,6 +868,7 @@ export const en = {
     'sync.changesSummary': 'compatibility={compatibility}, {count} change(s)',
     'sync.configWhitespace': 'Repository URL must not contain whitespace',
     'sync.configUnparseable': 'Cannot parse repository URL: {url}',
+    'sync.configPrivateHost': 'Repository URL points at this machine or a private network, so it is not accepted as a sync target: {url}',
     'sync.configUserinfo': 'Do not include a username/password in the repository URL (use the credential field for the auth token; it is never embedded in the URL)',
     'sync.state.notObject': 'sync-state.json is corrupt: must be an object',
     'sync.state.schemaUnsupported': 'sync-state.json schemaVersion not supported: {version} (expected {expected})',
@@ -917,6 +924,7 @@ export const en = {
     'sync.webdav.snapshotInvalid': 'Snapshot {id} failed to parse or is structurally invalid: {err}',
     'sync.pruneListFailed': 'Remote snapshot pruning failed: could not list remote snapshots, {reason}',
     'sync.pruneDeleteFailed': 'Remote snapshot pruning failed: deleting snapshot {id} failed, {reason}',
+    'sync.gcSkipped': 'Skipped reclaiming remote orphan files this round ({code}); snapshots are unaffected',
     // ---------- config marketplace (m-market: read-only public repo directory read + validation) ----------
     'market.invalidItemId': 'Invalid marketplace item id: {id} (must start with an alphanumeric; only . _ - allowed)',
     'market.urlWhitespace': 'Marketplace repository URL must not contain whitespace',

package/lib/core/model-tools.js

@@ -51,14 +51,30 @@ function dateStamp(d = new Date()) {
 function filterSectionIds(ids) {
     return ids.filter((id) => SECTION_IDS.includes(id));
 }
+/**
+ * SEC-03：把「读侧被白名单丢弃的配置」翻成一句可执行的补充说明。
+ * 只挑本通道的 issue —— git 地址被拒不该出现在 webdav 的错误里。
+ */
+function describeConfigIssues(issues, channel) {
+    const own = issues.filter((issue) => issue.channel === channel);
+    if (own.length === 0)
+        return '';
+    return own.map((issue) => `config issue ${issue.code} (${issue.channel}): ${issue.message}`).join('; ');
+}
 /** 解析同步引擎：channel 缺省取已配置的活动通道（git/webdav），未配置则抛可操作错误。 */
 async function resolveEngine(deps, channel) {
+    // SEC-03：两处读取都收集 issues —— 否则「地址被安全校验拒掉」会被报成
+    // 「sync-config.json 缺失或损坏」，让模型/用户反复重填同一个被拒地址。
+    const issues = [];
     // 未显式指定通道 → 取已配置的活动通道（唯一判定口径 parseSyncChannel；缺省 git）
-    const full = channel === undefined ? await readFullSyncConfig(deps.syncDir) : null;
+    const full = channel === undefined ? await readFullSyncConfig(deps.syncDir, issues) : null;
     const ch = channel ?? parseSyncChannel(full?.transport) ?? 'git';
-    const cfg = await readSyncConfigFor(deps.syncDir, ch);
+    const cfg = await readSyncConfigFor(deps.syncDir, ch, issues);
     if (cfg === null) {
-        throw new Error(engineMsg('core.modelTools.syncChannelNotConfigured', { channel: ch }));
+        const base = engineMsg('core.modelTools.syncChannelNotConfigured', { channel: ch });
+        const detail = describeConfigIssues(issues, ch);
+        // 无 issue = 真的没配（保持原文案）；有 issue = 说清成因，绝不吞掉
+        throw new Error(detail === '' ? base : `${base} — ${detail}`);
     }
     return { engine: deps.makeSyncEngine(cfg), channel: ch };
 }

package/lib/index.d.ts

@@ -77,7 +77,7 @@ export declare const name = "config-manager";
 /** Services required before the engine can mount (present in every profile). */
 export declare const inject: string[];
 /** Plugin version, kept in sync with package.json ("version"). */
-export declare const PLUGIN_VERSION = "0.2.3";
+export declare const PLUGIN_VERSION = "0.3.0";
 /**
  * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
  * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照