dsh-config-manager 0.2.4 → 0.3.0

package/lib/security/unverified-file-blocks.js

@@ -0,0 +1,151 @@
+/**
+ * SEC-05（表外条目）的**唯一**判定点：把「未登记进校验表、却会被落盘」的文件分区计划项
+ * 拦在执行之前。
+ *
+ * 为什么单独成模块：
+ *  - 判据落在一处才审得动 —— 文件前缀组合、会写盘的 kind、目录/结构文件排除，任何一处改口径都
+ *    同时影响「告警」与「阻断」，两边分叉就等于自己骗自己；
+ *  - `src/core/analyzer.ts` 有体量棘轮（tests/file-size-ratchet.test.ts），这类判定应下沉到
+ *    `src/security/`，而不是让分析器继续变胖。
+ *
+ * 本模块**不**反向依赖 `src/core/*` 的值：只声明用到的字段结构（`PlanItem` 结构可赋值），
+ * 消息翻译走注入的 `MsgFunc`，因此不与 core 形成环。
+ */
+import { SECTION_FILE_PREFIXES } from '../schema/config.js';
+import { CHECKSUMS_FILE, MANIFEST_FILE } from '../schema/manifest.js';
+import { parseJsonSafe } from '../utils/json.js';
+import { verifyChecksums } from '../utils/hashing.js';
+import { UNVERIFIED_FILE_ENTRY_CODE, UNVERIFIED_FILE_ENTRY_KEY, unverifiedEntries } from './integrity.js';
+/**
+ * SEC-05 文案：优先用专属键 `import.unverifiedFileEntry`。
+ *
+ * 字典还没收录该键时 `msg` 会回退成键名本身（messages.ts 的「未知键绝不抛错」约定），
+ * 那样文案里只有键名、**连是哪个文件都没说** —— 对用户是最糟的形态。因此回退到既有的
+ * `import.extraEntries`（已翻译、也带条目名）。两段指向同一事实：「这个条目没被校验表覆盖」。
+ */
+/** 单条文案最多列几个条目 —— 校验表缺失时名单 = 整包文件分区条目，不截断会撑爆一条 warning。 */
+const MAX_LISTED_ENTRIES = 10;
+export function unverifiedFileEntryText(text, names) {
+    return render(text, UNVERIFIED_FILE_ENTRY_KEY, names);
+}
+function render(text, key, names) {
+    const head = names.slice(0, MAX_LISTED_ENTRIES).map((n) => `"${n}"`).join(', ');
+    const list = names.length > MAX_LISTED_ENTRIES ? `${head} …(+${names.length - MAX_LISTED_ENTRIES})` : head;
+    const rendered = text(key, { entries: list });
+    return rendered === key ? text('import.extraEntries', { entries: list }) : rendered;
+}
+/**
+ * 未覆盖条目的**唯一**一条告警（RV1-F11：同一事实只发一次，不再与 `import.extraEntries` 并存）。
+ *
+ * 键按「到底拦没拦」选，避免文案自称做了没做的事：
+ *  - 真拦下了（blocked > 0）⇒ 专属键 `import.unverifiedFileEntry`（「已逐条阻断写入」）；
+ *  - 一个都没拦（豁免分区 / 不在任何文件分区前缀下的散落条目，守 INT-01）⇒ 中性口径 `import.extraEntries`。
+ */
+export function unverifiedNoticeText(text, names, blocked) {
+    return render(text, blocked > 0 ? UNVERIFIED_FILE_ENTRY_KEY : 'import.extraEntries', names);
+}
+/** 归档里的结构文件（不属于内容，永不参与「未覆盖」判定）。 */
+const STRUCTURAL_FILES = [MANIFEST_FILE, CHECKSUMS_FILE];
+/** 落在文件分区前缀下的归档条目（目录标记条目与结构文件排除）。 */
+function fileSectionEntries(names) {
+    const skip = new Set(STRUCTURAL_FILES);
+    const prefixes = Object.values(SECTION_FILE_PREFIXES).filter((prefix) => prefix !== '');
+    return names.filter((n) => !n.endsWith('/') && !skip.has(n) && prefixes.some((p) => n.startsWith(p)));
+}
+/**
+ * 校验表**覆盖不到**的条目（反向覆盖）。
+ *
+ * - 表存在且非空：表里没登记的条目（`unverifiedEntries` 的判据，正向校验看不到它们）；
+ * - 表**缺失/为空**：一个条目都没被校验 ⇒ 文件分区前缀下的条目一律视为未覆盖。
+ *   这是 RV1-F1 抓到的绕过：删掉 `integrity/checksums.json`（或置 `{}`）就等于把 SEC-05 关掉。
+ *   口径选「逐条 fail-closed」而非整包拒：旧包/手工包的非文件分区（settings 等）照常导入，
+ *   被拦下的只是「按归档名原样落盘、完整性声明又完全管不到」的那部分。
+ *
+ * 文案不在这里出（RV1-F11）：同一事实只由 `analyzeImport` 发一条 `import.unverifiedFileEntry`。
+ */
+export function scanUnverifiedEntries(names, table) {
+    if (table === null || Object.keys(table).length === 0)
+        return fileSectionEntries(names);
+    return unverifiedEntries(names, table, STRUCTURAL_FILES);
+}
+/** 会写盘的计划项 kind（Skip 本来就不写目标，改成 Error 只会让无害 no-op 显示成失败）。 */
+const WRITING_KINDS = new Set(['Create', 'Update', 'Conflict']);
+/**
+ * 把命中「表外 + 会写盘」的文件分区计划项升级为 Error。
+ *
+ * 为什么必须拦：文件集合分区按归档名原样落盘（`adapters/file-collection.ts` 的 applyItem 只看
+ * `target.ref`），而 `verifyAgainstTable` 只正向校验表里登记的条目 —— 表外文件一路绿灯。
+ * 拦在执行之前、拦在计划项上（kind:'Error'）：`applyOne` 遇到 Error 直接记 failed、绝不写目标，
+ * 用户也能在预览里看到「为什么这条没导」。
+ *
+ * @returns 被阻断的归档条目名（按计划项顺序，供调用方汇总一条提示）
+ */
+export function applyUnverifiedFileBlocks(unverified, items, fileSections, exemptSections, text) {
+    if (unverified.length === 0)
+        return [];
+    const unverifiedSet = new Set(unverified);
+    const exempt = new Set(exemptSections);
+    const blocked = [];
+    for (const item of items) {
+        if (!fileSections.has(item.adapter) || exempt.has(item.adapter))
+            continue;
+        if (!WRITING_KINDS.has(item.kind))
+            continue;
+        const ref = item.target?.ref;
+        if (ref === undefined)
+            continue;
+        const archiveName = (SECTION_FILE_PREFIXES[item.adapter] ?? '') + ref;
+        if (!unverifiedSet.has(archiveName))
+            continue;
+        item.kind = 'Error';
+        item.severity = 'error';
+        item.detail = UNVERIFIED_FILE_ENTRY_CODE;
+        item.description = unverifiedFileEntryText(text, [archiveName]);
+        blocked.push(archiveName);
+    }
+    return blocked;
+}
+/**
+ * 归档完整性扫描：正向（表内每条必须存在且 SHA-256 一致）+ 反向（ZIP 有、表里没登记）。
+ *
+ * 正向用 `utils/hashing.ts` 的 `verifyChecksums` —— 与 `import-planning.ts` 里的同名判据逐字等价，
+ * 是同一份语义的规范实现，此处不再复制第二遍。
+ * 判定却必须与导入阻断共用（`scanUnverifiedEntries` / `unverifiedEntries`），否则「告警说的表外条目」
+ * 与「真正被拦下的条目」会分叉。
+ */
+export async function scanArchiveIntegrity(archive, text) {
+    const warnings = [];
+    const names = archive.names();
+    // 校验表缺失或为空：全部条目都处于「未登记 ⇒ 未被校验」，两种形态对用户是同一件事，共用一条告警。
+    // 此时 checksums 恒 ok（没有可正向校验的声明），防线全靠下一行 scanUnverifiedEntries 的 fail-closed。
+    const table = archive.has(CHECKSUMS_FILE)
+        ? parseJsonSafe(archive.readEntryText(CHECKSUMS_FILE))
+        : null;
+    if (table === null || Object.keys(table).length === 0)
+        warnings.push(text('import.checksumsMissing'));
+    let checksums = { ok: true, mismatches: [], missing: [] };
+    if (table !== null && Object.keys(table).length > 0) {
+        const entries = new Map();
+        // 异步解压：这是全仓唯一逐条解压全部条目的地方（`inflateRawSync` 会整段阻塞事件循环）。
+        for (const name of names) {
+            if (name === MANIFEST_FILE || name === CHECKSUMS_FILE)
+                continue;
+            try {
+                entries.set(name, await archive.readEntryAsync(name));
+            }
+            catch {
+                entries.delete(name); // 损坏条目在完整性阶段即失败（最终体现为 missing）
+            }
+        }
+        checksums = verifyChecksums(entries, table);
+    }
+    // 反向覆盖只出条目名，文案统一由 analyzeImport 发一条（RV1-F11：同一事实不重复告警）。
+    const unverified = scanUnverifiedEntries(names, table);
+    const failure = checksums.ok
+        ? undefined
+        : text('import.integrityFailed', {
+            entries: [...checksums.mismatches, ...checksums.missing].map((m) => `"${m}"`).join(', '),
+        });
+    return { checksums, unverified, warnings, ...(failure !== undefined ? { failure } : {}) };
+}
+//# sourceMappingURL=unverified-file-blocks.js.map

