dsh-config-manager 0.2.3 → 0.3.0

package/src/core/integrity-extra-entries.test.ts

@@ -0,0 +1,205 @@
+/**
+ * SEC-05 回归：校验表只做「正向」校验 —— 表里登记的逐条比对，**表外的归档条目没人管**。
+ * 文件类分区又是按归档名原样落盘的，于是「ZIP 有、checksums 没登记」的文件照样被写进目标目录，
+ * 完整性声明形同虚设（审计 docs/research/dsh-config-manager-technical-audit.md SEC-05）。
+ *
+ * 修后口径：
+ *  - 会落盘的文件分区条目（Create/Update/Conflict）若不在 checksums 表内 ⇒ 计划项升级为 Error（逐条零写入），
+ *    整包仍 valid（表外 ≠ 被篡改，只留一条 warning）；
+ *  - 校验表**缺失或为空** ⇒ 一个条目都没被校验，文件分区条目同样逐条拦（RV1-F1，否则删表即绕过）；
+ *  - 历史包兼容开关 extraEntryExemptSections（默认空）按分区豁免，豁免分区退回「只告警」旧行为；
+ *  - 「不在任何文件分区前缀下」的散落条目仍是告警（守 tests/conformance/roundtrip.test.ts INT-01）。
+ */
+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 { Analyzer } from './analyzer.ts';
+import { Importer } from './importer.ts';
+import { createAdapters } from '../adapters/index.ts';
+import { makeContext, MemSnapshotStore } from '../adapters/test-helpers.ts';
+import { writeZip } from '../utils/zip.ts';
+import { buildManifest } from '../schema/manifest.ts';
+import { buildChecksums } from '../utils/hashing.ts';
+import { SECTION_IDS, SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.ts';
+import { UNVERIFIED_FILE_ENTRY_CODE } from '../security/integrity.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { HostContext } from './types.ts';
+
+const SETTINGS = JSON.stringify({
+  version: 1,
+  namespaces: { llm: { value: { model: 'deepseek-chat' }, revision: 1, secrets: [] } },
+});
+const DECISIONS = { strategy: 'merge' as const, resolutions: {}, pathMappings: [] };
+/** skills 分区在 ZIP 内的真实前缀（custom/skills/），从注册表派生，不写死布局。 */
+const SKILL_PREFIX = SECTION_FILE_PREFIXES['skills']!;
+const SKILL_REL = 'demo/SKILL.md';
+const SKILL_ENTRY = SKILL_PREFIX + SKILL_REL;
+/** 不在任何文件分区前缀下的散落条目（INT-01 用）。 */
+const ROGUE_ENTRY = 'injected/rogue.json';
+
+/** 造包：settings + skills 声明为包含；unlisted 里的条目进 ZIP 但不进 checksums 表。 */
+async function buildBundle(
+  opts: { unlisted?: string[]; declareSkills?: boolean; checksums?: 'omit' | 'empty' } = {},
+): Promise<{ zipPath: string; tmp: string }> {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-sec05-'));
+  const flags: Record<string, boolean> = {};
+  for (const sid of SECTION_IDS) flags[sid] = false;
+  flags['settings'] = true;
+  flags['skills'] = opts.declareSkills !== false;
+  const manifest = buildManifest({
+    exporterVersion: '0.1.0',
+    dshVersion: '0.1.54',
+    platform: 'win32',
+    arch: 'x64',
+    sections: flags as Record<SectionId, boolean>,
+    containsSecrets: false,
+    encrypted: false,
+    encryption: null,
+  });
+  const contentEntries = [
+    { name: SECTION_JSON_PATHS['settings']!, data: Buffer.from(SETTINGS, 'utf8') },
+    { name: SKILL_ENTRY, data: Buffer.from('# demo skill', 'utf8') },
+    { name: ROGUE_ENTRY, data: Buffer.from('{"rogue":true}', 'utf8') },
+  ];
+  const unlisted = new Set(opts.unlisted ?? []);
+  const checksums = buildChecksums(contentEntries.filter((e) => !unlisted.has(e.name)));
+  const entries = [
+    ...contentEntries,
+    { name: 'manifest.json', data: Buffer.from(JSON.stringify(manifest), 'utf8') },
+    // RV1-F1：表缺失（'omit'）与表为空（'empty'）都必须逐条 fail-closed —— 两种形态曾被当成「没事」。
+    ...(opts.checksums === 'omit'
+      ? []
+      : [{
+        name: 'integrity/checksums.json',
+        data: Buffer.from(opts.checksums === 'empty' ? '{}' : JSON.stringify(checksums), 'utf8'),
+      }]),
+  ];
+  const zipPath = path.join(tmp, 'bundle.zip');
+  await writeZip(zipPath, entries);
+  return { zipPath, tmp };
+}
+
+function mkCtx(): HostContext {
+  return makeContext('linux', '/home/bob');
+}
+
+function mkAnalyzer(ctx: HostContext, extraEntryExemptSections?: readonly SectionId[]): Analyzer {
+  return new Analyzer({
+    ctx,
+    adapters: createAdapters({ namespaces: ['llm'] }),
+    snapshotStore: new MemSnapshotStore(),
+    ...(extraEntryExemptSections ? { extraEntryExemptSections } : {}),
+  });
+}
+
+function mkImporter(ctx: HostContext): Importer {
+  return new Importer({ ctx, adapters: createAdapters({ namespaces: ['llm'] }), snapshotStore: new MemSnapshotStore() });
+}
+
+test('SEC-05/① 对照：文件分区条目全量登记 → 不阻断，计划项照常 Create', async () => {
+  const { zipPath } = await buildBundle();
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const analysis = await importer.analyzeImport(zipPath);
+  assert.equal(analysis.valid, true, '全量登记不应阻断');
+  assert.deepEqual(analysis.errors, []);
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const item = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(item, 'skills 分区应有 SKILL.md 计划项');
+  assert.equal(item!.kind, 'Create');
+});
+
+test('SEC-05/② 表外文件分区条目 → 计划项 Error（零写入），analysis 只留一条 warning', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [SKILL_ENTRY] });
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const analysis = await importer.analyzeImport(zipPath);
+  // 表外 ≠ 被篡改：逐条 Error 已保证零写入，把整包判死只会拒绝整笔合法导入（含一个多余文件的历史包），
+  // 却没多拦住任何一次写盘 ⇒ valid 保持 true，错误面只留一条 warning 点名该条目。
+  assert.equal(analysis.valid, true, '表外条目不得把整包判死');
+  assert.deepEqual(analysis.errors, [], '表外条目不进 errors（不阻断整体导入）');
+  const named = analysis.warnings.some((w) => w.includes(SKILL_REL) || w.includes(SKILL_ENTRY));
+  assert.ok(named, 'warnings 必须点名该条目，实际: ' + JSON.stringify(analysis.warnings));
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const item = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(item, '被阻断条目仍要出现在计划里（用户能看到为什么没导）');
+  assert.equal(item!.kind, 'Error');
+  assert.equal(item!.severity, 'error');
+  assert.ok(item!.detail?.includes(UNVERIFIED_FILE_ENTRY_CODE), 'detail 应带错误码，实际: ' + String(item!.detail));
+});
+
+test('SEC-05/③ 按分区豁免 → 退回只告警（历史包兼容开关，默认关）', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [SKILL_ENTRY] });
+  const ctx = mkCtx();
+  const analyzer = mkAnalyzer(ctx, ['skills']);
+  const analysis = await analyzer.analyzeImport(zipPath);
+  assert.equal(analysis.valid, true, '豁免分区不得阻断');
+  assert.ok(analysis.warnings.some((w) => w.includes(SKILL_ENTRY)), '豁免也要留告警，不能静默放行');
+  const plan = await analyzer.createImportPlan(zipPath, DECISIONS);
+  const item = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.equal(item!.kind, 'Create', '豁免分区应照常落盘');
+});
+
+test('SEC-05/④ 非文件分区的散落条目仍只告警（守 INT-01 口径）', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [ROGUE_ENTRY] });
+  const ctx = mkCtx();
+  const analysis = await mkImporter(ctx).analyzeImport(zipPath);
+  assert.equal(analysis.valid, true, '散落条目不阻断');
+  assert.deepEqual(analysis.errors, []);
+  assert.ok(analysis.warnings.some((w) => w.includes(ROGUE_ENTRY)), '散落条目必须有告警（不得静默忽略）');
+});
+
+test('SEC-05/⑤ 执行被阻断的计划 → 表外文件零落盘', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [SKILL_ENTRY] });
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const skillItem = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(skillItem, '被阻断条目应在计划里');
+  const result = await importer.executeImportPlan(zipPath, plan, { confirm: true });
+  const blocked = result.executed.find((e) => e.itemId === skillItem!.id);
+  assert.equal(blocked?.status, 'failed', '被阻断项执行结果必须是 failed');
+  assert.equal(await ctx.fs.exists(SKILL_ENTRY), false, '表外条目绝不能被写进目标');
+});
+
+/* ─── RV1-F1：表缺失 / 表为空 ⇒ 逐条 fail-closed（删掉表就等于关掉 SEC-05 的那个绕过） ─── */
+
+async function expectFailClosed(mode: 'omit' | 'empty'): Promise<void> {
+  const { zipPath } = await buildBundle({ checksums: mode });
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const analysis = await importer.analyzeImport(zipPath);
+  // 逐条 fail-closed，不是整包拒：settings 这类非文件分区照常可导，判死的只是完整性管不到的文件分区条目。
+  assert.equal(analysis.valid, true, '表缺失/为空不得把整包判死（旧包仍要能用）');
+  assert.deepEqual(analysis.errors, []);
+  assert.ok(
+    analysis.warnings.some((w) => w.includes(SKILL_ENTRY)),
+    '没有校验表时，文件分区条目必须被点名（静默放行 = 防线失效），实际: ' + JSON.stringify(analysis.warnings),
+  );
+
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const skillItem = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(skillItem, '文件分区条目应在计划里');
+  assert.equal(skillItem!.kind, 'Error', '没有校验表 ⇒ 文件分区条目一律未覆盖 ⇒ 必须拦');
+  assert.ok(String(skillItem!.detail ?? '').includes(UNVERIFIED_FILE_ENTRY_CODE), '拦下时必须带错误码');
+  assert.ok(
+    plan.items.some((i) => i.adapter === 'settings' && i.kind !== 'Error'),
+    '非文件分区（settings）不应被连带阻断',
+  );
+
+  const result = await importer.executeImportPlan(zipPath, plan, { confirm: true });
+  assert.equal(result.executed.find((e) => e.itemId === skillItem!.id)?.status, 'failed', '被拦项执行结果必须是 failed');
+  assert.equal(await ctx.fs.exists(SKILL_ENTRY), false, '没有校验表时，文件条目绝不能被写进目标');
+}
+
+test('RV1/F1⑥ 包内缺 integrity/checksums.json → 文件分区条目逐条拦、零写入（删表不能绕过 SEC-05）', async () => {
+  await expectFailClosed('omit');
+});
+
+test('RV1/F1⑦ 校验表为空 {} → 与缺失同口径（空表 = 一个条目都没校验）', async () => {
+  await expectFailClosed('empty');
+});
+

