dsh-config-manager 0.2.4 → 0.3.0

package/lib/index.js

@@ -106,8 +106,9 @@ import { DEFAULT_RETENTION_POLICY, selectPruneCandidatesByPolicy } from './sync/
 import { selectPruneCandidates } from './core/backup.js';
 import { appendAutosyncEntry } from './sync/sync-history.js';
 import { MigrationStore, MIGRATION_HISTORY_DIR } from './core/migration-history.js';
-import { readSyncConfig, validateRepoUrl, validateWebDavUrl, isWebDavConfig, isS3Config, isGistConfig, channelOf, parseSyncChannel, SYNC_CHANNELS, GIST_PROVIDER, isS3CompatProvider, validateCloudChannelInput, cloudSecretRef } from './sync/sync-config.js';
+import { validateRepoUrl, validateWebDavUrl, isWebDavConfig, isS3Config, isGistConfig, channelOf, parseSyncChannel, SYNC_CHANNELS, GIST_PROVIDER, isS3CompatProvider, validateCloudChannelInput, cloudSecretRef } from './sync/sync-config.js';
 import { resolveSessionFormatDisposition, sessionFormatAbortResponse, } from './routes/session-format.js';
+import { createPrepareSync } from './sync/config-issue-reporting.js';
 import { AUTO_SYNC_OPT_IN_SECTIONS, defaultSyncSelection, effectiveSections, OPT_IN_SYNC_SECTIONS, readAllSyncSelections, readSyncSelection } from './sync/sync-selection.js';
 import { GitMarketReader } from './market/reader.js';
 import { parseMarketIndex } from './market/index-parser.js';
