dsh-config-manager 0.2.4 → 0.3.0

package/src/sync/git/git-transport.test.ts

@@ -119,6 +119,17 @@ function joinedArgs(calls: CallRecord[], needle: string): string[] {
   return calls.filter((c) => c.args.join(' ').includes(needle)).map((c) => c.args.join(' '));
 }
 
+/** 去掉 argv 前置的协议护栏（-c protocol.*.allow=never），用于断言「业务参数」本身 */
+function stripProtocolGuards(joined: string): string {
+  return joined.replace(/^(?:-c protocol\.[a-z]+\.allow=never )+/, '');
+}
+
+/** 单条调用是否带某个 -c 配置（必须成对出现） */
+function hasGitConfig(args: string[], kv: string): boolean {
+  const i = args.indexOf(kv);
+  return i > 0 && args[i - 1] === '-c';
+}
+
 /**
  * 拉取命令判定（issue #122）：fetch 与 origin 之间现在会插 `--no-tags`/`--filter=blob:none`，
  * 所以不能再按 'fetch origin' 子串匹配。
@@ -977,7 +988,8 @@ test('远端同步命令序列：显式 refspec fetch + merge --ff-only，绝不
     workDir: dir, exec: pullScriptedExec(calls, [{ stdout: '', stderr: '', code: 0 }]),
   }));
   await transport.list();
-  const joined = calls.map((c) => c.args.join(' '));
+  // SEC-12：每条 argv 前都挂协议护栏，断言业务参数前先剥掉
+  const joined = calls.map((c) => stripProtocolGuards(c.args.join(' ')));
   assert.ok(!joined.some((j) => /^pull(\s|$)/.test(j)), '不得再执行 git pull: ' + joined.join(' | '));
   // 网络命令前面会挂 credential helper 的 -c 参数，所以按「末尾 3 个参数」判命令本身
   // issue #122：fetch 与 origin 之间还会插 `--no-tags`（partial clone 时另有 `--filter=blob:none`），
@@ -1118,7 +1130,7 @@ test('issue #122：首次 clone 走 partial clone + sparse-checkout，只 materi
   const sparse = calls.find((c) => c.args.includes('sparse-checkout'));
   assert.ok(sparse !== undefined, '必须设置 sparse-checkout');
   assert.equal(
-    sparse.args.join(' '),
+    stripProtocolGuards(sparse.args.join(' ')),
     'sparse-checkout set --cone snapshots snapshots-encrypted blobs',
     'sparse 面必须与同步目录同源: ' + sparse.args.join(' '),
   );
@@ -1325,10 +1337,10 @@ test('issue #79：已有工作副本且 origin 与 repoUrl 不一致 → set-url
     exec: probeExec(calls, 'ssh://git@old.example:2222/owner/repo.git'),
   }));
   await transport.list();
-  assert.deepEqual(joinedArgs(calls, 'remote set-url'), [
-    `remote set-url origin ${target}`,
-    `remote set-url --push origin ${target}`,
-  ], 'fetch 与 push 地址都必须跟随（否则推送仍走旧地址）');
+  assert.deepEqual(joinedArgs(calls, 'remote set-url').map(stripProtocolGuards), [
+    `remote set-url origin -- ${target}`,
+    `remote set-url --push origin -- ${target}`,
+  ], 'fetch 与 push 地址都必须跟随（否则推送仍走旧地址）；repoUrl 恒由 -- 结束选项解析');
 });
 
 test('issue #79：origin 已一致 → 一条写命令都不发（幂等，只有只读探针）', async (t) => {
@@ -1347,7 +1359,7 @@ test('issue #79：无 origin（读不出来）→ remote add origin，否则 pus
   const target = 'ssh://git@fresh.example:2222/owner/repo.git';
   const transport = new GitTransport(makeOptions({ repoUrl: target, workDir: dir, exec: probeExec(calls, null) }));
   await transport.list();
-  assert.deepEqual(joinedArgs(calls, 'remote add origin'), [`remote add origin ${target}`]);
+  assert.deepEqual(joinedArgs(calls, 'remote add origin').map(stripProtocolGuards), [`remote add origin -- ${target}`]);
 });
 
 test('issue #79：origin 读得出但为空串 → 视为读不到，不改写（不拿不确定的读取覆盖配置）', async (t) => {
@@ -1716,3 +1728,152 @@ test('只读自检有界：锁被活进程持有时报「工作副本忙」，
 });
 
 
+
+/* ------------------------------------------------------------------------------------------------
+ * SEC-12 / SEC-03：repoUrl 不得被 git 当成命令行选项，也不得借协议开关读到本机任意仓库
+ *
+ * 事实：repoUrl 原样进 argv。于是「--upload-pack=touch /tmp/pwn」「-c core.pager=…」这类取值会被
+ * git 当成**选项**执行；「file:///…」则让 git 用本地文件协议去读任意本机仓库（sync 通道本该只碰
+ * 同步内容）。三道防线：构造期白名单（方案/主机/首字符）→ argv 恒带协议护栏 → repoUrl 前恒有 --。
+ * ---------------------------------------------------------------------------------------------- */
+test('SEC-12：以 - 开头 / 非网络方案 / 私网环回地址的 repoUrl → 构造期直接拒绝（一条 git 都不 spawn）', async (t) => {
+  const dir = await makeTempDir(t);
+  for (const repoUrl of [
+    '--upload-pack=touch /tmp/pwned',
+    '-c core.pager=touch /tmp/pwned',
+    'file:///c:/repos/x.git',
+    'ext::sh -c touch% /tmp/pwned',
+    'ftp://git.example.com/r.git',
+    'git://git.example.com/r.git',
+    'https://127.0.0.1:8443/r.git',
+    'https://[::1]/r.git',
+    'https://169.254.169.254/latest/meta-data/',
+    'https://10.1.2.3/r.git',
+    'https://172.20.0.1/r.git',
+    'https://192.168.0.9/r.git',
+  ]) {
+    const calls: CallRecord[] = [];
+    assert.throws(
+      () => new GitTransport(makeOptions({ repoUrl, workDir: dir, exec: mockExec(calls) })),
+      (err: unknown) => {
+        assert.ok(err instanceof GitTransportError, '必须是 GitTransportError: ' + repoUrl);
+        assert.match(err.message, /repoUrl/, '错误必须点明 repoUrl');
+        assert.ok(err.message.includes('[REPO_URL]'), '错误消息里的地址必须脱敏');
+        assert.ok(!err.message.includes('169.254.169.254'), '不得把危险地址原样回显');
+        return true;
+      },
+    );
+    assert.equal(calls.length, 0, '构造期拦截，不得先 spawn 再失败: ' + repoUrl);
+  }
+
+  // 本机路径仍是 git 通道既有的合法目标（real-git 集成测试就靠它），不得被白名单误伤
+  const local = new GitTransport(makeOptions({ repoUrl: path.join(dir, 'remote.git'), workDir: dir, exec: mockExec([]) }));
+  assert.ok(local);
+});
+
+test('SEC-12：协议护栏 —— 网络地址恒禁 ext + file；本机路径只禁 ext（否则本地仓老用法失效）', async (t) => {
+  const net = await makeTempDir(t);
+  const netCalls: CallRecord[] = [];
+  const netTransport = new GitTransport(makeOptions({ workDir: net, exec: mockExec(netCalls) }));
+  await netTransport.list();
+  assert.ok(netCalls.length > 0, '应有 git 调用');
+  for (const c of netCalls) {
+    assert.ok(hasGitConfig(c.args, 'protocol.ext.allow=never'), '每条 git 都必须禁 ext 兜底（ext:: 可执行任意命令）: ' + c.args.join(' '));
+    assert.ok(hasGitConfig(c.args, 'protocol.file.allow=never'), '网络地址还须禁 file（防被改写成 file:// 后读本机仓）: ' + c.args.join(' '));
+  }
+
+  const localDir = await makeTempDir(t);
+  const localCalls: CallRecord[] = [];
+  const localTransport = new GitTransport(makeOptions({
+    repoUrl: path.join(localDir, 'remote.git'), workDir: localDir, exec: mockExec(localCalls),
+  }));
+  await localTransport.list();
+  assert.ok(localCalls.length > 0, '应有 git 调用');
+  for (const c of localCalls) {
+    assert.ok(hasGitConfig(c.args, 'protocol.ext.allow=never'), 'ext 护栏对任何地址都开: ' + c.args.join(' '));
+    assert.ok(!hasGitConfig(c.args, 'protocol.file.allow=never'), '本机路径不得禁 file（否则 clone 本地仓直接失败）: ' + c.args.join(' '));
+  }
+});
+
+test('SEC-12：repoUrl 恒由 -- 与选项分开（clone / ls-remote / remote add）', async (t) => {
+  const dir = await makeTempDir(t);
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+  await transport.list();
+
+  const urlArgIndex = (args: string[]): number => args.indexOf('https://github.com/example/private-config.git');
+  const withUrl = calls.filter((c) => urlArgIndex(c.args) >= 0);
+  assert.ok(withUrl.length > 0, '应有带 repoUrl 的调用: ' + calls.map((c) => c.args.join(' ')).join(' | '));
+  for (const c of withUrl) {
+    const i = urlArgIndex(c.args);
+    assert.equal(c.args[i - 1], '--', 'repoUrl 前必须有 -- 结束选项解析: ' + c.args.join(' '));
+  }
+
+  // remote add 同样受约束（工作副本已存在但 origin 读不到）
+  const wd = await makeGitWorkDir(t);
+  const remotes: CallRecord[] = [];
+  const t2 = new GitTransport(makeOptions({ workDir: wd, exec: probeExec(remotes, null) }));
+  await t2.list();
+  const add = remotes.filter((c) => c.args.includes('add'));
+  assert.equal(add.length, 1, '应 remote add: ' + remotes.map((c) => c.args.join(' ')).join(' | '));
+  const ai = add[0]!.args.indexOf('https://github.com/example/private-config.git');
+  assert.equal(add[0]!.args[ai - 1], '--', 'remote add 的 repoUrl 前必须有 --');
+});
+
+/* ------------------------------------------------------------------------------------------------
+ * RV1-F8：错误消息与返回体不得回显真 repoUrl
+ *
+ * 事实：构造期已用 `[REPO_URL]` 占位符，但 `repoHost()` 的 catch、`cmdFailed` 的 `{args}`（argv 里
+ * 原样带着 repoUrl）、以及 `inspectWorkDir()` 回传的 origin/pushUrl 仍可能把 `user:token@` 带出去 ——
+ * 这些字符串会进日志、进 GET /sync/status 响应、进用户贴出来的 issue 截图。
+ * 口径：错误/日志一律占位符（mask），返回体保留 host/path 但剥掉 userinfo。
+ * ---------------------------------------------------------------------------------------------- */
+test('RV1-F8：错误文本与工作副本自检返回体都不含 userinfo（token 一条都不许出）', async (t) => {
+  const secret = 'ghp_leaktoken0123456789';
+  const secretUrl = 'ssh://user:' + secret + '@git.example.com/u/r.git';
+
+  // ① exec 抛错 → cmdFailed 的 {args} 含 repoUrl 原文，必须经 mask
+  const dir = await makeTempDir(t);
+  const throwing: GitExecFn = async (_cmd, args): Promise<GitExecResult> => {
+    if (args.includes('ls-remote')) throw new Error('spawn git ENOENT: ' + args.join(' '));
+    return { stdout: '', stderr: '', code: 0 };
+  };
+  const transport = new GitTransport(makeOptions({ repoUrl: secretUrl, workDir: dir, exec: throwing }));
+  let raised: unknown = null;
+  try {
+    await transport.checkIsPrivate();
+  } catch (err) {
+    raised = err;
+  }
+  assert.ok(raised instanceof GitTransportError, '必须归一为 GitTransportError');
+  const msg1 = (raised as GitTransportError).message;
+  assert.ok(msg1.includes('[REPO_URL]'), '回显必须走占位符: ' + msg1);
+  assert.ok(!msg1.includes(secret), 'argv 里的地址含 token —— 错误文本不得回显: ' + msg1);
+  assert.ok(!msg1.includes('user:'), '不得回显 userinfo 片段: ' + msg1);
+
+  // ② 工作副本自检的 origin / pushUrl 会进 GET /sync/status 响应 → 只剥 userinfo，保留 host/path
+  const wd = await makeGitWorkDir(t);
+  const calls: CallRecord[] = [];
+  const inspector = new GitTransport(makeOptions({ repoUrl: secretUrl, workDir: wd, exec: probeExec(calls, secretUrl) }));
+  const facts = await inspector.inspectWorkDir();
+  assert.equal(facts.origin, 'ssh://git.example.com/u/r.git', 'origin 必须剥掉 userinfo: ' + String(facts.origin));
+  assert.equal(facts.pushUrl, 'ssh://git.example.com/u/r.git', 'pushUrl 同样剥掉 userinfo: ' + String(facts.pushUrl));
+  assert.ok(!JSON.stringify(facts).includes(secret), 'facts 里任何字段都不得残留 token');
+  assert.equal(facts.match, true, '匹配判定用原文比对，不受脱敏影响');
+
+  // ③ 地址解析不出主机时（本机路径走 repoHost），错误里也只是占位符
+  const localDir = await makeTempDir(t);
+  const localTransport = new GitTransport(makeOptions({
+    repoUrl: path.join(localDir, 'remote.git'), workDir: localDir, exec: mockExec([]),
+  }));
+  let hostErr: unknown = null;
+  try {
+    // 私有可见性探测会走 buildCredentialArgs → repoHost()；本机路径 new URL() 必失败
+    await localTransport.checkIsPrivate();
+  } catch (err) {
+    hostErr = err;
+  }
+  if (hostErr instanceof GitTransportError) {
+    assert.ok(!hostErr.message.includes(localDir), '本机路径同样不得原样回显: ' + hostErr.message);
+  }
+});