package/src/core/messages.test.ts

@@ -47,7 +47,9 @@ test('i18n(ui): zhUiT 缺省 + makeUiT 双语插值', () => {
   assert.equal(zhUiT('error.notMounted'), 'config-manager 服务未挂载（插件未加载）：请确认 profile 中已安装 dsh-config-manager 并重启 DSH');
   const enT = makeUiT('en');
   assert.equal(enT('error.notMounted'), 'config-manager service is not mounted (plugin not loaded): make sure dsh-config-manager is installed in the profile and restart DSH');
-  assert.equal(enT('report.credentialsNeedEntry', { count: '3' }), '3 credential(s) need to be entered');
+  // 2026-11-01 起复数由 `{count, plural, ...}` 段决定：3 → credentials / need
+  assert.equal(enT('report.credentialsNeedEntry', { count: '3' }), '3 credentials need to be entered');
+  assert.equal(enT('report.credentialsNeedEntry', { count: '1' }), '1 credential needs to be entered');
   // 未知键回退 zh → 键名（类型层不允许字面量，这里用宽松断言验证运行期回退）
   const loose = makeUiT('en') as (key: string) => string;
   assert.equal(loose('no.such.key'), 'no.such.key');

package/src/core/messages.ts

@@ -65,6 +65,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}',
@@ -349,6 +350,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}',
 
