dsh-config-manager 0.2.4 → 0.3.0

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 = [

package/src/security/unverified-file-blocks.ts

@@ -0,0 +1,192 @@
+/**
+ * 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.ts';
+import { CHECKSUMS_FILE, MANIFEST_FILE } from '../schema/manifest.ts';
+import { parseJsonSafe } from '../utils/json.ts';
+import { verifyChecksums } from '../utils/hashing.ts';
+import type { ChecksumVerifyResult } from '../utils/hashing.ts';
+import { UNVERIFIED_FILE_ENTRY_CODE, UNVERIFIED_FILE_ENTRY_KEY, unverifiedEntries } from './integrity.ts';
+import type { SectionId } from '../schema/types.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;
+}
+
+/**
+ * SEC-05 文案：优先用专属键 `import.unverifiedFileEntry`。
+ *
+ * 字典还没收录该键时 `msg` 会回退成键名本身（messages.ts 的「未知键绝不抛错」约定），
+ * 那样文案里只有键名、**连是哪个文件都没说** —— 对用户是最糟的形态。因此回退到既有的
+ * `import.extraEntries`（已翻译、也带条目名）。两段指向同一事实：「这个条目没被校验表覆盖」。
+ */
+/** 单条文案最多列几个条目 —— 校验表缺失时名单 = 整包文件分区条目，不截断会撑爆一条 warning。 */
+const MAX_LISTED_ENTRIES = 10;
+
+export function unverifiedFileEntryText(text: MsgFunc, names: readonly string[]): string {
+  return render(text, UNVERIFIED_FILE_ENTRY_KEY, names);
+}
+
+function render(text: MsgFunc, key: string, names: readonly string[]): string {
+  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: MsgFunc, names: readonly string[], blocked: number): string {
+  return render(text, blocked > 0 ? UNVERIFIED_FILE_ENTRY_KEY : 'import.extraEntries', names);
+}
+
+/** 归档里的结构文件（不属于内容，永不参与「未覆盖」判定）。 */
+const STRUCTURAL_FILES = [MANIFEST_FILE, CHECKSUMS_FILE];
+
+/** 落在文件分区前缀下的归档条目（目录标记条目与结构文件排除）。 */
+function fileSectionEntries(names: readonly string[]): string[] {
+  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: readonly string[], table: Record<string, string> | null): string[] {
+  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: readonly string[],
+  items: UnverifiedBlockableItem[],
+  fileSections: ReadonlySet<string>,
+  exemptSections: readonly string[],
+  text: MsgFunc,
+): string[] {
+  if (unverified.length === 0) return [];
+  const unverifiedSet = new Set(unverified);
+  const exempt = new Set<string>(exemptSections);
+  const blocked: string[] = [];
+  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 as SectionId] ?? '') + 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;
+}
+
+/** 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 async function scanArchiveIntegrity(archive: IntegrityArchive, text: MsgFunc): Promise<ArchiveIntegrityScan> {
+  const warnings: string[] = [];
+  const names = archive.names();
+  // 校验表缺失或为空：全部条目都处于「未登记 ⇒ 未被校验」，两种形态对用户是同一件事，共用一条告警。
+  // 此时 checksums 恒 ok（没有可正向校验的声明），防线全靠下一行 scanUnverifiedEntries 的 fail-closed。
+  const table = archive.has(CHECKSUMS_FILE)
+    ? (parseJsonSafe(archive.readEntryText(CHECKSUMS_FILE)) as Record<string, string>)
+    : null;
+  if (table === null || Object.keys(table).length === 0) warnings.push(text('import.checksumsMissing'));
+  let checksums: ChecksumVerifyResult = { ok: true, mismatches: [], missing: [] };
+  if (table !== null && Object.keys(table).length > 0) {
+    const entries = new Map<string, Uint8Array>();
+    // 异步解压：这是全仓唯一逐条解压全部条目的地方（`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 } : {}) };
+}
+

package/src/sync/autosync-config.ts

@@ -54,17 +54,21 @@ export const DEFAULT_AUTOSYNC_AUTO_APPLY_TIER: AutosyncAutoApplyTier = 'medium';
 
 /**
  * 双侧都改（真冲突）时的自动裁决策略：
- *  - '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（保留本机并推上去） */
-export const DEFAULT_AUTOSYNC_CONFLICT_POLICY: AutosyncConflictPolicy = 'local';
+/** 缺省冲突策略：ask（冲突待人工裁决；显式写过 local 的旧配置仍按 local 生效） */
+export const DEFAULT_AUTOSYNC_CONFLICT_POLICY: AutosyncConflictPolicy = 'ask';
 
 /** 最近一次自动同步执行状态 */
 export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';