package/lib/sync/autosync-config.d.ts

@@ -21,15 +21,19 @@ export type AutosyncAutoApplyTier = 'low' | 'medium';
 export declare const DEFAULT_AUTOSYNC_AUTO_APPLY_TIER: AutosyncAutoApplyTier;
 /**
  * 双侧都改（真冲突）时的自动裁决策略：
- *  - 'ask'   ：保留冲突待人工裁决（改造前的唯一行为）；
- *  - 'local' ：缺省 —— **保留本机并推上去**（VS Code 风格）：本机版本成为新的远端最新，
- *              被覆盖的远端版本仍留在远端历史快照里，随时可回滚。
+ *  - 'ask'   ：缺省 —— 保留冲突待人工裁决，冲突期间**零写入**（下行不动、上行不 force）；
+ *  - 'local' ：用户显式选中才生效 —— **保留本机并推上去**（VS Code 风格）：本机版本成为新的
+ *              远端最新，被覆盖的远端版本仍留在远端历史快照里，随时可回滚。
+ *
+ * SYN-05 为什么把缺省从 'local' 改成 'ask'：'local' 缺省会在「首轮」与「远端刚出现新快照」
+ * 这两个高危时刻静默用本机覆盖远端最新（用户根本没看见那段远端改动就被盖掉）。缺省必须选
+ * **安全且可逆**的一侧 = ask；想覆盖必须自己选，且首轮 / 远端有新快照时仍降级为 ask（forced）。
  *
  * 刻意**不提供** 'remote'：采用远端需要走 applyMergeResolutions，那条路径会整体应用所有
  * 可决断分区、绕过 risk.ts 的风险分级（audit-sync sync-F5），与「分区逐档放行」冲突。
  */
 export type AutosyncConflictPolicy = 'ask' | 'local';
