dsh-config-manager 0.2.4 → 0.3.0

package/lib/sync/gc-skip.js

@@ -0,0 +1,57 @@
+/**
+ * 本轮 blob GC 的放弃码（SYN-04）。**机器可判定**，文案由上层按码翻译（字典键由 Lead 统一加）：
+ * 通道没有 logger，`delete()` 还会吞掉 GC 抛出的异常，所以「本轮为什么没回收」只能靠这个码如实外露。
+ * 三态同义：拿不到引用者内容 = 无法证明「没人引用」⇒ 本轮整轮放弃，绝不按残集删除。
+ *
+ * 单一来源：webdav / s3 两个通道都从这里导入（此前各写一份同名常量，改一侧不炸另一侧 =
+ * 静默漂移；本模块不 import 任何 transport，所以不存在环）。
+ */
+export const GC_SKIP_REFERENCE_MISSING = 'gc-skip-reference-missing';
+export const GC_SKIP_REFERENCE_UNREADABLE = 'gc-skip-reference-unreadable';
+export const GC_SKIP_SNAPSHOT_UNPARSABLE = '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 function readGcSkipCode(transport) {
+    try {
+        const raw = transport?.lastGcSkip;
+        return typeof raw === 'string' && raw !== '' ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * SYN-04b：放弃码 → 一条 warning 文本。
+ *
+ * 码必须同时以**明文**出现：core 目录的翻译器对未知键回退键名本身（{code} 插值随之丢失），
+ * 而文案键由上层统一补字典 —— 在补键之前，只发出裸键名等于「报了但看不出来」，日志也无法 grep。
+ */
+export function gcSkipWarning(msg, code) {
+    const text = msg('sync.gcSkipped', { code });
+    return text.includes(code) ? text : text + ': ' + code;
+}
+/**
+ * SYN-04b：把通道的 GC 放弃码冒泡成一条 warning（`state` 保证同一轮只报一次）。
+ *
+ * 语义边界：放弃 GC **不是** push 失败 —— 快照本身已上传/已删除，只是这一轮的孤儿 blob
+ * 没被回收（磁盘/远端会多留几份文件）。所以它进 warnings、不进 ok，与 prune 既有语义一致。
+ */
+export function reportGcSkipOnce(transport, msg, warnings, state) {
+    if (state.done)
+        return;
+    const code = readGcSkipCode(transport);
+    if (code === null)
+        return;
+    state.done = true;
+    warnings.push(gcSkipWarning(msg, code));
+}
+//# sourceMappingURL=gc-skip.js.map

package/lib/sync/git/git-transport.d.ts

@@ -109,6 +109,8 @@ export declare class GitTransport implements SyncTransport {
      */
     private readErrors;
     private readonly msg;
+    /** repoUrl 是否为网络地址（本地目录仓库 == false）：决定要不要额外禁 file 传输（SEC-12）。 */
+    private readonly networkRepo;
     constructor(options: GitTransportOptions);
     /** 最近一次 checkIsPrivate() 的结果；null = 尚未检查 */
     get isPrivateHint(): boolean | null;
@@ -283,6 +285,14 @@ export declare class GitTransport implements SyncTransport {
     private repoHost;
     /** 读取一次 token（错误消息脱敏用）；非 http(s) 场景返回空 */
     private readTokenOnce;
+    /**
+     * 回传体里的地址（工作副本自检的 origin / pushUrl）脱敏：只剥「凭据段」，其余原样保留。
+     *
+     * 为什么不整串换占位符：状态面板要显示「工作副本现在指向哪个远端」，用户靠 host/path 判断是否
+     * 已跟随配置。为什么不一律剥 userinfo：`ssh://git@host` 里的 `git` 是 ssh 登录名（标准写法），
+     * 剥掉会让用户认不出自己的远端 —— 与 validateRepoUrl 的口径保持一致（只有 password 位是凭据）。
+     */
+    private bareUrl;
     /** 错误/日志脱敏：token（原文与 URL 编码两种形态）与 repoUrl 一律替换 */
     private mask;
     /**

package/lib/sync/git/git-transport.js

@@ -26,6 +26,7 @@ import { createSnapshotFs, joinFs } from '../fs.js';
 import { readSnapshotFromDir, SNAPSHOT_BLOB_REFS_SUFFIX, SNAPSHOT_KEEP_CONTENT, SNAPSHOT_KEEP_FILE, SNAPSHOT_MANIFEST_FILE, writeSnapshotToDir } from '../layout.js';
 import { BLOB_SECTIONS, gcBlobs, referencedBlobHashes } from '../blob-store.js';
 import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.js';
+import { classifyRepoUrl, isPrivateRepoHost } from '../sync-config.js';
 import { classifyNetworkErrorText, computeSnapshotMeta, DEFAULT_SYNC_TIMEOUT_MS, isEncryptedSections, SyncTransportError, withSyncRetry, } from '../transport.js';
 import { parseJsonSafe } from '../../utils/json.js';
 import { atomicWriteFile } from '../../utils/atomic-write.js';
@@ -111,6 +112,19 @@ const SYNC_ROOT_DIRS = [...ADOPT_ROOT_ALLOW];
  */
 const NETWORK_SUBCOMMANDS = new Set(['clone', 'fetch', 'push', 'ls-remote', 'pull']);
 const LOW_SPEED_ARGS = ['-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 = ['-c', 'protocol.ext.allow=never'];
+/** 网络仓库额外禁 file 传输（本地目录仓库是显式支持的用法，不能一刀切禁掉）。 */
+const FILE_PROTOCOL_GUARD_ARGS = ['-c', 'protocol.file.allow=never'];
+/** 报错/日志里回显的地址占位符：不带真实 repoUrl（脱敏由上层的 mask() 负责）。 */
+const REPO_URL_PLACEHOLDER = '[REPO_URL]';
 const DEFAULT_AUTHOR = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
@@ -270,6 +284,8 @@ export class GitTransport {
      */
     readErrors = [];
     msg;
+    /** repoUrl 是否为网络地址（本地目录仓库 == false）：决定要不要额外禁 file 传输（SEC-12）。 */
+    networkRepo;
     constructor(options) {
         if (typeof options.repoUrl !== 'string' || options.repoUrl.length === 0) {
             throw new GitTransportError(zhMsg('sync.git.repoUrlRequired'));
@@ -282,6 +298,16 @@ export class GitTransport {
             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,
@@ -494,12 +520,12 @@ export class GitTransport {
     async checkIsPrivate() {
         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;
@@ -618,7 +644,7 @@ export class GitTransport {
     async cloneIntoWorkDir() {
         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)) {
@@ -627,7 +653,7 @@ export class GitTransport {
             }
             // 老 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();
@@ -697,16 +723,16 @@ export class GitTransport {
         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]);
         }
     }
     /**
@@ -805,8 +831,9 @@ export class GitTransport {
         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,
@@ -1018,6 +1045,10 @@ export class GitTransport {
         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 = [];
         let token = null;
         let cleanup = null;
@@ -1037,7 +1068,7 @@ export class GitTransport {
         // 而目录里原本就有别的内容时宁可放弃重试，也绝不删用户文件。
         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 禁执行应用
@@ -1048,7 +1079,7 @@ export class GitTransport {
                 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) {
@@ -1061,7 +1092,9 @@ export class GitTransport {
                 throw err;
             // 注入的 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) }), { ...classifyNetworkErrorText(detail), cause: err });
+            throw new GitTransportError(
+            // 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 {
             if (cleanup)
@@ -1092,7 +1125,7 @@ export class GitTransport {
                 ? 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);
@@ -1140,7 +1173,8 @@ export class GitTransport {
             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 }));
         }
     }
     /** 读取一次 token（错误消息脱敏用）；非 http(s) 场景返回空 */
@@ -1154,6 +1188,30 @@ export class GitTransport {
             return null;
         }
     }
+    /**
+     * 回传体里的地址（工作副本自检的 origin / pushUrl）脱敏：只剥「凭据段」，其余原样保留。
+     *
+     * 为什么不整串换占位符：状态面板要显示「工作副本现在指向哪个远端」，用户靠 host/path 判断是否
+     * 已跟随配置。为什么不一律剥 userinfo：`ssh://git@host` 里的 `git` 是 ssh 登录名（标准写法），
+     * 剥掉会让用户认不出自己的远端 —— 与 validateRepoUrl 的口径保持一致（只有 password 位是凭据）。
+     */
+    bareUrl(url) {
+        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 一律替换 */
     mask(text, token) {
         let out = text.split(this.o.repoUrl).join('[REPO_URL]');

package/lib/sync/merge-preview-text.d.ts

@@ -0,0 +1,11 @@
+/** 单侧预览文本上限（2 KiB **字符**预算）：超出截断并追加省略号。 */
+export declare const MERGE_PREVIEW_TEXT_LIMIT = 2048;
+/**
+ * 预览文本统一出口：先 redact（敏感值绝不回传浏览器），再截断到 2 KiB。
+ *
+ * 顺序恒为「先 redact 再截断」：反过来会把跨边界的敏感值切成半个形状，让脱敏匹配不到它
+ * （等于把秘密截一半发出去）。redact 之后的剩余文本已不含秘密形状，截断才安全。
+ */
+export declare function finalizePreviewText(text: string): string;
+/** 把任意冲突侧值转成**可读字符串**；二进制只回传形状与字节数，绝不回传原始值对象。 */
+export declare function previewTextOf(value: unknown): string;

package/lib/sync/merge-preview-text.js

@@ -0,0 +1,38 @@
+import { redact } from '../security/redaction.js';
+/** 单侧预览文本上限（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) {
+    const masked = redact(text);
+    return masked.length > MERGE_PREVIEW_TEXT_LIMIT ? `${masked.slice(0, MERGE_PREVIEW_TEXT_LIMIT)}…` : masked;
+}
+/** 把任意冲突侧值转成**可读字符串**；二进制只回传形状与字节数，绝不回传原始值对象。 */
+export function previewTextOf(value) {
+    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));
+    }
+}
+//# sourceMappingURL=merge-preview-text.js.map

package/lib/sync/s3/s3-transport.d.ts

@@ -1,4 +1,5 @@
 import type { MsgFunc } from '../../core/msg-types.ts';
+import type { GcSkipCode } from '../gc-skip.ts';
 import { SyncTransportError } from '../transport.ts';
 import type { SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
 import type { SigV4DialectId } from './sigv4.ts';
@@ -63,6 +64,10 @@ export declare class S3Transport implements SyncTransport {
     readonly type: string;
     private readonly target;
     private readonly o;
+    /** 最近一轮 blob GC 的放弃码（`null` = 跑完或未触发；SYN-04）。 */
+    private gcSkip;
+    /** 最近一轮 blob GC 是否因「无法证明引用集完整」而整体放弃（`null` = 正常跑完），供上层给用户提示。 */
+    get lastGcSkip(): GcSkipCode | null;
     constructor(options: S3TransportOptions);
     /** 解析后的目标（只读；端点/region/寻址风格/方言；**不含任何密钥**）。 */
     get resolvedTarget(): S3Target;
@@ -129,6 +134,8 @@ export declare class S3Transport implements SyncTransport {
     /** 下载后把引用形态还原成文件分区（缺 blob → 硬失败，绝不降级为空分区） */
     private rehydrate;
     /** blob 仓 GC：逐份读仍存在的快照收集引用，删除无人引用且超保护窗的 blob；
-     *  读坏任一份快照 → 本轮直接放弃（宁可留垃圾，不可删在用的） */
+     *  读不坏任何一份快照 → 正常回收，否则本轮整体放弃（宁可留垃圾，不可删在用的）。
+     *  SYN-04（P1）：**404 也放弃本轮** —— 条目在但文件 404 = 拿不到内容 = 无法证明「没人引用」，
+     *  按残集回收会删掉仍在用的 blob（与 WebDAV 同型，口径一致）。 */
     private gcBlobStore;
 }

package/lib/sync/s3/s3-transport.js

@@ -24,6 +24,7 @@
  */
 import { requestOnce } from '../../utils/proxy.js';
 import { parseJsonSafe } from '../../utils/json.js';
+import { GC_SKIP_REFERENCE_MISSING, GC_SKIP_REFERENCE_UNREADABLE, GC_SKIP_SNAPSHOT_UNPARSABLE } from '../gc-skip.js';
 import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.js';
 import { BLOB_SECTIONS, gcBlobs, isBlobRefsSection, isFilesSectionLike, referencedBlobHashes, refsToSection, sectionToBlobRefs, } from '../blob-store.js';
 import { classifyHttpStatus, classifyNetworkErrorText, computeSnapshotMeta, DEFAULT_SYNC_TIMEOUT_MS, isEncryptedSections, sectionsEqual, SyncTransportError, withSyncRetry, } from '../transport.js';
@@ -123,6 +124,12 @@ export class S3Transport {
     type;
     target;
     o;
+    /** 最近一轮 blob GC 的放弃码（`null` = 跑完或未触发；SYN-04）。 */
+    gcSkip = null;
+    /** 最近一轮 blob GC 是否因「无法证明引用集完整」而整体放弃（`null` = 正常跑完），供上层给用户提示。 */
+    get lastGcSkip() {
+        return this.gcSkip;
+    }
     constructor(options) {
         // t79：宿主传进来的 msg（core 目录）**不包含** sync.s3.* 键，直接用会显示裸键名 —— 合并本地目录。
         const msg = composeMsg(options.msg, s3Msg);
@@ -593,24 +600,31 @@ export class S3Transport {
         return { ...snapshot, sections: next };
     }
     /** blob 仓 GC：逐份读仍存在的快照收集引用，删除无人引用且超保护窗的 blob；
-     *  读坏任一份快照 → 本轮直接放弃（宁可留垃圾，不可删在用的） */
+     *  读不坏任何一份快照 → 正常回收，否则本轮整体放弃（宁可留垃圾，不可删在用的）。
+     *  SYN-04（P1）：**404 也放弃本轮** —— 条目在但文件 404 = 拿不到内容 = 无法证明「没人引用」，
+     *  按残集回收会删掉仍在用的 blob（与 WebDAV 同型，口径一致）。 */
     async gcBlobStore(secret, remaining) {
+        this.gcSkip = null;
         const index = await this.readBlobIndex(secret);
         if (Object.keys(index).length === 0)
             return;
         const referenced = new Set();
         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)
+            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;
             try {
                 snap = deserializeSnapshot(await sent.res.text());
             }
             catch {
+                this.gcSkip = GC_SKIP_SNAPSHOT_UNPARSABLE;
                 return;
             }
             const plain = snap.sections;

package/lib/sync/session-tombstones.d.ts

@@ -1,3 +1,5 @@
+import type { SectionData } from '../schema/types.ts';
+import type { SyncSnapshotMeta, SyncTransport } from './transport.ts';
 /** 会话单元 id 前缀（与 SessionsAdapter.unitIdOf 同口径：`sessions:<projectKey>/<sessionId>`）。 */
 export declare const SESSION_UNIT_PREFIX = "sessions:";
 /** 墓碑上限（FIFO 保留最新 N 条）：防止 manifest 无限膨胀（真机会话库 ~660 条，5000 足够宽裕）。 */
@@ -37,3 +39,54 @@ export declare function stripTombstonedUnits(section: unknown, tombstones: reado
 export declare function sessionUnitIdsOfSection(section: unknown): string[];
 /** 内容哈希（用于报告/去重；调用方需要时可对单元清单取指纹）。 */
 export declare function unitSetFingerprint(units: readonly string[]): string;
+/**
+ * 一次远端 list() 的读取结果。
+ *
+ * `metas` 为空**且**无 `reason` 才代表「远端确实为空」；有 reason = 读不到（按「看不到远端」
+ * 处理，调用方告警后继续，绝不把它当成「远端没东西」而误判）。
+ */
+export interface RemoteSnapshotIndex {
+    metas: SyncSnapshotMeta[];
+    reason?: string;
+}
+/** 读一次远端快照索引（只读、零写入）。push 的「是否被推进」判定与墓碑继承共用这一份。 */
+export declare function listRemoteSnapshotIndex(transport: Pick<SyncTransport, 'list'>): Promise<RemoteSnapshotIndex>;
+/**
+ * 远端最新快照携带的会话删除墓碑（去重、去空、保序）。
+ *
+ * 只取**最新一份**：manifest.deletedSessions 是累积清单（见文件头），旧快照的墓碑必然被后续
+ * 快照包含；把整段历史并起来只会让「已经在别处撤销的墓碑」复活。
+ * 远端为空 / 老快照缺字段 → 空数组（行为与改造前逐字一致：不继承任何墓碑）。
+ */
+export declare function remoteTombstonesOf(metas: readonly SyncSnapshotMeta[]): string[];
+/** 一次 push 的会话簿记结果（manifest / baseline / 告警共用这一份）。 */
+export interface SessionBookkeepingResult {
+    /** false = 本次没有可用的会话枚举（没推 sessions / 适配器不支持 / 枚举失败或为空） */
+    tracked: boolean;
+    sessionUnits: string[];
+    tombstones: string[];
+    /** 本次**新**发现的删除（之前推过、这次本机没了） */
+    deletedNow: string[];
+    /** 从远端继承来的墓碑条数（本机此前没有、且本机也没有实体） */
+    inherited: number;
+}
+/**
+ * 墓碑集合的唯一计算点（本机删除 + 远端继承合进同一条累积链）。
+ *
+ * 去重、FIFO 上限、以及「本机还有实体 ⇒ 撤销墓碑」这条不变量对继承来的墓碑同样适用：
+ * 另一台设备删了、本机仍有 → 用户在本机显然没删，绝不把它记成本机删除。
+ */
+export declare function planSessionBookkeeping(args: {
+    previousUnits: readonly string[];
+    previousTombstones: readonly string[];
+    localUnits: readonly string[];
+    exportedSessions: SectionData | undefined;
+    remoteTombstones: readonly string[];
+}): Omit<SessionBookkeepingResult, 'tracked'>;
+/** 按墓碑剔除**将要导入**的会话（旧快照不得复活已删除的对话）。只动载荷，不动本机数据。 */
+export declare function stripTombstonedSessionsInPlace<P extends {
+    manifest: {
+        deletedSessions?: readonly string[];
+    };
+    sections: unknown;
+}>(snapshot: P): string[];

package/lib/sync/session-tombstones.js

@@ -18,6 +18,7 @@
  *    本次不实现（保留信息可见，不代用户删数据）。
  */
 import { sha256Hex } from '../utils/hashing.js';
+import { isEncryptedSections } from './transport.js';
 /** 会话单元 id 前缀（与 SessionsAdapter.unitIdOf 同口径：`sessions:<projectKey>/<sessionId>`）。 */
 export const SESSION_UNIT_PREFIX = 'sessions:';
 /** 墓碑上限（FIFO 保留最新 N 条）：防止 manifest 无限膨胀（真机会话库 ~660 条，5000 足够宽裕）。 */
@@ -122,4 +123,55 @@ export function sessionUnitIdsOfSection(section) {
 export function unitSetFingerprint(units) {
     return sha256Hex([...units].sort().join('\n'));
 }
+/** 读一次远端快照索引（只读、零写入）。push 的「是否被推进」判定与墓碑继承共用这一份。 */
+export async function listRemoteSnapshotIndex(transport) {
+    try {
+        return { metas: await transport.list() };
+    }
+    catch (error) {
+        return { metas: [], reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * 远端最新快照携带的会话删除墓碑（去重、去空、保序）。
+ *
+ * 只取**最新一份**：manifest.deletedSessions 是累积清单（见文件头），旧快照的墓碑必然被后续
+ * 快照包含；把整段历史并起来只会让「已经在别处撤销的墓碑」复活。
+ * 远端为空 / 老快照缺字段 → 空数组（行为与改造前逐字一致：不继承任何墓碑）。
+ */
+export function remoteTombstonesOf(metas) {
+    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 !== ''))];
+}
+/**
+ * 墓碑集合的唯一计算点（本机删除 + 远端继承合进同一条累积链）。
+ *
+ * 去重、FIFO 上限、以及「本机还有实体 ⇒ 撤销墓碑」这条不变量对继承来的墓碑同样适用：
+ * 另一台设备删了、本机仍有 → 用户在本机显然没删，绝不把它记成本机删除。
+ */
+export function planSessionBookkeeping(args) {
+    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(snapshot) {
+    const tombstones = snapshot.manifest.deletedSessions ?? [];
+    if (tombstones.length === 0 || isEncryptedSections(snapshot.sections))
+        return [];
+    const plain = snapshot.sections;
+    const stripped = stripTombstonedUnits(plain['sessions'], tombstones);
+    if (stripped.removed.length === 0)
+        return [];
+    plain['sessions'] = stripped.section;
+    return stripped.removed;
+}
 //# sourceMappingURL=session-tombstones.js.map

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

@@ -98,18 +98,21 @@ export declare function isGistConfig(cfg: SyncConfig): cfg is Extract<SyncConfig
  * 读取同步通道配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
  * 兼容旧文件：缺 schemaVersion 字段视为 v1（git 通道）。
  * 恒返回 schemaVersion=2 的规范形态（v1 读取时归一为 git）。
+ *
+ * `issues` 可选：传数组时，被丢弃的 git repoUrl（白名单校验不通过）以结构化成因追加进去，
+ * 供 UI/日志如实呈现（不静默吞掉）。
  */
-export declare function readSyncConfig(dir: string): Promise<SyncConfig | null>;
+export declare function readSyncConfig(dir: string, issues?: SyncConfigIssue[]): Promise<SyncConfig | null>;
 /**
  * 读取完整的双命名空间配置（供 status 路由回填另一通道的 repoUrl/url）。
  * 文件不存在/损坏/无任何通道配置 → null（视为未配置）。
  */
-export declare function readFullSyncConfig(dir: string): Promise<FullSyncConfig | null>;
+export declare function readFullSyncConfig(dir: string, issues?: SyncConfigIssue[]): Promise<FullSyncConfig | null>;
 /**
  * 读取指定通道的同步通道配置（供自动同步调度器按通道运行）。
  * 从完整双命名空间配置取对应通道构造可辨识联合 SyncConfig；该通道未配置 → null。
  */
-export declare function readSyncConfigFor(dir: string, channel: SyncTransportType): Promise<SyncConfig | null>;
+export declare function readSyncConfigFor(dir: string, channel: SyncTransportType, issues?: SyncConfigIssue[]): Promise<SyncConfig | null>;
 /**
  * 保存同步通道配置（自动创建目录；恒写 schemaVersion=3 双命名空间）。
  * - 写入当前通道的命名空间（git/webdav）；
@@ -142,10 +145,57 @@ export interface ClearSyncChannelResult {
  * 它们分别住在 DSH credentials 与 autosync.json，由路由层显式清除（本模块只碰 sync-config.json）。
  */
 export declare function clearSyncChannel(dir: string, channel: SyncTransportType): Promise<ClearSyncChannelResult>;
+/** repoUrl 形态：网络地址（http/https/ssh，含 scp 式）或本机路径 */
+export type RepoUrlKind = 'http' | 'https' | 'ssh' | 'local';
+/**
+ * 已落盘 repoUrl 校验失败的**结构化**结果（SEC-01 读侧）。
+ * 读取侧不能只是返回 null：调用方要能如实告诉用户「你的配置被丢弃了，原因是地址不合法」。
+ */
+export interface SyncConfigIssue {
+    code: 'repo-url-invalid';
+    channel: SyncTransportType;
+    message: string;
+}
+/**
+ * repoUrl 形态分类；null = 不认识的形态。
+ *
+ * 为什么要分类而不是只做正则：git 对同一个「地址」支持 http(s)、ssh、scp 式与本机路径，
+ * 而这三类的安全含义完全不同（网络地址要防 SSRF，本机路径要防 argv 注入）。先判形态，
+ * 再按形态分别收紧，比一堆互相打架的正则清楚。
+ */
+export declare function classifyRepoUrl(repoUrl: string): {
+    kind: RepoUrlKind;
+    host: string;
+} | null;
+/**
+ * 环回 / 私网 / 链路本地 / 未指定地址（含云元数据 169.254.169.254）判定。
+ * SEC-03：这类地址让「客户端」去访问内网或本机端口，等于给 SSRF 开一扇门。
+ *
+ * **已知行为变更（有意，非副作用）**：SEC-02/03 之前 `https://192.168.1.10/…`、`http://127.0.0.1:3000/…`、
+ * `http://nas.local/…` 这类地址可以被接受。收紧后一律拒绝 —— 代价是「拿家里 NAS / 局域网 git 服务器
+ * 当同步目标」这条路走不通，收益是「包里的 repoUrl 无法把家目录配置推给内网监听者或云元数据端点」。
+ * 取舍判据：本插件的同步目标是「用户自己的远端仓库」，公网 http(s)/ssh 已覆盖该用途；本机目录仓库
+ * 仍走 `local` 分支（不由本函数判定）。真要支持内网目标，应做成显式开关 + 用户逐目标确认，
+ * 不能靠「地址字符串看起来像内网就放行」——那正是攻击者可控的判据。
+ */
+export declare function isPrivateRepoHost(host: string): boolean;
+/**
+ * 文案里回显地址用：剥掉 userinfo（token 可能就藏在这一段），host/path 原样保留。
+ *
+ * 为什么不整串换成 `[REPO_URL]` 占位符：这里拒绝的是**用户自己刚填的**地址，他需要认出
+ * 「被拒的是哪一个」才能改；剥掉 `user:pass@` 之后剩下的部分正是修复所需的定位信息。
+ * 为什么解析失败也要剥：`https://user:tok@` 这类半截地址 `new URL` 会抛，但前缀照样是凭据。
+ */
+export declare function sanitizeRepoUrlForMessage(url: string): string;
 /**
  * 仓库地址合法性校验（返回错误消息；null = 合法）。
- * 安全约束：token 永不拼入 repoUrl —— http(s) 地址带 userinfo（username[:password]@）直接拒绝，
- * 引导用户把 token 放凭据字段（DSH credentials），避免 token 经 URL 泄漏进 git 历史/日志。
+ *
+ * 白名单口径（SEC-02/03/12，写入侧与读取侧共用同一份实现）：
+ * - 只认 http(s)/ssh/scp 式网络地址与本机路径；file://、ext::、ftp://、git:// 一律拒绝；
+ * - 整串以 '-' 开头拒绝（git argv 位置参数以 '-' 开头会被当选项，可执行任意命令）；
+ * - 网络地址拒绝环回/私网/链路本地主机（SSRF）—— 文案单独一条（sync.configPrivateHost），
+ *   不能复用「无法解析」：用户看到「解析不了」只会反复改写法，实际原因是地址指向内网；
+ * - 带 scheme 的地址一律拒绝 userinfo（username[:password]@）—— token 只许放凭据字段。
  */
 export declare function validateRepoUrl(repoUrl: string, msg?: MsgFunc): string | null;
 /**