package/src/sync/autosync-scheduler.test.ts

@@ -7,9 +7,13 @@
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
 
 import {
   AutoSyncScheduler, intervalToMs, shouldTriggerStartupRun, buildAutoApplyPlan,
+  resolveConflictPushPolicy,
 } from './autosync-scheduler.ts';
 import { RunRegistry } from '../core/run-registry.ts';
 import { nullLogger, createLogger } from '../utils/logger.ts';
@@ -22,6 +26,7 @@ import type { SyncSnapshotMeta } from './transport.ts';
 import type { SectionId } from '../schema/types.ts';
 import type { SyncEngine } from './sync-engine.ts';
 import type { SyncConfig, SyncTransportType } from './sync-config.ts';
+import { SYNC_CONFIG_FILE } from './sync-config.ts';
 import { SYNC_CHANNELS } from './sync-config.ts';
 import { syncIsConfigured } from './autosync-scheduler.ts';
 
@@ -351,7 +356,7 @@ test('runOnce: merge 抛错 → failed，连续失败计数 +1', async () => {
   assert.ok(getEntries().some((e) => e.status === 'failed'), '写入失败历史');
 });
 
-test('issue #79 + conflictPolicy=local（缺省）：冲突只挡下行，本机版本强制推成新远端（partial，不谎报 success/failed）', async () => {
+test('SYN-05：缺省策略 = ask —— 冲突只挡下行，绝不 force 覆盖远端（首轮同样强制 ask）', async () => {
   const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 1 };
   const applyCalls: string[] = [];
   const pushCalls: Array<{ force?: boolean } | undefined> = [];
@@ -370,20 +375,81 @@ test('issue #79 + conflictPolicy=local（缺省）：冲突只挡下行，本机
   };
   const { scheduler, getConfig, getEntries } = makeScheduler({ cfg, engine, history: [] });
   const result = await scheduler.runOnce('git');
-  assert.equal(result.status, 'partial', '上行成功 + 下行被冲突挡下 → partial');
-  assert.equal(result.skipReason, 'conflict-kept-local', '本机已按策略覆盖远端，与「待人工裁决」区分开');
+  assert.equal(result.status, 'partial', '上行成功 + 下行待裁决 → partial');
+  assert.equal(result.skipReason, 'conflict', '缺省绝不宣称「本机已覆盖远端」');
   assert.deepEqual(result.conflictedSections, ['settings']);
   assert.equal(result.pushedSnapshotId, 'snap-up', '本机快照仍有上行出口（issue #79 主诉）');
   assert.equal(applyCalls.length, 0, '冲突绝不写本机配置');
   assert.equal(pushCalls.length, 1, '纯上行不被冲突连坐');
-  assert.equal(pushCalls[0]?.force, true, 'local 策略下必须带上 force，否则引擎会因「远端已推进」拒绝上传');
+  assert.equal(pushCalls[0]?.force, undefined, '缺省 ask 一律不得带 force（绝不覆盖远端最新）');
+  assert.equal(result.forced, undefined, '缺省就是 ask：不算「用户选择被推翻」，不标 forced');
   assert.equal(result.consecutiveFailures, 0, '冲突跳过不是失败 → 计数归零');
-  assert.equal(getConfig().lastRunSkipReason, 'conflict-kept-local', '跳过原因落到状态（界面按码取字典）');
+  assert.equal(getConfig().lastRunSkipReason, 'conflict', '跳过原因落到状态（界面按码取字典）');
   assert.equal(getConfig().lastRunSkipCount, 1);
-  assert.ok(getEntries().some((e) => e.status === 'partial' && e.skipReason === 'conflict-kept-local'), '写入 partial 历史');
+  assert.ok(getEntries().some((e) => e.status === 'partial' && e.skipReason === 'conflict'), '写入 partial 历史');
+
   assert.ok(getEntries().some((e) => e.pushedSnapshotId === 'snap-up'), '历史带上行快照 id');
 });
 
+test('SYN-05：显式 local + 首轮 → 降级 ask 且 forced=true（历史留痕）', async () => {
+  const cfg: AutosyncConfig = {
+    enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0,
+    conflictPolicy: 'local',
+  };
+  const pushCalls: Array<{ force?: boolean } | undefined> = [];
+  const engine = {
+    hasNewRemoteSnapshot: async () => true,
+    hasLocalChanges: async () => true,
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'conflict']]),
+    push: async (opts?: { force?: boolean }) => {
+      pushCalls.push(opts);
+      return { ok: true, snapshotId: 'snap-up', sections: [] as never, warnings: [] };
+    },
+  };
+  const { scheduler, getEntries } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce('git');
+  assert.equal(pushCalls[0]?.force, undefined, '首轮 = 高危时刻：显式 local 也不得 force');
+  assert.equal(result.skipReason, 'conflict');
+  assert.equal(result.forced, true, '用户选过 local 但被降级 → 必须标 forced');
+  const forcedEntries = getEntries().filter(
+    (e) => (e as AutosyncHistoryEntry & { forced?: boolean }).forced === true,
+  );
+  assert.equal(forcedEntries.length, 1, '历史同步留痕（界面能说清「这次没按你的设置走」）');
+});
+
+test('SYN-05：远端有新快照（非首轮）+ 显式 local → 仍强制 ask，不覆盖远端最新', async () => {
+  const cfg: AutosyncConfig = {
+    enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0,
+    conflictPolicy: 'local', lastRunAt: '2026-11-01T10:00:00.000Z',
+  };
+  const pushCalls: Array<{ force?: boolean } | undefined> = [];
+  const engine = {
+    hasNewRemoteSnapshot: async () => true,
+    hasLocalChanges: async () => true,
+    merge: async (): Promise<MergePlan> => makeMergePlan([['settings', 'conflict']]),
+    push: async (opts?: { force?: boolean }) => {
+      pushCalls.push(opts);
+      return { ok: true, snapshotId: 'snap-up', sections: [] as never, warnings: [] };
+    },
+  };
+  const { scheduler } = makeScheduler({ cfg, engine, history: [] });
+  const result = await scheduler.runOnce('git');
+  assert.equal(pushCalls[0]?.force, undefined, '远端有新快照 = 高危时刻，即使用户选过 local 也不得 force');
+  assert.equal(result.skipReason, 'conflict');
+  assert.equal(result.forced, true, '强制降级必须可见');
+});
+
+test('SYN-05：非首轮 + 远端无新快照 + 显式 local → 尊重用户选择（force 语义保留）', () => {
+  // 冲突只可能随「远端有新快照」出现，因此调度层实际上不会走到 force；
+  // 这条断言钉住判定函数本身：显式 local 且非高危时刻 → force 仍为 true（策略没被单方面删除）。
+  const decision = resolveConflictPushPolicy({
+    configuredPolicy: 'local', firstRun: false, remoteNew: false, conflicted: 1,
+  });
+  assert.equal(decision.policy, 'local');
+  assert.equal(decision.force, true);
+  assert.equal(decision.forcedAsk, false);
+});
+
 test('issue #79 + conflictPolicy=ask：冲突只挡下行，绝不强推覆盖远端（partial + skipped 码 conflict）', async () => {
   const cfg: AutosyncConfig = {
     enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 1,
@@ -994,3 +1060,64 @@ test('运行期多通道触发：每个通道各自补跑（单槽实现会让
   await tick();
 });
 
+
+/* ---------------- SEC-03 读侧可见性：被白名单拒绝的 repoUrl ≠ 「真的没配」 ---------------- */
+
+/**
+ * 审计 SEC-01/02/03：已落盘的 repoUrl 过不了白名单就会被 readFullSyncConfig 丢掉。
+ * 丢掉本身是对的（绝不把可疑地址交给凭据注入与 git 子进程），但自动同步若只说
+ * 'unconfigured'，用户看到的是「你没配」，实际是「你配过、被拒了」—— 永远查不出原因。
+ * 所以未配置分支必须带上成因字段（配置跳过 + 历史各一份），且真没配时不产生幻影成因。
+ */
+
+test('SEC-03：已存 repoUrl 被白名单拒绝 → skipped(unconfigured) 但带 configIssue（结果 + 历史）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-autosync-config-issue-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, SYNC_CONFIG_FILE),
+      JSON.stringify({ schemaVersion: 2, transport: 'git', git: { repoUrl: 'https://192.168.1.10/owner/repo.git' } }),
+      'utf8',
+    );
+    const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+    const entries: AutosyncHistoryEntry[] = [];
+    // 故意不注入 readSyncConfigFn：走缺省 readSyncConfigFor(syncDir, channel, issues)，钉住真实接线
+    const scheduler = new AutoSyncScheduler({
+      syncDir: dir,
+      host: { log: nullLogger() },
+      makeSyncEngine: () => { throw new Error('被拒地址绝不构造同步引擎'); },
+      msg: (k: string) => k,
+      runs: new RunRegistry(),
+      now: () => new Date(1_000_000_000_000),
+      readConfig: async () => cfg,
+      writeConfig: async () => {},
+      readHistoryFn: async () => ({ schemaVersion: 1, autosyncEntries: entries, updatedAt: '' }),
+      appendHistoryFn: async (e) => { entries.push(e); },
+    });
+    const result = await scheduler.runOnce('git');
+    assert.equal(result.status, 'skipped');
+    assert.equal(result.skipReason, 'unconfigured', '机读 token 保持稳定（客户端本地化不破）');
+    assert.ok(
+      (result.configIssue ?? '').includes('192.168.1.10'),
+      '结果必须说明「地址被拒」，实际: ' + JSON.stringify(result),
+    );
+    assert.equal(entries.length, 1, '仍然写一条跳过历史');
+    const entry = entries[0] as AutosyncHistoryEntry & { configIssue?: string };
+    assert.equal(entry.skipReason, 'unconfigured');
+    assert.ok(
+      (entry.configIssue ?? '').includes('192.168.1.10'),
+      '历史同一字段（界面按字段有无渲染「被拒」而不是「未配置」）: ' + JSON.stringify(entry),
+    );
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('SEC-03：真的没配 → 不带 configIssue（不产生幻影告警）', async () => {
+  const cfg: AutosyncConfig = { enabled: true, interval: '30m', startupMinIntervalMs: 300000, consecutiveFailures: 0 };
+  const { scheduler, getEntries } = makeScheduler({ cfg, engine: {}, history: [], syncCfg: null });
+  const result = await scheduler.runOnce('git');
+  assert.equal(result.skipReason, 'unconfigured');
+  assert.equal(result.configIssue, undefined, '空配置不是「被拒」，不许造一条假成因');
+  const entry = getEntries()[0] as AutosyncHistoryEntry & { configIssue?: string } | undefined;
+  assert.equal(entry?.configIssue, undefined);
+});