-/** 缺省冲突策略：local（保留本机并推上去） */
+/** 缺省冲突策略：ask（冲突待人工裁决；显式写过 local 的旧配置仍按 local 生效） */
 export declare const DEFAULT_AUTOSYNC_CONFLICT_POLICY: AutosyncConflictPolicy;
 /** 最近一次自动同步执行状态 */
 export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';

package/lib/sync/autosync-config.js

@@ -35,8 +35,8 @@ export const MIN_AUTOSYNC_REMOTE_CHECK_MS = 15 * 1000;
 export const MAX_AUTOSYNC_REMOTE_CHECK_MS = 60 * 60 * 1000;
 /** 缺省自动应用等级：medium（用户拍板：plugins/mcp 的中风险改动也要真自动，否则「同步所有改动」是假的） */
 export const DEFAULT_AUTOSYNC_AUTO_APPLY_TIER = 'medium';
-/** 缺省冲突策略：local（保留本机并推上去） */
-export const DEFAULT_AUTOSYNC_CONFLICT_POLICY = 'local';
+/** 缺省冲突策略：ask（冲突待人工裁决；显式写过 local 的旧配置仍按 local 生效） */
+export const DEFAULT_AUTOSYNC_CONFLICT_POLICY = 'ask';
 /** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
 export function defaultAutosyncConfig() {
     return {

package/lib/sync/autosync-scheduler.d.ts

@@ -7,9 +7,10 @@ import type { SyncEngine } from './sync-engine.ts';
 import type { SyncSnapshotMeta } from './transport.ts';
 import type { MutationLockPort, MutationLockContext } from '../utils/env-lock.ts';
 import type { AutosyncConfig, AutosyncInterval } from './autosync-config.ts';
-import type { SyncConfig, SyncTransportType } from './sync-config.ts';
+import type { SyncConfig, SyncConfigIssue, SyncTransportType } from './sync-config.ts';
 import { readSyncHistory } from './sync-history.ts';
 import type { AutosyncHistoryEntry } from './sync-history.ts';
+import type { AutosyncConflictPolicy } from './autosync-config.ts';
 import type { MergePlan } from './merge.ts';
 import type { SyncApplyPlan } from './risk.ts';
 import { SyncWatcher } from './sync-watcher.ts';
@@ -32,7 +33,40 @@ export interface AutosyncRunResult {
     error?: string;
     historyId: string;
     consecutiveFailures: number;
+    /**
+     * SYN-05：本轮 ask 是**被强制**的（首轮或远端有新快照），不是用户选的 ask。
+     * 界面据此说清「这次没让你选」，避免用户以为自己的 local 设置失效了。
+     */
+    forced?: boolean;
+    /**
+     * SEC-03：本轮 skipReason='unconfigured' 时，已落盘配置为何被读侧丢弃（地址被白名单拒绝）。
+     * 缺省 undefined = 真的没配。有值就必须让用户看见 —— 否则「保存过却被拒」和
+     * 「从来没配」在界面上长得一模一样，用户会反复重填同一个被拒地址。
+     */
+    configIssue?: string;
 }
+/**
+ * SYN-05：本轮冲突（下行冲突）该不该 force push —— 唯一判定点。
+ *
+ * 规则（缺省 ask 之上再加两道高危闸）：
+ *  - 用户没选过策略 → 用缺省（ask）；
+ *  - **首轮**（从未跑过）或**远端有新快照**：即使显式选了 'local' 也强制降级 ask（forcedAsk）——
+ *    这两个时刻正是「远端最新改动只在历史快照里」的事故现场，静默覆盖等于替用户丢数据；
+ *    降级记 forced，界面才能说清「这次没按你的 local 走」；
+ *  - 只有「显式 local + 非高危时刻 + 真有冲突」才 force。
+ *
+ * 纯函数（无状态、无 I/O）：调度层与单测共用同一份判定，避免两处各写一遍阈值。
+ */
+export declare function resolveConflictPushPolicy(args: {
+    configuredPolicy?: AutosyncConflictPolicy;
+    firstRun: boolean;
+    remoteNew: boolean;
+    conflicted: number;
+}): {
+    policy: AutosyncConflictPolicy;
+    force: boolean;
+    forcedAsk: boolean;
+};
 /**
  * runOnce 的触发语义（只影响「做什么」的两个分支，不改变同步流程本身）。
  * reason 只进日志，用来说明这一轮是被谁叫醒的（排障时能区分「定时兜底」与「真有事发生」）。
@@ -67,7 +101,11 @@ export interface AutoSyncSchedulerOptions {
     readConfig?: (channel: SyncTransportType) => Promise<AutosyncConfig>;
     writeConfig?: (channel: SyncTransportType, cfg: AutosyncConfig) => Promise<void>;
     /** 注入 sync-config 读取（按通道） */