package/src/sync/git/git-transport.ts

@@ -31,6 +31,7 @@ import type { SnapshotDirManifest } from '../layout.ts';
 import { BLOB_SECTIONS, gcBlobs, referencedBlobHashes } from '../blob-store.ts';
 import type { BlobSink } from '../blob-store.ts';
 import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.ts';
+import { classifyRepoUrl, isPrivateRepoHost } from '../sync-config.ts';
 import {
   classifyNetworkErrorText, computeSnapshotMeta, DEFAULT_SYNC_TIMEOUT_MS, isEncryptedSections,
   SyncTransportError, withSyncRetry,
@@ -198,6 +199,19 @@ const SYNC_ROOT_DIRS: readonly string[] = [...ADOPT_ROOT_ALLOW];
  */
 const NETWORK_SUBCOMMANDS = new Set<string>(['clone', 'fetch', 'push', 'ls-remote', 'pull']);
 const LOW_SPEED_ARGS: readonly string[] = ['-c', 'http.lowSpeedLimit=1000', '-c', 'http.lowSpeedTime=30'];
+/**
+ * 协议护栏（SEC-12）：**所有** git 子进程恒带，与「这条命令走不走网络」无关。
+ *
+ * 为什么恒带而不是只给网络命令：危险的不只是远端协议本身 —— `ext::sh -c ...` / `file://`
+ * 这类地址在 clone/fetch 之外还能经 `remote set-url`、配置重载等路径被触发，而本插件的 repoUrl
+ * 来自用户可编辑的 sync-config.json 与可导入的配置包。把 `ext` 与 `file` 传输整体关掉，
+ * 就等于「repoUrl 无论被改成什么，都只能走 http/https/ssh 三种真协议」。
+ */
+const PROTOCOL_GUARD_ARGS: readonly string[] = ['-c', 'protocol.ext.allow=never'];
+/** 网络仓库额外禁 file 传输（本地目录仓库是显式支持的用法，不能一刀切禁掉）。 */
+const FILE_PROTOCOL_GUARD_ARGS: readonly string[] = ['-c', 'protocol.file.allow=never'];
+/** 报错/日志里回显的地址占位符：不带真实 repoUrl（脱敏由上层的 mask() 负责）。 */
+const REPO_URL_PLACEHOLDER = '[REPO_URL]';
 const DEFAULT_AUTHOR: GitAuthor = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
@@ -361,6 +375,8 @@ export class GitTransport implements SyncTransport {
    */
   private readErrors: { file: string; reason: string }[] = [];
   private readonly msg: MsgFunc;
+  /** repoUrl 是否为网络地址（本地目录仓库 == false）：决定要不要额外禁 file 传输（SEC-12）。 */
+  private readonly networkRepo: boolean;
 
   constructor(options: GitTransportOptions) {
     if (typeof options.repoUrl !== 'string' || options.repoUrl.length === 0) {
@@ -374,6 +390,16 @@ export class GitTransport implements SyncTransport {
       throw new GitTransportError(zhMsg('sync.git.credentialsRequired'));
     }
     this.msg = options.msg ?? zhMsg;
+    // SEC-12：repoUrl 来自用户可编辑配置与可导入配置包 —— 构造期就收成「只能是真网络地址或本地目录」，
+    // 环回/私网/链路本地一律拒（把家目录配置推到 localhost 上的抓取器是最省事的外泄方式）。
+    // **已知行为变更**：局域网 NAS / 内网 git 服务器作为同步目标此后会被拒绝（见 sync-config.ts
+    // 的 isPrivateRepoHost 注释里的取舍说明），这是有意的安全收紧，不是回归。
+    // 地址本体不回显进错误（占位符代替），脱敏仍由 mask() 兜底。
+    const repoShape = classifyRepoUrl(options.repoUrl);
+    if (repoShape === null || (repoShape.kind !== 'local' && isPrivateRepoHost(repoShape.host))) {
+      throw new GitTransportError(this.msg('sync.git.repoUrlInvalid', { url: REPO_URL_PLACEHOLDER }));
+    }
+    this.networkRepo = repoShape.kind !== 'local';
     this.o = {
       repoUrl: options.repoUrl,
       workDir: options.workDir,
@@ -583,12 +609,12 @@ export class GitTransport implements SyncTransport {
    */
   async checkIsPrivate(): Promise<boolean> {
     if (this.privateHint !== null) return this.privateHint;
-    const anon = await this.runGit(['ls-remote', this.o.repoUrl], { allowNonZero: true, cwd: undefined });
+    const anon = await this.runGit(['ls-remote', '--', this.o.repoUrl], { allowNonZero: true, cwd: undefined });
     if (anon.code === 0) {
       this.privateHint = false;
       return false;
     }
-    const authed = await this.runGit(['ls-remote', this.o.repoUrl], { allowNonZero: true, cwd: undefined, withCredential: true });
+    const authed = await this.runGit(['ls-remote', '--', this.o.repoUrl], { allowNonZero: true, cwd: undefined, withCredential: true });
     if (authed.code === 0) {
       this.privateHint = true;
       return true;
@@ -708,7 +734,7 @@ export class GitTransport implements SyncTransport {
   private async cloneIntoWorkDir(): Promise<void> {
     const cwd = this.o.workDir;
     this.partialClone = null; // reclone 后重新判定（配置可能变）
-    const filteredArgs = ['clone', '--filter=blob:none', '--no-checkout', this.o.repoUrl, '.'];
+    const filteredArgs = ['clone', '--filter=blob:none', '--no-checkout', '--', this.o.repoUrl, '.'];
     const filtered = await this.runGit(filteredArgs, { cwd, withCredential: true, allowNonZero: true });
     if (filtered.code !== 0) {
       if (!UNSUPPORTED_GIT_OPTION_RE.test(filtered.stderr + ' ' + filtered.stdout)) {
@@ -717,7 +743,7 @@ export class GitTransport implements SyncTransport {
       }
       // 老 git：回落全量 clone（全量 clone 自带 checkout）
       await clearDirContents(cwd);
-      await this.runGit(['clone', this.o.repoUrl, '.'], { cwd, withCredential: true });
+      await this.runGit(['clone', '--', this.o.repoUrl, '.'], { cwd, withCredential: true });
       return;
     }
     const branch = await this.currentBranch();
@@ -789,15 +815,15 @@ export class GitTransport implements SyncTransport {
     const current = await this.runGit(['remote', 'get-url', 'origin'], { allowNonZero: true });
     const origin = current.code === 0 ? current.stdout.trim() : '';
     if (current.code !== 0) {
-      await this.runGit(['remote', 'add', 'origin', this.o.repoUrl]);
+      await this.runGit(['remote', 'add', 'origin', '--', this.o.repoUrl]);
     } else if (origin !== '' && origin !== this.o.repoUrl) {
-      await this.runGit(['remote', 'set-url', 'origin', this.o.repoUrl]);
+      await this.runGit(['remote', 'set-url', 'origin', '--', this.o.repoUrl]);
       this.partialClone = null; // 换了远端 ⇒ promisor 判定失效（issue #122）
     }
     const push = await this.runGit(['remote', 'get-url', '--push', 'origin'], { allowNonZero: true });
     const pushUrl = push.code === 0 ? push.stdout.trim() : '';
     if (pushUrl !== '' && pushUrl !== this.o.repoUrl) {
-      await this.runGit(['remote', 'set-url', '--push', 'origin', this.o.repoUrl]);
+      await this.runGit(['remote', 'set-url', '--push', 'origin', '--', this.o.repoUrl]);
     }
   }
 
@@ -896,8 +922,9 @@ export class GitTransport implements SyncTransport {
     return {
       path: this.o.workDir,
       exists: true,
-      origin: origin === '' ? null : origin,
-      pushUrl: pushRaw === '' ? null : pushRaw,
+      // RV1-F8：这两个字段会进 GET /sync/status 的响应 → 剥掉可能存在的 userinfo token
+      origin: origin === '' ? null : this.bareUrl(origin),
+      pushUrl: pushRaw === '' ? null : this.bareUrl(pushRaw),
       // 读不出 origin（null）→ 不算 match（状态接口据此提示「工作副本地址未知」）
       match: origin === this.o.repoUrl && (pushRaw === '' || pushRaw === this.o.repoUrl),
       ahead,
@@ -1138,6 +1165,10 @@ export class GitTransport implements SyncTransport {
     const cwd = opts.cwd === undefined ? this.o.workDir : opts.cwd;
     // 网络子命令一律带低速上限：真卡住在 30 s 内明确失败，而不是耗满 timeoutMs（issue #122）
     const networkArgs = NETWORK_SUBCOMMANDS.has(args[0] ?? '') ? [...LOW_SPEED_ARGS] : [];
+    // SEC-12：协议护栏恒带（见 PROTOCOL_GUARD_ARGS）；网络仓库再额外禁 file 传输。
+    const guardArgs = this.networkRepo
+      ? [...PROTOCOL_GUARD_ARGS, ...FILE_PROTOCOL_GUARD_ARGS]
+      : [...PROTOCOL_GUARD_ARGS];
     let extra: string[] = [];
     let token: string | null = null;
     let cleanup: (() => Promise<void>) | null = null;
@@ -1156,7 +1187,7 @@ export class GitTransport implements SyncTransport {
     // 而目录里原本就有别的内容时宁可放弃重试，也绝不删用户文件。
     const cloneTargetWasEmpty = args[0] === 'clone' ? await isEmptyDir(cwd) : false;
     try {
-      let result = await this.o.exec(this.o.gitBin, [...extra, ...networkArgs, ...args], { cwd, timeoutMs: this.o.timeoutMs });
+      let result = await this.o.exec(this.o.gitBin, [...extra, ...guardArgs, ...networkArgs, ...args], { cwd, timeoutMs: this.o.timeoutMs });
       // issue #120：credential helper 必须经 shell 执行（值里不含空格也一样，git 统一拼成
       // `sh -c 'git <helper> ...'`），而 Android 上 git 二进制的 GIT_SHELL_PATH 指向 App 沙箱里
       // 不存在的 Termux sh；`core.askpass` 又要 exec 权限（Android 10+ 对 targetSdk ≥ 29 禁执行应用
@@ -1166,7 +1197,7 @@ export class GitTransport implements SyncTransport {
         const headerEnv = credentialHeaderEnv(this.o.repoUrl, this.o.credentialUsername, token);
         if (Object.keys(headerEnv).length > 0 && (args[0] !== 'clone' || cloneTargetWasEmpty)) {
           if (args[0] === 'clone') await clearDirContents(cwd);
-          result = await this.o.exec(this.o.gitBin, [...networkArgs, ...args], { cwd, timeoutMs: this.o.timeoutMs, env: headerEnv });
+          result = await this.o.exec(this.o.gitBin, [...guardArgs, ...networkArgs, ...args], { cwd, timeoutMs: this.o.timeoutMs, env: headerEnv });
         }
       }
       if (result.code !== 0 && !opts.allowNonZero) {
@@ -1178,7 +1209,8 @@ export class GitTransport implements SyncTransport {
       // 注入的 exec 实现可能直接抛错（默认实现只返回非零 code）——同样归一为带分类的传输层错误
       const detail = err instanceof Error ? err.message : String(err);
       throw new GitTransportError(
-        this.msg('sync.git.cmdFailed', { args: args.join(' '), code: 'exec', err: this.mask(detail, token) }),
+        // argv 里含 repoUrl 原文（clone/ls-remote/remote set-url -- <url>）→ 必须经 mask 才进文案
+        this.msg('sync.git.cmdFailed', { args: this.mask(args.join(' '), token), code: 'exec', err: this.mask(detail, token) }),
         { ...classifyNetworkErrorText(detail), cause: err },
       );
     } finally {
@@ -1210,7 +1242,7 @@ export class GitTransport implements SyncTransport {
         ? this.msg('sync.git.pushAuthFailed', { err: this.mask(result.stderr, token) })
         : args[0] === 'clone' && classified.kind === 'auth'
           ? this.msg('sync.git.cloneAuthFailed', { err: this.mask(result.stderr, token) })
-          : this.msg('sync.git.cmdFailed', { args: args.join(' '), code: String(result.code), err: this.mask(result.stderr, token) });
+          : this.msg('sync.git.cmdFailed', { args: this.mask(args.join(' '), token), code: String(result.code), err: this.mask(result.stderr, token) });
     // 归类同样不能交给原文：`cannot exec ...: No such file or directory` 里的 ENOENT 会被判成
     // notfound（「仓库不存在」），而真实原因是凭据通道不可用 → 钉成 auth（非瞬时、别重试）。
     throw new GitTransportError(message, credentialBlocked ? { kind: 'auth', retryable: false } : classified);
@@ -1258,7 +1290,8 @@ export class GitTransport implements SyncTransport {
       const u = new URL(this.o.repoUrl);
       return u.port ? `${u.hostname}:${u.port}` : u.hostname;
     } catch {
-      throw new GitTransportError(this.msg('sync.git.repoUrlInvalid', { url: this.o.repoUrl }));
+      // RV1-F8：回显一律占位符 —— repoUrl 可能带 userinfo token，错误消息会进日志/响应/issue 截图
+      throw new GitTransportError(this.msg('sync.git.repoUrlInvalid', { url: REPO_URL_PLACEHOLDER }));
     }
   }
 
@@ -1268,6 +1301,29 @@ export class GitTransport implements SyncTransport {
     try { return await this.o.credentials.getToken(); } catch { return null; }
   }
 
+  /**
+   * 回传体里的地址（工作副本自检的 origin / pushUrl）脱敏：只剥「凭据段」，其余原样保留。
+   *
+   * 为什么不整串换占位符：状态面板要显示「工作副本现在指向哪个远端」，用户靠 host/path 判断是否
+   * 已跟随配置。为什么不一律剥 userinfo：`ssh://git@host` 里的 `git` 是 ssh 登录名（标准写法），
+   * 剥掉会让用户认不出自己的远端 —— 与 validateRepoUrl 的口径保持一致（只有 password 位是凭据）。
+   */
+  private bareUrl(url: string): string {
+    try {
+      const parsed = new URL(url);
+      const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();
+      const keepSshUser = scheme === 'ssh' && parsed.password === '';
+      const dirty = parsed.password !== '' || (parsed.username !== '' && !keepSshUser);
+      if (!dirty) return url;
+      parsed.username = '';
+      parsed.password = '';
+      return parsed.toString();
+    } catch {
+      // 解析不了（scp 式 `git@host:path` 或本机路径）：`git@` 是登录名不是凭据，原样返回
+      return url;
+    }
+  }
+
   /** 错误/日志脱敏：token（原文与 URL 编码两种形态）与 repoUrl 一律替换 */
   private mask(text: string, token: string | null): string {
     let out = text.split(this.o.repoUrl).join('[REPO_URL]');

package/src/sync/merge-preview-text.ts

@@ -0,0 +1,37 @@
+import { redact } from '../security/redaction.ts';
+
+/** 单侧预览文本上限（2 KiB **字符**预算）：超出截断并追加省略号。 */
+export const MERGE_PREVIEW_TEXT_LIMIT = 2048;
+
+/** 严格 UTF-8 解码器：非法字节序列直接抛错（用于区分文本与二进制文件冲突）。 */
+const STRICT_UTF8 = new TextDecoder('utf-8', { fatal: true });
+
+/**
+ * 预览文本统一出口：先 redact（敏感值绝不回传浏览器），再截断到 2 KiB。
+ *
+ * 顺序恒为「先 redact 再截断」：反过来会把跨边界的敏感值切成半个形状，让脱敏匹配不到它
+ * （等于把秘密截一半发出去）。redact 之后的剩余文本已不含秘密形状，截断才安全。
+ */
+export function finalizePreviewText(text: string): string {
+  const masked = redact(text);
+  return masked.length > MERGE_PREVIEW_TEXT_LIMIT ? `${masked.slice(0, MERGE_PREVIEW_TEXT_LIMIT)}…` : masked;
+}
+
+/** 把任意冲突侧值转成**可读字符串**；二进制只回传形状与字节数，绝不回传原始值对象。 */
+export function previewTextOf(value: unknown): string {
+  if (value === undefined) return '';
+  if (typeof value === 'string') return finalizePreviewText(value);
+  if (value instanceof Uint8Array) {
+    try {
+      return finalizePreviewText(STRICT_UTF8.decode(value));
+    } catch {
+      // 二进制内容解码只会得到乱码（同样误导用户）→ 只回传形状；JSON 是数据形态，不是文案
+      return JSON.stringify({ binary: true, bytes: value.length });
+    }
+  }
+  try {
+    return finalizePreviewText(JSON.stringify(value) ?? '');
+  } catch {
+    return finalizePreviewText(String(value));
+  }
+}

package/src/sync/s3/s3-delete-index-404.test.ts

@@ -11,7 +11,9 @@
  *   ② index 读操作抛错  → 显式失败（F2 语义，绝不回落成空索引）；
  *   ③ index = 200 + []  → 索引权威地声明集合为空，保持既有语义（既有用例
  *      「blob GC：删除最后一份快照后回收超保护窗的无人引用 blob」钉住该路径）；
- *   ④ GC 遇到「索引有条目但快照文件读不出来（非 404）」→ 本轮放弃（读不出来 ≠ 没引用）。
+ *   ④ GC 遇到「索引有条目但快照文件读不出来（非 404）」→ 本轮放弃（读不出来 ≠ 没引用）；
+ *   ⑤ SYN-04（P1）：与 WebDAV 同型 —— **404 也放弃本轮**（孤儿条目 / 假 404 拿不到内容就无法证明
+ *      「没人引用」），本轮 0 删除并记下放弃码（`lastGcSkip`，机器可判定）。
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
@@ -168,3 +170,26 @@ test('N1⑤：索引有条目但该快照文件读不出来（非 404）→ 本
   assert.equal(remote.deletedBlobs.length, 0, '读不出 sync-ccc-333 就无法证明它没引用 blob → 本轮不得删任何 blob');
   assert.equal(remote.objects.has(PREFIX + '/blobs/' + BLOB_HASH), true);
 });
+
+test('N1⑥（SYN-04）：索引有条目但该快照文件真 404 → 本轮放弃 GC（404 也证明不了「没引用」）+ 记放弃码', async () => {
+  const remote = makeRemote({
+    index: JSON.stringify([meta('sync-aaa-111', '1'), meta('sync-ccc-333', '3')]),
+    snapshotFiles: { 'sync-aaa-111': snapOf('sync-aaa-111', PLAIN) },
+  });
+  const t = new S3Transport(makeOptions(remote));
+  await t.delete('sync-aaa-111');
+  assert.equal(remote.deletedBlobs.length, 0, '404 与「读不出来」同属「无法证明没有引用」→ 本轮 0 删除');
+  assert.equal(remote.objects.has(PREFIX + '/blobs/' + BLOB_HASH), true, '没有被证明无引用的 blob 必须保留');
+  assert.equal(t.lastGcSkip, 'gc-skip-reference-missing', '必须记下本轮放弃码（机器可判定，文案由上层按码翻译）');
+});
+
+test('N1⑦（SYN-04）：引用者 200 但内容坏掉 → 本轮放弃，放弃码 = snapshot-unparsable', async () => {
+  const remote = makeRemote({
+    index: JSON.stringify([meta('sync-aaa-111', '1'), meta('sync-ccc-333', '3')]),
+    snapshotFiles: { 'sync-aaa-111': snapOf('sync-aaa-111', PLAIN), 'sync-ccc-333': 'not-json' },
+  });
+  const t = new S3Transport(makeOptions(remote));
+  await t.delete('sync-aaa-111');
+  assert.equal(remote.deletedBlobs.length, 0, '解析不了 ⇒ 引用集不完整 ⇒ 本轮不得删任何 blob');
+  assert.equal(t.lastGcSkip, 'gc-skip-snapshot-unparsable');
+});

package/src/sync/s3/s3-transport.ts

@@ -26,6 +26,8 @@ import { requestOnce } from '../../utils/proxy.ts';
 import type { RawResponse } from '../../utils/proxy.ts';
 import { parseJsonSafe } from '../../utils/json.ts';
 import type { MsgFunc } from '../../core/msg-types.ts';
+import { GC_SKIP_REFERENCE_MISSING, GC_SKIP_REFERENCE_UNREADABLE, GC_SKIP_SNAPSHOT_UNPARSABLE } from '../gc-skip.ts';
+import type { GcSkipCode } from '../gc-skip.ts';
 import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.ts';
 import {
   BLOB_SECTIONS, gcBlobs, isBlobRefsSection, isFilesSectionLike, referencedBlobHashes,
@@ -213,6 +215,14 @@ export class S3Transport implements SyncTransport {
     msg: MsgFunc;
   };
 
+  /** 最近一轮 blob GC 的放弃码（`null` = 跑完或未触发；SYN-04）。 */
+  private gcSkip: GcSkipCode | null = null;
+
+  /** 最近一轮 blob GC 是否因「无法证明引用集完整」而整体放弃（`null` = 正常跑完），供上层给用户提示。 */
+  get lastGcSkip(): GcSkipCode | null {
+    return this.gcSkip;
+  }
+
   constructor(options: S3TransportOptions) {
     // t79：宿主传进来的 msg（core 目录）**不包含** sync.s3.* 键，直接用会显示裸键名 —— 合并本地目录。
     const msg = composeMsg(options.msg, s3Msg);
@@ -708,20 +718,29 @@ export class S3Transport implements SyncTransport {
   }
 
   /** blob 仓 GC：逐份读仍存在的快照收集引用，删除无人引用且超保护窗的 blob；
-   *  读坏任一份快照 → 本轮直接放弃（宁可留垃圾，不可删在用的） */
+   *  读不坏任何一份快照 → 正常回收，否则本轮整体放弃（宁可留垃圾，不可删在用的）。
+   *  SYN-04（P1）：**404 也放弃本轮** —— 条目在但文件 404 = 拿不到内容 = 无法证明「没人引用」，
+   *  按残集回收会删掉仍在用的 blob（与 WebDAV 同型，口径一致）。 */
   private async gcBlobStore(secret: string, remaining: SyncSnapshotMeta[]): Promise<void> {
+    this.gcSkip = null;
     const index = await this.readBlobIndex(secret);
     if (Object.keys(index).length === 0) return;
     const referenced = new Set<string>();
     for (const meta of remaining) {
       const sent = await this.send('GET', snapshotKey(this.target.prefix, meta.id), { secret });
-      // 条目在但文件 404 ⇒ 不可能引用 blob（安全跳过）；其它失败 ⇒ 读不出来 ≠ 没引用，本轮放弃。
-      if (sent.res.status === 404) continue;
-      if (!sent.res.ok) return;
+      if (sent.res.status === 404) {
+        this.gcSkip = GC_SKIP_REFERENCE_MISSING;
+        return;
+      }
+      if (!sent.res.ok) {
+        this.gcSkip = GC_SKIP_REFERENCE_UNREADABLE;
+        return;
+      }
       let snap: SyncSnapshot;
       try {
         snap = deserializeSnapshot(await sent.res.text());
       } catch {
+        this.gcSkip = GC_SKIP_SNAPSHOT_UNPARSABLE;
         return;
       }
       const plain = snap.sections as Partial<Record<SectionId, unknown>>;

package/src/sync/session-tombstones.ts

@@ -18,6 +18,9 @@
  *    本次不实现（保留信息可见，不代用户删数据）。
  */
 import { sha256Hex } from '../utils/hashing.ts';
+import { isEncryptedSections } from './transport.ts';
+import type { SectionData, SectionId } from '../schema/types.ts';
+import type { SyncSnapshotMeta, SyncTransport } from './transport.ts';
 
 /** 会话单元 id 前缀（与 SessionsAdapter.unitIdOf 同口径：`sessions:<projectKey>/<sessionId>`）。 */
 export const SESSION_UNIT_PREFIX = 'sessions:';
@@ -121,3 +124,90 @@ export function sessionUnitIdsOfSection(section: unknown): string[] {
 export function unitSetFingerprint(units: readonly string[]): string {
   return sha256Hex([...units].sort().join('\n'));
 }
+
+/* ---------------- SYN-02：墓碑跨设备继承（远端 → 本机 → 下一份快照） ---------------- */
+
+/**
+ * 一次远端 list() 的读取结果。
+ *
+ * `metas` 为空**且**无 `reason` 才代表「远端确实为空」；有 reason = 读不到（按「看不到远端」
+ * 处理，调用方告警后继续，绝不把它当成「远端没东西」而误判）。
+ */
+export interface RemoteSnapshotIndex {
+  metas: SyncSnapshotMeta[];
+  reason?: string;
+}
+
+/** 读一次远端快照索引（只读、零写入）。push 的「是否被推进」判定与墓碑继承共用这一份。 */
+export async function listRemoteSnapshotIndex(transport: Pick<SyncTransport, 'list'>): Promise<RemoteSnapshotIndex> {
+  try {
+    return { metas: await transport.list() };
+  } catch (error) {
+    return { metas: [], reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * 远端最新快照携带的会话删除墓碑（去重、去空、保序）。
+ *
+ * 只取**最新一份**：manifest.deletedSessions 是累积清单（见文件头），旧快照的墓碑必然被后续
+ * 快照包含；把整段历史并起来只会让「已经在别处撤销的墓碑」复活。
+ * 远端为空 / 老快照缺字段 → 空数组（行为与改造前逐字一致：不继承任何墓碑）。
+ */
+export function remoteTombstonesOf(metas: readonly SyncSnapshotMeta[]): string[] {
+  const latest = metas.length === 0 ? undefined : metas[metas.length - 1];
+  const list = latest?.manifest.deletedSessions ?? [];
+  return [...new Set(list.filter((id) => typeof id === 'string' && id !== ''))];
+}
+
+/** 一次 push 的会话簿记结果（manifest / baseline / 告警共用这一份）。 */
+export interface SessionBookkeepingResult {
+  /** false = 本次没有可用的会话枚举（没推 sessions / 适配器不支持 / 枚举失败或为空） */
+  tracked: boolean;
+  sessionUnits: string[];
+  tombstones: string[];
+  /** 本次**新**发现的删除（之前推过、这次本机没了） */
+  deletedNow: string[];
+  /** 从远端继承来的墓碑条数（本机此前没有、且本机也没有实体） */
+  inherited: number;
+}
+
+/**
+ * 墓碑集合的唯一计算点（本机删除 + 远端继承合进同一条累积链）。
+ *
+ * 去重、FIFO 上限、以及「本机还有实体 ⇒ 撤销墓碑」这条不变量对继承来的墓碑同样适用：
+ * 另一台设备删了、本机仍有 → 用户在本机显然没删，绝不把它记成本机删除。
+ */
+export function planSessionBookkeeping(args: {
+  previousUnits: readonly string[];
+  previousTombstones: readonly string[];
+  localUnits: readonly string[];
+  exportedSessions: SectionData | undefined;
+  remoteTombstones: readonly string[];
+}): Omit<SessionBookkeepingResult, 'tracked'> {
+  const known = args.previousTombstones;
+  const knownSet = new Set(known);
+  const localSet = new Set(args.localUnits);
+  const inherited = args.remoteTombstones.filter((id) => !knownSet.has(id) && !localSet.has(id)).length;
+  const { tombstones, deletedNow } = nextSessionTombstones({
+    previousUnits: [...args.previousUnits],
+    localUnits: [...args.localUnits],
+    previousTombstones: [...known, ...args.remoteTombstones],
+  });
+  return { sessionUnits: sessionUnitIdsOfSection(args.exportedSessions), tombstones, deletedNow, inherited };
+}
+
+/** 按墓碑剔除**将要导入**的会话（旧快照不得复活已删除的对话）。只动载荷，不动本机数据。 */
+export function stripTombstonedSessionsInPlace<P extends {
+  manifest: { deletedSessions?: readonly string[] };
+  sections: unknown;
+}>(snapshot: P): string[] {
+  const tombstones = snapshot.manifest.deletedSessions ?? [];
+  if (tombstones.length === 0 || isEncryptedSections(snapshot.sections)) return [];
+  const plain = snapshot.sections as Partial<Record<SectionId, SectionData>>;
+  const stripped = stripTombstonedUnits(plain['sessions'], tombstones);
+  if (stripped.removed.length === 0) return [];
+  plain['sessions'] = stripped.section as SectionData;
+  return stripped.removed;
+}
+