@@ -399,6 +401,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}）',
@@ -459,6 +462,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}（仅允许字母数字开头，字符限 . _ -）',
@@ -571,6 +575,7 @@ export const en: Record<keyof typeof zh, string> = {
   '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}',
@@ -855,6 +860,7 @@ export const en: Record<keyof typeof zh, string> = {
   '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}',
 
@@ -905,6 +911,7 @@ export const en: Record<keyof typeof zh, string> = {
   '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})',
@@ -961,6 +968,7 @@ export const en: Record<keyof typeof zh, string> = {
   '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)',

package/src/core/model-tools.test.ts

@@ -398,3 +398,36 @@ test('registerModelTools：tools 服务缺失 → 静默跳过（不抛错、不
     await fs.rm(tmp, { recursive: true, force: true })
   }
 })
+
+/* ---------------- SEC-03 读侧可见性：被拒 repoUrl 的成因必须传到模型工具错误里 ---------------- */
+
+/**
+ * 审计 SEC-01/02/03：`resolveEngine` 读到的 git 通道若因白名单被丢弃（repoUrl 是内网/环回/
+ * 带 userinfo/以 '-' 开头），修复前只抛「该通道未配置」——把「你配过但被拒」说成「你没配」，
+ * Agent 于是让用户「去配一下」，用户配了还是被拒，彻底卡死。
+ * 这里钉住：错误文本必须带上被拒地址与成因，且**绝不构造同步引擎**。
+ */
+test('SEC-03 config_sync_push：已存 repoUrl 被白名单拒绝 → 错误带真实成因（不是「未配置」）', async () => {
+  const { deps, tmp, transport } = await makeDeps()
+  try {
+    await fs.mkdir(deps.syncDir, { recursive: true })
+    await fs.writeFile(
+      path.join(deps.syncDir, 'sync-config.json'),
+      JSON.stringify({ schemaVersion: 2, transport: 'git', git: { repoUrl: 'https://192.168.1.10/owner/repo.git' } }),
+      'utf8',
+    )
+    const tools = createModelTools(deps)
+    await assert.rejects(
+      () => tools.syncPush({ channel: 'git' }),
+      (error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        assert.ok(message.includes('192.168.1.10'), '错误必须带上被拒地址: ' + message)
+        assert.ok(/repo-url-invalid/.test(message), '错误必须带上机读成因码: ' + message)
+        return true
+      },
+    )
+    assert.ok(!transport.calls.includes('upload'), '被拒地址绝不发起任何远端写入')
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true })
+  }
+})