-    readSyncConfigFn?: (channel: SyncTransportType) => Promise<SyncConfig | null>;
+    /**
+     * SEC-03：可选第二参收集「读侧被丢弃的配置成因」。既有注入实现（单参闭包）依然合法 ——
+     * 少一个参数不是类型错误，缺省接线才负责真正回填。
+     */
+    readSyncConfigFn?: (channel: SyncTransportType, issues?: SyncConfigIssue[]) => Promise<SyncConfig | null>;
     /** 注入 sync-history 读写 */
     readHistoryFn?: () => Promise<Awaited<ReturnType<typeof readSyncHistory>>>;
     appendHistoryFn?: (entry: AutosyncHistoryEntry) => Promise<void>;
@@ -164,11 +202,25 @@ export declare class AutoSyncScheduler {
     private readonly profile;
     private readonly makeWatcher;
     private readonly minTriggerGapMs;
+    /** SEC-03：已 warn 过的「地址被拒」成因（键 = 通道 + 成因文本），进程内去重。 */
+    private readonly reportedConfigIssues;
     private stopped;
     private running;
     constructor(opts: AutoSyncSchedulerOptions);
-    /** 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。 */
+    /**
+     * 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。
+     *
+     * SYN-05：额外允许 forced（本轮 ask 是被强制的）。该字段不在 sync-history.ts 的
+     * AutosyncHistoryEntry 里（那是另一个模块的公开契约，本轮不扩），但读写两侧都按普通对象
+     * 原样透传（readSyncHistory 逐条 cast），所以运行时可稳定往返；界面按「字段有无」渲染。
+     */
     private appendHistory;
+    /**
+     * SEC-03：「地址被拒」是持久状态，而自动同步每 interval（缺省 60s）就转一圈 ——
+     * 每轮打一条日志等于把日志刷成噪音。同一 (通道 + 成因) 只 warn 一次。
+     * 用户改了配置后成因文本会变（message 带真实地址/原因），自然再报一次。
+     */
+    private reportConfigIssue;
     /** 启动：读两个通道配置 → enabled 通道各自排定时器 → 对每个 enabled 通道执行一次启动触发。 */
     start(): void;
     /** 停止：清全部定时器、拆掉文件监听、标记不再调度；正在执行的任务允许自然结束。 */
@@ -247,3 +299,9 @@ export declare function buildAutoApplyPlan(plan: MergePlan): SyncApplyPlan;
  * 未配置（null / 缺字段）→ false。作为 autosync 未配置跳过的判定依据。
  */
 export declare function syncIsConfigured(cfg: SyncConfig | null): boolean;
+/**
+ * SEC-03：从读侧收集到的 issue 里挑出本通道的成因（`code(channel): message`），
+ * 没有就返回 undefined —— 「真的没配」绝不伪造原因（无幻影告警）。
+ * 多通道并存时只取本通道，git 的拒因不该挂在 webdav 的历史里。
+ */
+export declare function describeConfigIssue(issues: readonly SyncConfigIssue[], channel: SyncTransportType): string | undefined;

package/lib/sync/autosync-scheduler.js

@@ -32,9 +32,11 @@
  *    → engine.applyMergePlan(autoApply) 写入本地
  *  - Phase C: 完整双向 → engine.push() 上传。两处策略：
  *    ① 无冲突且推送被远端推进挡下 → skipped/partial + skipReason='conflict'（等人工）；
- *    ② conflictPolicy='local'（缺省）且本轮有冲突 → **不写本地**，改 engine.push({force:true})
- *       把本机版本推成新的远端最新（被覆盖的远端旧版本仍在远端历史快照里可回滚），
- *       状态记 partial + skipReason='conflict-kept-local'（绝不谎报 success）。
+ *    ② conflictPolicy='local'（**只有用户显式选过才生效**；缺省 ask）且本轮有冲突 → **不写本地**，
+ *       改 engine.push({force:true}) 把本机版本推成新的远端最新（被覆盖的远端旧版本仍在远端历史快照里
+ *       可回滚），状态记 partial + skipReason='conflict-kept-local'（绝不谎报 success）；
+ *       SYN-05：首轮 / 远端有新快照时即使选了 local 也降级 ask 并记 forced=true（见
+ *       resolveConflictPushPolicy）——这两个时刻覆盖远端等于替用户丢数据。
  *  - 收尾：写该通道 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures,
  *    lastRunHistoryId, lastRunMessage/跳过原因 —— 每轮覆盖上一轮，绝不残留旧错误）
  *
@@ -76,6 +78,25 @@ export function shouldTriggerStartupRun(lastRunAt, startupMinIntervalMs, nowMs =
         return true;
     return nowMs - lastMs >= startupMinIntervalMs;
 }
+/**
+ * SYN-05：本轮冲突（下行冲突）该不该 force push —— 唯一判定点。
+ *
+ * 规则（缺省 ask 之上再加两道高危闸）：
+ *  - 用户没选过策略 → 用缺省（ask）；
+ *  - **首轮**（从未跑过）或**远端有新快照**：即使显式选了 'local' 也强制降级 ask（forcedAsk）——
+ *    这两个时刻正是「远端最新改动只在历史快照里」的事故现场，静默覆盖等于替用户丢数据；
+ *    降级记 forced，界面才能说清「这次没按你的 local 走」；
+ *  - 只有「显式 local + 非高危时刻 + 真有冲突」才 force。
+ *
+ * 纯函数（无状态、无 I/O）：调度层与单测共用同一份判定，避免两处各写一遍阈值。
+ */
+export function resolveConflictPushPolicy(args) {
+    const configured = args.configuredPolicy ?? DEFAULT_AUTOSYNC_CONFLICT_POLICY;
+    // forcedAsk 只描述「用户选了 local，但本轮被降级」——缺省 ask 不算被强制（那不是用户的决定被推翻）。
+    const forcedAsk = configured === 'local' && (args.firstRun || args.remoteNew);
+    const policy = forcedAsk ? 'ask' : configured;
+    return { policy, force: policy === 'local' && args.conflicted > 0, forcedAsk };
+}
 export class AutoSyncScheduler {
     syncDir;
     host;
@@ -118,6 +139,8 @@ export class AutoSyncScheduler {
     profile;
     makeWatcher;
     minTriggerGapMs;
+    /** SEC-03：已 warn 过的「地址被拒」成因（键 = 通道 + 成因文本），进程内去重。 */
+    reportedConfigIssues = new Set();
     stopped = false;
     running = false;
     constructor(opts) {
@@ -128,7 +151,7 @@ export class AutoSyncScheduler {
         this.now = opts.now ?? (() => new Date());
         this.readConfig = opts.readConfig ?? ((channel) => readAutosyncConfig(this.syncDir, channel));
         this.writeConfig = opts.writeConfig ?? ((channel, cfg) => writeAutosyncConfig(this.syncDir, channel, cfg));
-        this.readSyncConfigFn = opts.readSyncConfigFn ?? ((channel) => readSyncConfigFor(this.syncDir, channel));
+        this.readSyncConfigFn = opts.readSyncConfigFn ?? ((channel, issues) => readSyncConfigFor(this.syncDir, channel, issues));
         this.readHistoryFn = opts.readHistoryFn ?? (() => readSyncHistory(this.syncDir));
         this.appendHistoryFn = opts.appendHistoryFn ?? ((entry) => appendAutosyncEntry(this.syncDir, entry));
         this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
@@ -143,10 +166,28 @@ export class AutoSyncScheduler {
         this.makeWatcher = opts.makeWatcher ?? defaultMakeWatcher;
         this.minTriggerGapMs = opts.minTriggerGapMs ?? 3000;
     }
-    /** 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。 */
+    /**
+     * 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。
+     *
+     * SYN-05：额外允许 forced（本轮 ask 是被强制的）。该字段不在 sync-history.ts 的
+     * AutosyncHistoryEntry 里（那是另一个模块的公开契约，本轮不扩），但读写两侧都按普通对象
+     * 原样透传（readSyncHistory 逐条 cast），所以运行时可稳定往返；界面按「字段有无」渲染。
+     */
     async appendHistory(channel, entry) {
         await this.appendHistoryFn({ ...entry, transport: channel });
     }
+    /**
+     * SEC-03：「地址被拒」是持久状态，而自动同步每 interval（缺省 60s）就转一圈 ——
+     * 每轮打一条日志等于把日志刷成噪音。同一 (通道 + 成因) 只 warn 一次。
+     * 用户改了配置后成因文本会变（message 带真实地址/原因），自然再报一次。
+     */
+    reportConfigIssue(channel, detail) {
+        const key = channel + '/' + detail;
+        if (this.reportedConfigIssues.has(key))
+            return;
+        this.reportedConfigIssues.add(key);
+        this.host.log.warn(`自动同步已跳过（${channel}）：同步通道配置被安全校验拒绝，请重新填写地址（${detail}）`);
+    }
     /** 启动：读两个通道配置 → enabled 通道各自排定时器 → 对每个 enabled 通道执行一次启动触发。 */
     start() {
         if (this.stopped)
@@ -448,11 +489,18 @@ export class AutoSyncScheduler {
         }
         try {
             // 读该通道 sync-config：按通道判定「已配置」——git 看 git.repoUrl、webdav 看 webdav.url。
-            const syncCfg = await this.readSyncConfigFn(channel);
+            // SEC-03：「未配置」有两种成因 —— 真的没配，或存过的地址被白名单拒掉（读侧丢弃）。
+            // 必须区分：后者如果说成前者的「尚未配置」，用户会一遍遍重填同一个被拒地址。
+            const configIssues = [];
+            const syncCfg = await this.readSyncConfigFn(channel, configIssues);
             if (!syncIsConfigured(syncCfg)) {
+                const configIssue = describeConfigIssue(configIssues, channel);
+                if (configIssue !== undefined)
+                    this.reportConfigIssue(channel, configIssue);
                 const result = {
                     status: 'skipped', direction: 'none', skipReason: 'unconfigured', historyId,
                     consecutiveFailures: 0,
+                    ...(configIssue === undefined ? {} : { configIssue }),
                 };
                 await this.appendHistory(channel, {
                     direction: 'both',
@@ -460,6 +508,7 @@ export class AutoSyncScheduler {
                     skipReason: 'unconfigured',
                     createdAt: nowIso,
                     failureCountAtRun: 0,
+                    ...(configIssue === undefined ? {} : { configIssue }),
                 });
                 await this.writeFinalConfig(cfg, result, nowIso, historyId, channel);
                 return result;
@@ -502,6 +551,9 @@ export class AutoSyncScheduler {
             // 列表拿不到（网络失败）时 remoteMetas 为 null → 检测自己再 list 一次，行为与改造前一致
             const remoteNew = await this.detectRemoteNew(engine, remoteMetas ?? undefined);
             const localDirty = await this.detectLocalChange(engine);
+            // SYN-05：首轮（从未跑过）与「远端有新快照」是覆盖风险最高的两个时刻 —— 由
+            // resolveConflictPushPolicy 统一把这两处的 ask 标成 forced。
+            const firstRun = cfg.lastRunAt === undefined || cfg.lastRunAt === '';
             // 两端都无变化 → 什么都不做，记为 upToDate（不重复拉取/不空转）。
             if (!remoteNew && !localDirty) {
                 const result = {
@@ -603,13 +655,23 @@ export class AutoSyncScheduler {
             if (!opts.startup && localDirty) {
                 try {
                     /**
-                     * 冲突策略（conflictPolicy，缺省 'local'）：
+                     * 冲突策略（conflictPolicy，缺省 'ask'）：
                      * - 'ask'：不强制，推送会被引擎的「远端已推进」前置检测挡下 → skipped/partial(conflict)；
-                     * - 'local'：**不写本地**（下行被冲突挡下），但把本机版本强制推成新的远端最新。
-                     *   force 只跳过「基线是否落后」这一道检查，仍走正常快照上传与基线记录；
+                     * - 'local'：用户显式选中才生效 —— **不写本地**（下行被冲突挡下），但把本机版本强制推成
+                     *   新的远端最新。force 只跳过「基线是否落后」这一道检查，仍走正常快照上传与基线记录；
                      *   被覆盖的远端旧版本留在远端历史快照里，可手动回滚。
+                     *
+                     * SYN-05：首轮 / 远端有新快照时即使显式选了 local 也强制降级 ask（forced=true 进结果与
+                     * 历史），绝不在这两个高危时刻替用户覆盖远端最新。
                      */
-                    const forcePush = conflictedSections.length > 0 && (cfg.conflictPolicy ?? DEFAULT_AUTOSYNC_CONFLICT_POLICY) === 'local';
+                    const pushDecision = resolveConflictPushPolicy({
+                        ...(cfg.conflictPolicy !== undefined ? { configuredPolicy: cfg.conflictPolicy } : {}),
+                        firstRun,
+                        remoteNew,
+                        conflicted: conflictedSections.length,
+                    });
+                    const forcePush = pushDecision.force;
+                    const forcedMark = pushDecision.forcedAsk ? { forced: true } : {};
                     // Phase C: 完整双向 → engine.push() 上传。P0-A：外部 push 包 intent journal。
                     const rawPush = async () => engine.push(forcePush ? { force: true } : {});
                     const pushReport = (this.phase3Recovery !== undefined && this.lockCtxForJournal !== null)
@@ -630,6 +692,7 @@ export class AutoSyncScheduler {
                             appliedSections,
                             ...(conflictedSections.length > 0 ? { conflictedSections } : {}),
                             consecutiveFailures: 0,
+                            ...forcedMark,
                         };
                         await this.appendHistory(channel, {
                             direction: appliedSections.length ? 'both' : 'push', status: conflictResult.status,
@@ -637,6 +700,7 @@ export class AutoSyncScheduler {
                             appliedSections,
                             ...(conflictedSections.length > 0 ? { conflictedSections } : {}),
                             createdAt: nowIso, failureCountAtRun: 0,
+                            ...forcedMark,
                         });
                         await this.writeFinalConfig(cfg, conflictResult, nowIso, historyId, channel);
                         return conflictResult;
@@ -680,6 +744,7 @@ export class AutoSyncScheduler {
                         ...(skipReason !== undefined ? { skipReason } : {}),
                         ...(reportedConflicted.length > 0 ? { conflictedSections: reportedConflicted } : {}),
                         consecutiveFailures: 0,
+                        ...forcedMark,
                     };
                     await this.appendHistory(channel, {
                         direction: appliedSections.length ? 'both' : 'push',
@@ -688,6 +753,7 @@ export class AutoSyncScheduler {
                         ...(skipReason !== undefined ? { skipReason } : {}),
                         ...(reportedConflicted.length > 0 ? { conflictedSections: reportedConflicted } : {}),
                         createdAt: nowIso, failureCountAtRun: 0,
+                        ...forcedMark,
                     });
                     await this.writeFinalConfig(cfg, result, nowIso, historyId, channel);
                     return result;
@@ -856,6 +922,17 @@ export function syncIsConfigured(cfg) {
     }
     return false;
 }
+/**
+ * SEC-03：从读侧收集到的 issue 里挑出本通道的成因（`code(channel): message`），
+ * 没有就返回 undefined —— 「真的没配」绝不伪造原因（无幻影告警）。
+ * 多通道并存时只取本通道，git 的拒因不该挂在 webdav 的历史里。
+ */
+export function describeConfigIssue(issues, channel) {
+    const own = issues.filter((issue) => issue.channel === channel);
+    if (own.length === 0)
+        return undefined;
+    return own.map((issue) => `${issue.code} (${issue.channel}): ${issue.message}`).join('; ');
+}
 /**
  * 缺省远端新快照检测（§3.2）：engine 实现了 hasNewRemoteSnapshot() → 调用；
  * 否则（测试 mock 未实现）保守返回 true（假设有新生，保持旧行为=每次都尝试拉取）。

package/lib/sync/config-issue-reporting.d.ts

@@ -0,0 +1,32 @@
+import type { SyncConfig, SyncConfigIssue } from './sync-config.ts';
+/**
+ * 造一个「配置被拒」报告器：返回的函数幂等 —— 同一 (通道/码/文案) 只输出一行。
+ *
+ * 去重理由：调用方每次同步请求都跑一遍，按请求打日志会被零信息量的重复行刷满；而
+ * 「地址被拒」是**持久状态**，报一次即可。键里带 message 而不只带 code：不同被拒地址的
+ * 成因文案不同，那是新的有用信息，用户改了配置再被拒应当再报一次。
+ *
+ * `log` 由调用方注入（宿主传 `host.log.warn`），本模块不碰日志设施与 i18n 字典。
+ */
+export declare function createSyncConfigIssueReporter(log: (line: string) => void): (issues: readonly SyncConfigIssue[]) => void;
+/** `createPrepareSync` 的依赖（全部注入，便于单测与避免与 index.ts 形成循环依赖）。 */
+export interface PrepareSyncOptions {
+    /** 同步配置目录（`sync-config.json` 所在处）。 */
+    syncDir: string;
+    /** 解析请求体（宿主传入带 credentials 的 closure）。 */
+    parseBody: (body: Record<string, unknown>) => Promise<SyncConfig>;
+    /** 把已保存的 webdav username 回填进请求体（宿主传入 `mergePersistedWebDavUsername`）。 */
+    mergeWebDavUsername: (cfg: SyncConfig, persisted: SyncConfig | null) => SyncConfig;
+    /** 告警出口（宿主传 `(line) => host.log.warn(line)`）。 */
+    log: (line: string) => void;
+}
+/**
+ * 造 `prepareSync`：解析请求体，webdav 请求体未带 username 时从持久化配置回填 ——
+ * 否则 WebDavTransport 构造会因空 username 抛错，导致「保存过配置仍无法列出快照」。
+ * 语义与 password 一致：留空 = 沿用已保存凭据。
+ *
+ * SEC-03：顺带把「已落盘但过不了白名单、被读取侧丢弃」的 repoUrl 成因报一次；界面侧的
+ * 权威出口是 GET /sync/status 的 `configIssues`（字段恒在、按请求实时算），这里只补日志。
+ * 读配置失败时保持原值（空 username 由 WebDavTransport 构造校验兜底报错）。
+ */
+export declare function createPrepareSync(opts: PrepareSyncOptions): (body: Record<string, unknown>) => Promise<SyncConfig>;

package/lib/sync/config-issue-reporting.js

@@ -0,0 +1,63 @@
+/**
+ * 同步请求准备期的两个只读旁路（从宿主壳 `src/index.ts` 下沉，行为逐字保持）。
+ *
+ * 为什么独立成模块：
+ *  1) `prepareSync` 每个同步请求都跑一次（含挂载时 snapshotsList 的自动加载），它的副作用
+ *     （回填 webdav username、把「配置被拒」告警一次）需要自己的单测，而宿主壳本身不可实例化；
+ *  2) 去重语义是**可见性契约**的一部分（同一 (通道/码/文案) 只报一次），写在 4400 行的
+ *     assembly 文件里没人守得住。
+ *
+ * 这两件事共享同一个来源：读已落盘的 sync-config。读出来的产物有两种用途 —— 回填缺失字段、
+ * 报告被读侧丢弃的成因，因此放在同一个模块里，但各自独立导出、独立可测。
+ */
+import { isWebDavConfig, readSyncConfig } from './sync-config.js';
+/**
+ * 造一个「配置被拒」报告器：返回的函数幂等 —— 同一 (通道/码/文案) 只输出一行。
+ *
+ * 去重理由：调用方每次同步请求都跑一遍，按请求打日志会被零信息量的重复行刷满；而
+ * 「地址被拒」是**持久状态**，报一次即可。键里带 message 而不只带 code：不同被拒地址的
+ * 成因文案不同，那是新的有用信息，用户改了配置再被拒应当再报一次。
+ *
+ * `log` 由调用方注入（宿主传 `host.log.warn`），本模块不碰日志设施与 i18n 字典。
+ */
+export function createSyncConfigIssueReporter(log) {
+    const reported = new Set();
+    return (issues) => {
+        for (const issue of issues) {
+            const key = issue.channel + '/' + issue.code + '/' + issue.message;
+            if (reported.has(key))
+                continue;
+            reported.add(key);
+            log('sync config rejected (' + issue.channel + '/' + issue.code + '): ' + issue.message);
+        }
+    };
+}
+/**
+ * 造 `prepareSync`：解析请求体，webdav 请求体未带 username 时从持久化配置回填 ——
+ * 否则 WebDavTransport 构造会因空 username 抛错，导致「保存过配置仍无法列出快照」。
+ * 语义与 password 一致：留空 = 沿用已保存凭据。
+ *
+ * SEC-03：顺带把「已落盘但过不了白名单、被读取侧丢弃」的 repoUrl 成因报一次；界面侧的
+ * 权威出口是 GET /sync/status 的 `configIssues`（字段恒在、按请求实时算），这里只补日志。
+ * 读配置失败时保持原值（空 username 由 WebDavTransport 构造校验兜底报错）。
+ */
+export function createPrepareSync(opts) {
+    const reportIssues = createSyncConfigIssueReporter(opts.log);
+    return async (body) => {
+        const cfg = await opts.parseBody(body);
+        if (!isWebDavConfig(cfg))
+            return cfg;
+        if (cfg.webdav.username !== undefined && cfg.webdav.username !== '')
+            return cfg;
+        try {
+            const issues = [];
+            const persisted = await readSyncConfig(opts.syncDir, issues);
+            reportIssues(issues);
+            return opts.mergeWebDavUsername(cfg, persisted);
+        }
+        catch {
+            return cfg;
+        }
+    };
+}
+//# sourceMappingURL=config-issue-reporting.js.map

package/lib/sync/gc-skip.d.ts

@@ -0,0 +1,42 @@
+import type { MsgFunc } from '../core/messages.ts';
+/**
+ * 本轮 blob GC 的放弃码（SYN-04）。**机器可判定**，文案由上层按码翻译（字典键由 Lead 统一加）：
+ * 通道没有 logger，`delete()` 还会吞掉 GC 抛出的异常，所以「本轮为什么没回收」只能靠这个码如实外露。
+ * 三态同义：拿不到引用者内容 = 无法证明「没人引用」⇒ 本轮整轮放弃，绝不按残集删除。
+ *
+ * 单一来源：webdav / s3 两个通道都从这里导入（此前各写一份同名常量，改一侧不炸另一侧 =
+ * 静默漂移；本模块不 import 任何 transport，所以不存在环）。
+ */
+export declare const GC_SKIP_REFERENCE_MISSING = "gc-skip-reference-missing";
+export declare const GC_SKIP_REFERENCE_UNREADABLE = "gc-skip-reference-unreadable";
+export declare const GC_SKIP_SNAPSHOT_UNPARSABLE = "gc-skip-snapshot-unparsable";
+/** blob GC 放弃码（SYN-04）。 */
+export type GcSkipCode = typeof GC_SKIP_REFERENCE_MISSING | typeof GC_SKIP_REFERENCE_UNREADABLE | typeof GC_SKIP_SNAPSHOT_UNPARSABLE;
+/**
+ * SYN-04b：通道「本轮 GC 放弃码」的读取与冒泡（从 sync-engine.ts 下沉，行为逐字不变）。
+ *
+ * 为什么放在独立模块：SYN-04 之后 webdav/s3 遇到「引用快照 404 / 读不出」会**放弃本轮 blob GC**
+ * （绝不在「证明不了没人引用」时删 blob），而通道层没有 logger、delete() 又把 GC 异常吃掉
+ * ⇒ 放弃只能靠 transport 的只读字段外露。字段形态是 getter（见 webdav/s3 transport 的
+ * `get lastGcSkip()`），这里按 unknown 读、只接受非空字符串，getter 抛错也不影响 push。
+ *
+ * 判据（缺一不可，全部当「没有放弃码」）：字段缺失 / null / 非字符串 / 空串 / getter 抛错。
+ * 读不到 ≠ 没有放弃：通道没这个能力时本来就不该冒泡告警，所以两者在调用侧合并处理。
+ */
+export declare function readGcSkipCode(transport: unknown): string | null;
+/**
+ * SYN-04b：放弃码 → 一条 warning 文本。
+ *
+ * 码必须同时以**明文**出现：core 目录的翻译器对未知键回退键名本身（{code} 插值随之丢失），
+ * 而文案键由上层统一补字典 —— 在补键之前，只发出裸键名等于「报了但看不出来」，日志也无法 grep。
+ */
+export declare function gcSkipWarning(msg: MsgFunc, code: string): string;
+/**
+ * SYN-04b：把通道的 GC 放弃码冒泡成一条 warning（`state` 保证同一轮只报一次）。
+ *
+ * 语义边界：放弃 GC **不是** push 失败 —— 快照本身已上传/已删除，只是这一轮的孤儿 blob
+ * 没被回收（磁盘/远端会多留几份文件）。所以它进 warnings、不进 ok，与 prune 既有语义一致。
+ */
+export declare function reportGcSkipOnce(transport: unknown, msg: MsgFunc, warnings: string[], state: {
+    done: boolean;
+}): void;