@@ -136,7 +137,7 @@ export const name = 'config-manager';
 /** Services required before the engine can mount (present in every profile). */
 export const inject = ['settings', 'credentials'];
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.2.4';
+export const PLUGIN_VERSION = '0.3.0';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**
@@ -2450,26 +2451,15 @@ function makeRoutes(deps) {
     // 请求级装配：每次 push/pull 从请求体取 repoUrl，token 非空先写入 DSH
     // credentials（只存值不落盘同步文件/日志），git 网络操作时经 resolve 现取 ——
     // 与 GitTransport「token 只从注入 provider 读取」的安全契约完全对齐。
-    /**
-     * 解析同步请求体并补全缺失字段（委托给导出的 parseSyncBody，便于单测）。
-     * username 回退：webdav 请求体未带 username（如挂载时 snapshotsList 自动加载、
-     * 表单留空后直接同步）时，从持久化 sync-config 回填已保存的 username——
-     * 否则 WebDavTransport 构造会因空 username 抛错，导致「保存过配置仍无法列出快照」。
-     * 语义与 password 一致：留空 = 沿用已保存凭据。
-     */
-    const prepareSync = async (body) => {
-        const cfg = await parseSyncBody(body, { credentials });
-        if (isWebDavConfig(cfg) && (cfg.webdav.username === undefined || cfg.webdav.username === '')) {
-            try {
-                const persisted = await readSyncConfig(syncDir);
-                return mergePersistedWebDavUsername(cfg, persisted);
-            }
-            catch {
-                return cfg; // 读失败保持原值（空 username 由 WebDavTransport 构造校验兜底报错）
-            }
-        }
-        return cfg;
-    };
+    // 同步请求体准备 = 「webdav username 回填 + SEC-03 配置被拒的一次性告警」。
+    // 解析/去重/文案与读侧语义都在 src/sync/config-issue-reporting.ts（含单测），
+    // 这里只做装配：宿主只提供 credentials、日志出口与配置目录。
+    const prepareSync = createPrepareSync({
+        syncDir,
+        parseBody: (body) => parseSyncBody(body, { credentials }),
+        mergeWebDavUsername: mergePersistedWebDavUsername,
+        log: (line) => host.log.warn(line),
+    });
     /** 同步分区选择缓存（按通道；sync-selection.json；makeSyncEngine 同步读取用，保存路由更新）。
      *  缺失通道 = 尚未加载（启动竞态窗口）；读取/使用处兜底 defaultSyncSelection。 */
     const selectionCache = {};

package/lib/routes/import.js

@@ -5,6 +5,7 @@
  * path/methods 就是唯一声明处；围栏、方法判定与顶层异常处理由 src/routes/kit.ts 在注册点统一提供。
  */
 import { endpoint, requireJsonObject, readJsonBody, writeJson, queryParam } from './kit.js';
+import { DEFAULT_ROLLBACK_ON_ERROR } from '../core/import-defaults.js';
 import { decryptErrorText, isControlledPath, tryDecryptCredentials, writeRequestBodyToFile } from './route-support.js';
 import { resolveSessionFormatDisposition, sessionFormatAbortResponse } from './session-format.js';
 import { ENCRYPTED_CONTAINER_CODE, SecurityError, decryptArchive, isArchiveBlob, readContainerKind, verifyEncryptedBlob } from '../security/index.js';
@@ -237,7 +238,8 @@ export function importRoutes(env) {
                     secretInputs: opts['secretInputs'] !== null && typeof opts['secretInputs'] === 'object'
                         ? opts['secretInputs']
                         : {},
-                    rollbackOnError: opts['rollbackOnError'] === true,
+                    // IE-02：调用方没写就落全仓同一缺省，别在这里另立一份 true/false
+                    rollbackOnError: typeof opts['rollbackOnError'] === 'boolean' ? opts['rollbackOnError'] : DEFAULT_ROLLBACK_ON_ERROR,
                     decryptedCredentials,
                     // Phase 4 生产 snapshot 接线：deferred journal 绑定的 ctx 透传给引擎，
                     // 使快照创建后立即 bindSnapshot（SNAPSHOT_CREATED）→ markApplying（APPLYING）再执行。

package/lib/routes/recovery.js

@@ -17,7 +17,11 @@ import { EnvironmentLockUnavailableError, runWithMutationLock } from '../utils/e
 import { scanSessionHealth } from '../utils/session-health-scan.js';
 import { applySessionTitles } from '../core/session-meta.js';
 import { applySessionLogTitles } from '../core/session-title.js';
-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.js';
+import { writeZip } from '../utils/zip.js';
+import { isValidSnapshotId } from '../core/restore.js';
 import { applySessionRepair, listSessionRepairs, previewSessionRepair, rollbackSessionRepair, } from '../utils/session-repair-service.js';
 import { applySessionLayoutRepair, planSessionLayoutRepair } from '../utils/session-layout-repair-service.js';
 import { sessionHealthNextSteps } from './route-support.js';
@@ -306,8 +310,185 @@ function incompleteCopiesOf(profiles) {
         return { copies: [], unreadable: true };
     }
 }
+/* ------------------------------------------------------------------ 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]+)?$/;
+function isPreRestoreAttemptName(name) {
+    return typeof name === 'string' && PRE_RESTORE_ATTEMPT_RE.test(name);
+}
+/**
+ * 递归走一遍 attempt 目录，只**读元数据**（readdir + stat），不读文件内容。
+ * symlink 不跟随（只计数）：反悔副本里出现链接本身就可疑，跟过去会把 home 外的东西带进 zip。
+ * 超深度 / 超文件数 / 超字节即 `truncated` —— 调用方必须把截断当成「没说全」，不能当成「就这么多」。
+ */
+async function walkPreRestore(dir, maxBytes) {
+    const files = [];
+    let totalBytes = 0;
+    let skippedLinks = 0;
+    let truncated = false;
+    const walk = async (current, rel, depth) => {
+        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) {
+    const roots = await readdir(snapshotsDir, { withFileTypes: true }).catch(() => null);
+    if (roots === null) {
+        // 与 listSnapshots 同口径：读不动就如实说「读不动」，不抛 500、也不假装「没有反悔副本」
+        return { readOnly: true, snapshots: [], unreadable: snapshotsDir };
+    }
+    const snapshots = [];
+    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) => error);
+        if (!Array.isArray(entries)) {
+            const code = entries.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 = [];
+        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 } : {}) });
+    }
+    return { readOnly: true, snapshots, unreadable: null };
+}
+/**
+ * 把某个 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, body) {
+    const fail = (status, code, detail) => ({ 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 = [];
+    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) {
-    const { dataDir, host, makeRecoveryExecutors, profiles, recoveryOrchestrator, sessionHealth, tryAppendHistory, } = env;
+    const { dataDir, host, makeRecoveryExecutors, profiles, recoveryOrchestrator, sessionHealth, snapshotsDir, tryAppendHistory, } = env;
     return [
         // ------------------------------------------------------------ recovery
         // Phase 5：recovery 编排（prefix 路由，内部按 path 分发）。
@@ -526,6 +707,49 @@ export function recoveryRoutes(env) {
                 }
                 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/lib/routes/sync.js

@@ -145,8 +145,12 @@ export function syncRoutes(env) {
      */
     const collectSyncStatus = async (opts) => {
         // 完整双命名空间配置：repoUrl / webdav.url 无论当前通道都回填，
-        // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失
-        const full = await readFullSyncConfig(syncDir);
+        // 保证 UI 在 git ↔ webdav 间切换时另一通道的地址不丢失。
+        // SEC-03 读侧可见性：已落盘但过不了白名单的 repoUrl 会被 readFullSyncConfig 丢弃
+        // （绝不交给凭据注入/git 子进程），但**必须把成因带出去** —— 否则界面显示「未配置」，
+        // 用户永远看不出自己保存过的地址是被安全校验拒掉，而不是从来没存过。
+        const configIssues = [];
+        const full = await readFullSyncConfig(syncDir, configIssues);
         const state = await loadSyncState(syncDir);
         const [cred, webdavCred] = await Promise.all([
             credentials.describe(credentialRef(SYNC_CREDENTIAL_REF)),
@@ -179,6 +183,9 @@ export function syncRoutes(env) {
             configured: full !== null,
             transport,
             repoUrl: full?.git?.repoUrl,
+            // 被丢弃的通道配置成因（默认空数组：字段恒在，客户端不必判 undefined；
+            // 合法配置不产生幻影告警）。code 是机读 token，message 可直接展示。
+            configIssues,
             credentialConfigured: cred.configured,
             credentialWritable: cred.writable === true,
             // webdav 配置状态（无 secret 值：口令用 passwordConfigured 布尔标记）
@@ -251,10 +258,17 @@ export function syncRoutes(env) {
                     writeJson(res, 400, { error: msg('sync.workdirRecloneNeedsConfirm') });
                     return;
                 }
-                const full = await readFullSyncConfig(syncDir);
+                const configIssues = [];
+                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);
@@ -326,11 +340,15 @@ export function syncRoutes(env) {
                     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 = [];
+                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,
@@ -769,8 +787,9 @@ export function syncRoutes(env) {
                 }
                 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/lib/security/integrity.d.ts

@@ -25,5 +25,29 @@ export declare function parseChecksumsTable(raw: string, opts?: ChecksumsTableOp
 export declare function verifyChecksums(entries: ReadonlyMap<string, Uint8Array>, table: Record<string, string>): ChecksumVerifyResult;
 /** 一步到位：解析 checksums.json 原文并校验（解析失败抛错；不符返回 {ok:false,...}） */
 export declare function verifyChecksumsJson(entries: ReadonlyMap<string, Uint8Array>, raw: string, opts?: ChecksumsTableOptions): ChecksumVerifyResult;
+/**
+ * 会落盘的文件分区条目「未登记进校验表」时的错误码（写进 `PlanItem.detail`，也进执行报告）。
+ *
+ * 语义不是「哈希不符」（那由 `import.integrityFailed` 表示，且直接失败），而是
+ * 「这个条目根本没被校验表覆盖」—— 完整性声明对它零约束（SEC-05）。
+ */
+export declare const UNVERIFIED_FILE_ENTRY_CODE = "unverified-file-entry";
+/**
+ * 上述状态的文案键。字典条目由维护方补齐；缺失时 messages 回退成键名本身、绝不抛错，
+ * 所以导入流程不会因为缺一条文案而中断。
+ */
+export declare 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 declare function unverifiedEntries(names: readonly string[], table: Record<string, string>, exclude?: readonly string[]): string[];
 /** 人类可读的不匹配摘要（给「Backup integrity check failed」错误消息用） */
 export declare function describeMismatches(result: ChecksumVerifyResult): string;

package/lib/security/integrity.js

@@ -10,6 +10,8 @@
  *    危险键（防 prototype pollution）；解析失败抛错 → 导入方归为「Backup integrity check failed」。
  *  - 一步到位 `verifyChecksumsJson`：解析 + 校验合并，供 m5/导入管线直接调用。
  *  - 校验语义：表内每个路径必须在条目集合中存在且 SHA-256 一致；缺失与不符均计入 mismatches。
+ *  - 反向覆盖（SEC-05）：`unverifiedEntries` 算出「ZIP 有、表里没登记」的条目 —— 正向校验看不到
+ *    它们，而文件类分区按归档名原样落盘，缺了这条判定就等于「完整性只覆盖一半」。
  */
 import { parseJsonSafe } from '../utils/json.js';
 import { buildChecksums as coreBuildChecksums, verifyChecksums as coreVerifyChecksums, } from '../utils/hashing.js';
@@ -67,6 +69,34 @@ export function verifyChecksumsJson(entries, raw, opts = {}) {
     const table = parseChecksumsTable(raw, opts);
     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, table, exclude = []) {
+    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) {
     const parts = [

package/lib/security/unverified-file-blocks.d.ts

@@ -0,0 +1,73 @@
+import type { ChecksumVerifyResult } from '../utils/hashing.ts';
+import type { MsgFunc } from '../core/msg-types.ts';
+/**
+ * 本模块需要的计划项字段（结构子集）。刻意不 import `core/types.ts` 的 `PlanItem`：
+ * 值依赖方向是 core → security，security 只描述契约。
+ */
+export interface UnverifiedBlockableItem {
+    adapter: string;
+    kind: string;
+    severity?: string;
+    detail?: string;
+    description?: string;
+    target?: {
+        ref?: string;
+    } | undefined;
+}
+export declare function unverifiedFileEntryText(text: MsgFunc, names: readonly string[]): string;
+/**
+ * 未覆盖条目的**唯一**一条告警（RV1-F11：同一事实只发一次，不再与 `import.extraEntries` 并存）。
+ *
+ * 键按「到底拦没拦」选，避免文案自称做了没做的事：
+ *  - 真拦下了（blocked > 0）⇒ 专属键 `import.unverifiedFileEntry`（「已逐条阻断写入」）；
+ *  - 一个都没拦（豁免分区 / 不在任何文件分区前缀下的散落条目，守 INT-01）⇒ 中性口径 `import.extraEntries`。
+ */
+export declare function unverifiedNoticeText(text: MsgFunc, names: readonly string[], blocked: number): string;
+/**
+ * 校验表**覆盖不到**的条目（反向覆盖）。
+ *
+ * - 表存在且非空：表里没登记的条目（`unverifiedEntries` 的判据，正向校验看不到它们）；
+ * - 表**缺失/为空**：一个条目都没被校验 ⇒ 文件分区前缀下的条目一律视为未覆盖。
+ *   这是 RV1-F1 抓到的绕过：删掉 `integrity/checksums.json`（或置 `{}`）就等于把 SEC-05 关掉。
+ *   口径选「逐条 fail-closed」而非整包拒：旧包/手工包的非文件分区（settings 等）照常导入，
+ *   被拦下的只是「按归档名原样落盘、完整性声明又完全管不到」的那部分。
+ *
+ * 文案不在这里出（RV1-F11）：同一事实只由 `analyzeImport` 发一条 `import.unverifiedFileEntry`。
+ */
+export declare function scanUnverifiedEntries(names: readonly string[], table: Record<string, string> | null): string[];
+/**
+ * 把命中「表外 + 会写盘」的文件分区计划项升级为 Error。
+ *
+ * 为什么必须拦：文件集合分区按归档名原样落盘（`adapters/file-collection.ts` 的 applyItem 只看
+ * `target.ref`），而 `verifyAgainstTable` 只正向校验表里登记的条目 —— 表外文件一路绿灯。
+ * 拦在执行之前、拦在计划项上（kind:'Error'）：`applyOne` 遇到 Error 直接记 failed、绝不写目标，
+ * 用户也能在预览里看到「为什么这条没导」。
+ *
+ * @returns 被阻断的归档条目名（按计划项顺序，供调用方汇总一条提示）
+ */
+export declare function applyUnverifiedFileBlocks(unverified: readonly string[], items: UnverifiedBlockableItem[], fileSections: ReadonlySet<string>, exemptSections: readonly string[], text: MsgFunc): string[];
+/** ZIP 归档读取子集（结构子集：`ZipArchive` 可赋值）；本模块不 import core 的 ZIP 解析。 */
+export interface IntegrityArchive {
+    has(name: string): boolean;
+    names(): string[];
+    readEntryText(name: string): string;
+    readEntryAsync(name: string): Promise<Uint8Array>;
+}
+export interface ArchiveIntegrityScan {
+    checksums: ChecksumVerifyResult;
+    /** 表外条目（反向覆盖）；校验表缺失/为空时 = 文件分区前缀下的全部条目（见 scanUnverifiedEntries） */
+    unverified: string[];
+    /** 要挂进 zipWarnings 的文案（目前只有「校验表缺失」；反向覆盖文案由 analyzeImport 统一发一条） */
+    warnings: string[];
+    /** 完整性不符时的错误文案；undefined = 通过（调用方自己 throw，文案由注入的 msg 决定） */
+    failure?: string;
+}
+/**
+ * 归档完整性扫描：正向（表内每条必须存在且 SHA-256 一致）+ 反向（ZIP 有、表里没登记）。
+ *
+ * 正向用 `utils/hashing.ts` 的 `verifyChecksums` —— 与 `import-planning.ts` 里的同名判据逐字等价，
+ * 是同一份语义的规范实现，此处不再复制第二遍。
+ * 判定却必须与导入阻断共用（`scanUnverifiedEntries` / `unverifiedEntries`），否则「告警说的表外条目」
+ * 与「真正被拦下的条目」会分叉。
+ */
+export declare function scanArchiveIntegrity(archive: IntegrityArchive, text: MsgFunc): Promise<ArchiveIntegrityScan>;