package/src/core/model-tools.ts

@@ -37,7 +37,7 @@ import { createEncryptionProvider } from '../security/encryption.ts'
 import { SECTION_IDS } from '../schema/config.ts'
 import type { SectionId } from '../schema/types.ts'
 import { parseSyncChannel, readFullSyncConfig, readSyncConfigFor, SYNC_CHANNELS } from '../sync/sync-config.ts'
-import type { SyncConfig, SyncTransportType } from '../sync/sync-config.ts'
+import type { SyncConfig, SyncConfigIssue, SyncTransportType } from '../sync/sync-config.ts'
 import type { ConfigAdapter, HostContext, SecretScanner } from './types.ts'
 import { runWithMutationLock } from '../utils/env-lock.ts'
 
@@ -92,17 +92,33 @@ function filterSectionIds(ids: readonly string[]): SectionId[] {
   return ids.filter((id): id is SectionId => (SECTION_IDS as readonly string[]).includes(id))
 }
 
+/**
+ * SEC-03：把「读侧被白名单丢弃的配置」翻成一句可执行的补充说明。
+ * 只挑本通道的 issue —— git 地址被拒不该出现在 webdav 的错误里。
+ */
+function describeConfigIssues(issues: readonly SyncConfigIssue[], channel: SyncTransportType): string {
+  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: ModelToolsDeps,
   channel?: SyncTransportType,
 ): Promise<{ engine: SyncEngine; channel: SyncTransportType }> {
+  // SEC-03：两处读取都收集 issues —— 否则「地址被安全校验拒掉」会被报成
+  // 「sync-config.json 缺失或损坏」，让模型/用户反复重填同一个被拒地址。
+  const issues: SyncConfigIssue[] = []
   // 未显式指定通道 → 取已配置的活动通道（唯一判定口径 parseSyncChannel；缺省 git）
-  const full = channel === undefined ? await readFullSyncConfig(deps.syncDir) : null
+  const full = channel === undefined ? await readFullSyncConfig(deps.syncDir, issues) : null
   const ch: SyncTransportType = 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/src/index.ts

@@ -132,7 +132,7 @@ import type { PruneSelector } from './core/backup.ts'
 import { selectPruneCandidates } from './core/backup.ts'
 import { appendAutosyncEntry } from './sync/sync-history.ts'
 import { MigrationStore, type MigrationKind, type MigrationResult, MIGRATION_HISTORY_DIR } from './core/migration-history.ts'
-import { readSyncConfig, validateRepoUrl, validateWebDavUrl, isWebDavConfig, isS3Config, isGistConfig, channelOf, parseSyncChannel, SYNC_CHANNELS, GIST_PROVIDER, isS3CompatProvider, validateCloudChannelInput, cloudSecretRef } from './sync/sync-config.ts'
+import { validateRepoUrl, validateWebDavUrl, isWebDavConfig, isS3Config, isGistConfig, channelOf, parseSyncChannel, SYNC_CHANNELS, GIST_PROVIDER, isS3CompatProvider, validateCloudChannelInput, cloudSecretRef } from './sync/sync-config.ts'
 import {
   resolveSessionFormatDisposition,
   sessionFormatAbortResponse,
@@ -140,6 +140,7 @@ import {
 } from './routes/session-format.ts'
 import type { SessionFormatDisposition } from './core/types.ts'
 import type { SyncConfig, SyncTransportType } from './sync/sync-config.ts'
+import { createPrepareSync } from './sync/config-issue-reporting.ts'
 import { AUTO_SYNC_OPT_IN_SECTIONS, defaultSyncSelection, effectiveSections, OPT_IN_SYNC_SECTIONS, readAllSyncSelections, readSyncSelection } from './sync/sync-selection.ts'
 import type { SyncSelection, SyncSelectionMode } from './sync/sync-selection.ts'
 import type { SyncTransport } from './sync/transport.ts'
@@ -180,7 +181,7 @@ export const name = 'config-manager'
 export const inject = ['settings', 'credentials']
 
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.2.3'
+export const PLUGIN_VERSION = '0.3.0'
 
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager'
@@ -2772,25 +2773,15 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
   // credentials（只存值不落盘同步文件/日志），git 网络操作时经 resolve 现取 ——
   // 与 GitTransport「token 只从注入 provider 读取」的安全契约完全对齐。
 
-  /**
-   * 解析同步请求体并补全缺失字段（委托给导出的 parseSyncBody，便于单测）。
-   * username 回退：webdav 请求体未带 username（如挂载时 snapshotsList 自动加载、
-   * 表单留空后直接同步）时，从持久化 sync-config 回填已保存的 username——
-   * 否则 WebDavTransport 构造会因空 username 抛错，导致「保存过配置仍无法列出快照」。
-   * 语义与 password 一致：留空 = 沿用已保存凭据。
-   */
-  const prepareSync = async (body: Record<string, unknown>): Promise<SyncConfig> => {
-    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。 */

package/src/routes/import.ts

@@ -10,6 +10,7 @@ import type { WebRoute } from './kit.ts'
 import type { RoutesEnv } from './context.ts'
 import type { RunState } from '../core/run-registry.ts'
 import type { ImportPlan } from '../core/types.ts'
+import { DEFAULT_ROLLBACK_ON_ERROR } from '../core/import-defaults.ts'
 import { decryptErrorText, isControlledPath, tryDecryptCredentials, writeRequestBodyToFile } from './route-support.ts'
 import { resolveSessionFormatDisposition, sessionFormatAbortResponse } from './session-format.ts'
 import { ENCRYPTED_CONTAINER_CODE, SecurityError, decryptArchive, isArchiveBlob, readContainerKind, verifyEncryptedBlob } from '../security/index.ts'
@@ -252,7 +253,9 @@ export function importRoutes(env: RoutesEnv): WebRoute[] {
             opts['secretInputs'] !== null && typeof opts['secretInputs'] === 'object'
               ? opts['secretInputs'] as Record<string, string>
               : {},
-          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）再执行。