dsh-config-manager 0.2.3 → 0.3.0

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;
 /**

package/lib/sync/sync-config.js

@@ -113,12 +113,26 @@ function parseV2WebDavNamespace(ns) {
         webdav.username = o['username'];
     return webdav;
 }
+/**
+ * 已落盘 repoUrl 的读取侧校验（SEC-01）：与写入侧同一份 validateRepoUrl。
+ * 不合法 → 记一条明确 issue 并让调用方丢弃该配置；绝不把可疑地址继续交给凭据注入与 git 子进程。
+ */
+function acceptPersistedRepoUrl(repoUrl, issues) {
+    const err = validateRepoUrl(repoUrl);
+    if (err === null)
+        return true;
+    issues?.push({ code: 'repo-url-invalid', channel: 'git', message: err });
+    return false;
+}
 /**
  * 读取同步通道配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
  * 兼容旧文件：缺 schemaVersion 字段视为 v1（git 通道）。
  * 恒返回 schemaVersion=2 的规范形态（v1 读取时归一为 git）。
+ *
+ * `issues` 可选：传数组时，被丢弃的 git repoUrl（白名单校验不通过）以结构化成因追加进去，
+ * 供 UI/日志如实呈现（不静默吞掉）。
  */
-export async function readSyncConfig(dir) {
+export async function readSyncConfig(dir, issues) {
     const file = path.join(dir, SYNC_CONFIG_FILE);
     let raw;
     try {
@@ -149,6 +163,8 @@ export async function readSyncConfig(dir) {
         const git = parseV1Git(obj);
         if (git === null)
             return null;
+        if (!acceptPersistedRepoUrl(git.repoUrl, issues))
+            return null;
         return { schemaVersion: 2, transport: 'git', git };
     }
     // v2 / v3：顶层 transport 选择（v3 双命名空间并存，按 transport 返回对应通道）
@@ -160,6 +176,8 @@ export async function readSyncConfig(dir) {
         const git = parseV2GitNamespace(obj['git']);
         if (git === null)
             return null;
+        if (!acceptPersistedRepoUrl(git.repoUrl, issues))
+            return null;
         return { schemaVersion: 2, transport: 'git', git };
     }
     if (transport === 'webdav') {
@@ -219,9 +237,14 @@ function readBothNamespaces(file) {
  * 读取完整的双命名空间配置（供 status 路由回填另一通道的 repoUrl/url）。
  * 文件不存在/损坏/无任何通道配置 → null（视为未配置）。
  */
-export async function readFullSyncConfig(dir) {
+export async function readFullSyncConfig(dir, issues) {
     const file = path.join(dir, SYNC_CONFIG_FILE);
     const both = await readBothNamespaces(file);
+    // SEC-01/03 读侧：已落盘的 git repoUrl 过同一份白名单校验；不合法就当作没配 git 通道
+    // （自动同步/凭据注入都从这里取通道配置，绝不能让可疑地址继续往下走）
+    if (both.git !== undefined && !acceptPersistedRepoUrl(both.git.repoUrl, issues)) {
+        delete both.git;
+    }
     // 云端点通道的配置不在 sync-config.json（见 sync-cloud-config.json）；这里一并对齐成完整视图
     const s3 = await readS3ChannelConfig(dir);
     const gist = await readGistChannelConfig(dir);
@@ -253,8 +276,8 @@ export async function readFullSyncConfig(dir) {
  * 读取指定通道的同步通道配置（供自动同步调度器按通道运行）。
  * 从完整双命名空间配置取对应通道构造可辨识联合 SyncConfig；该通道未配置 → null。
  */
-export async function readSyncConfigFor(dir, channel) {
-    const full = await readFullSyncConfig(dir);
+export async function readSyncConfigFor(dir, channel, issues) {
+    const full = await readFullSyncConfig(dir, issues);
     if (full === null)
         return null;
     switch (channel) {
@@ -372,10 +395,139 @@ export async function clearSyncChannel(dir, channel) {
     await writeSyncConfigTransport(dir, transport);
     return { removed: true, hasRemaining: true, transport };
 }
+/**
+ * repoUrl 形态分类；null = 不认识的形态。
+ *
+ * 为什么要分类而不是只做正则：git 对同一个「地址」支持 http(s)、ssh、scp 式与本机路径，
+ * 而这三类的安全含义完全不同（网络地址要防 SSRF，本机路径要防 argv 注入）。先判形态，
+ * 再按形态分别收紧，比一堆互相打架的正则清楚。
+ */
+export function classifyRepoUrl(repoUrl) {
+    const url = repoUrl.trim();
+    if (url === '' || /\s/.test(url))
+        return null;
+    // SEC-12：以 '-' 开头的「地址」会被 git 当成选项（--upload-pack=… / -c core.pager=…）
+    if (url.startsWith('-'))
+        return null;
+    // 'ext::sh -c …' 一类命令协议（SCM 协议语法里 scheme 与地址之间是 '::'）
+    if (url.includes('::'))
+        return null;
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(url);
+    if (scheme !== null) {
+        const name = scheme[1].toLowerCase();
+        if (name !== 'http' && name !== 'https' && name !== 'ssh')
+            return null;
+        // 'https:///r.git' 这类空 authority 会被 URL 解析器「跳过斜杠」后当成主机 r.git —— 必须先拦
+        const rest = url.slice(scheme[0].length);
+        if (rest === '' || rest.startsWith('/') || rest.startsWith('\\'))
+            return null;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return null;
+        }
+        if (parsed.hostname === '')
+            return null;
+        return { kind: name, host: parsed.hostname };
+    }
+    // scp 式（git@github.com:user/repo.git）：只有 user@host:path 才算网络地址
+    const scp = /^[^\s/@:]+@([^\s/:]+):(.+)$/.exec(url);
+    if (scp !== null)
+        return { kind: 'ssh', host: scp[1] };
+    // 其余按本机路径处理（相对 ../bare、绝对 /home/u/r.git、盘符 D:/repos/bare）
+    return { kind: 'local', host: '' };
+}
+/** 四段点分且每段 0-255 → IPv4 字面量；否则 null（域名里的数字段不算 IP） */
+function parseIpv4(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return null;
+    const nums = [];
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const n = Number(part);
+        if (n > 255)
+            return null;
+        nums.push(n);
+    }
+    return [nums[0], nums[1], nums[2], nums[3]];
+}
+/**
+ * 环回 / 私网 / 链路本地 / 未指定地址（含云元数据 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 function isPrivateRepoHost(host) {
+    const h = host.trim().toLowerCase().replace(/^\[/, '').replace(/\]$/, '').replace(/\.$/, '');
+    if (h === '')
+        return true;
+    if (h === 'localhost' || h.endsWith('.localhost'))
+        return true;
+    const v4 = parseIpv4(h);
+    if (v4 !== null) {
+        const [a, b] = v4;
+        return a === 0 || a === 127 || a === 10
+            || (a === 172 && b >= 16 && b <= 31)
+            || (a === 192 && b === 168)
+            || (a === 169 && b === 254);
+    }
+    if (!h.includes(':'))
+        return false;
+    if (h === '::1' || h === '::')
+        return true;
+    if (/^f[cd][0-9a-f]{2}:/.test(h))
+        return true; // fc00::/7 唯一本地
+    if (/^fe[89ab][0-9a-f]?:/.test(h))
+        return true; // fe80::/10 链路本地
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(h);
+    if (mapped !== null)
+        return isPrivateRepoHost(mapped[1]);
+    return false;
+}
+/**
+ * 文案里回显地址用：剥掉 userinfo（token 可能就藏在这一段），host/path 原样保留。
+ *
+ * 为什么不整串换成 `[REPO_URL]` 占位符：这里拒绝的是**用户自己刚填的**地址，他需要认出
+ * 「被拒的是哪一个」才能改；剥掉 `user:pass@` 之后剩下的部分正是修复所需的定位信息。
+ * 为什么解析失败也要剥：`https://user:tok@` 这类半截地址 `new URL` 会抛，但前缀照样是凭据。
+ */
+export function sanitizeRepoUrlForMessage(url) {
+    const raw = url.trim();
+    try {
+        const parsed = new URL(raw);
+        if (parsed.username === '' && parsed.password === '')
+            return raw;
+        parsed.username = '';
+        parsed.password = '';
+        return parsed.toString();
+    }
+    catch {
+        // 只有「残缺的带 scheme 地址」（`https://user:tok@`，`new URL` 会抛但前缀就是凭据）需要剥。
+        // 无 scheme 的 scp 式（`git@host:path`）里 `git` 是 ssh 登录名、不是凭据 → 原样返回，
+        // 免得用户看到一条认不出是哪个远端的报错。
+        if (!/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw))
+            return raw;
+        return raw.replace(/^([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^/@\s]*@/, (_m, scheme) => scheme ?? '');
+    }
+}
 /**
  * 仓库地址合法性校验（返回错误消息；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 function validateRepoUrl(repoUrl, msg = zhMsg) {
     if (typeof repoUrl !== 'string' || repoUrl.trim() === '') {
@@ -385,15 +537,36 @@ export function validateRepoUrl(repoUrl, msg = zhMsg) {
     if (/\s/.test(url)) {
         return msg('sync.configWhitespace');
     }
-    if (/^https?:\/\//i.test(url)) {
-        let parsed;
-        try {
-            parsed = new URL(url);
-        }
-        catch {
-            return msg('sync.configUnparseable', { url });
-        }
-        if (parsed.username !== '' || parsed.password !== '') {
+    // 回显一律脱敏：错误文案会进日志、进接口响应、进 issue 截图
+    const echo = sanitizeRepoUrlForMessage(url);
+    const shape = classifyRepoUrl(url);
+    if (shape === null) {
+        return msg('sync.configUnparseable', { url: echo });
+    }
+    if (shape.kind === 'local')
+        return null;
+    if (isPrivateRepoHost(shape.host)) {
+        return msg('sync.configPrivateHost', { url: echo });
+    }
+    // userinfo 检查与 scheme 无关（RV1-F7）：原实现只在 http/https 分支内查，于是
+    // `ssh://user:tok@host/r.git` 能过白名单，token 照样进 argv 与 sync-config.json。
+    // 口径（按「这一段是不是凭据」区分，而不是按 scheme 区分）：
+    // - password 位：任何带 scheme 的地址都拒 —— 那是可粘贴的 secret；
+    // - http/https 的 username：Basic 认证的用户名与口令等同，一并拒（保持既有行为）；
+    // - ssh 的 username：就是 ssh 登录名（`ssh://git@host`、`ssh://deploy@host` 是标准写法），
+    //   ssh 认证只认密钥/agent，用户名不具凭据效力，因此放行 —— 拒掉会杀掉合法用法。
+    // scp 式（git@host:path）无 scheme、`new URL` 解析不了，本就不进这条判定。
+    let parsed = null;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed !== null) {
+        const hasPassword = parsed.password !== '';
+        const hasBasicUser = parsed.username !== '' && (shape.kind === 'http' || shape.kind === 'https');
+        if (hasPassword || hasBasicUser) {
             return msg('sync.configUserinfo');
         }
     }

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

@@ -326,6 +326,14 @@ export type MergeResolution = {
 export type ApplyMergeResolutionsReport = ApplyReport & {
     pendingConflicts: SectionId[];
 };
+/**
+ * 删除远端快照的结果（F3：显式删除路径此前对「本轮 blob GC 被放弃」完全静默）。
+ * `warnings` 与 push 报告同风格（空数组 = 本轮什么都没被放弃）：快照已按用户意图删除，
+ * 「孤儿 blob 没回收」不是失败（下一轮 GC 还会再试），所以进 warnings、不进 ok。
+ */
+export interface DeleteSnapshotResult {
+    warnings: string[];
+}
 export declare class SyncEngine {
     private readonly ctx;
     private readonly transport;
@@ -489,12 +497,6 @@ export declare class SyncEngine {
      * 本机枚举失败或为空。用「读不到」覆盖成「全删了」会一次性标错几百条墓碑，绝不猜。
      */
     private computeSessionBookkeeping;
-    /**
-     * P1-5：按远端墓碑剔除**将要导入**的会话（旧快照不得复活已删除的对话）。
-     * 只动载荷，不动本机已有数据 —— 墓碑不代用户删除本机文件（那是不可回滚的用户动作）。
-     * @returns 被剔除的会话单元 id（调用方据此出可见报告，绝不静默）
-     */
-    private stripTombstonedSessions;
     /**
      * 裁剪远端快照：调用 transport.list() 获取全部快照（按 createdAt 升序），
      * 按 retentionPolicyProvider() 给出的 GFS 策略（最近 N / 每月一份 / 每年一份）
@@ -523,6 +525,7 @@ export declare class SyncEngine {
      *  - 其余：远端最新快照 id !== lastSnapshotId ⇒ 远端被推进（或本机基线已被裁剪）→ 拦。
      *    两种情况都**无法安全断言「远端没变」**，保守拒绝并给出 force 出口。
      *  - list() 抛错 → 返回 reason（调用方按原样继续并告警），绝不把「读不到」当成「没变」。
+     *  - SYN-02：index 可由 push() 传入（同一轮只列一次远端），缺省自己 list（其它调用点行为不变）。
      */
     private remoteAdvancedCheck;
     /**
@@ -562,8 +565,19 @@ export declare class SyncEngine {
      *  - **与保留策略裁剪共用同一条 `transport.delete`**（两条通道的删除语义只有一份实现），
      *    区别只在「谁点名」：这里是用户显式指定的 id，pruneRemoteSnapshots 由 RetentionPolicy 挑；
      *  - **不存在视为成功**（SyncTransport 契约），所以重复点删除 / 已被裁剪掉都不会报错。
+     *
+     * F3：通道侧的 blob GC 可能「放弃本轮」（SYN-04：引用快照 404 / 读不出 ⇒ 证明不了没人引用）。
+     * 放弃不是删除失败，但**必须可见**（否则孤儿 blob 无人知晓地一直堆）⇒ 放弃码用与 push 报告
+     * 同一条 `gcSkipWarning` 渲染进返回体的 warnings。
+     */
+    deleteSnapshot(id: string): Promise<DeleteSnapshotResult>;
+    /**
+     * SYN-04b：通道最近一轮 GC 的放弃码（无则 null）。
+     *
+     * 保留为 public 只读出口（不删）：属本类已发布的可见 API，路由/诊断不跑删除流程也能读到通道能力；
+     * 引擎内已由 deleteSnapshot 消费（放弃码 → warnings），不再是死方法。读不到（通道没这能力）= null。
      */
-    deleteSnapshot(id: string): Promise<void>;
+    lastGcSkipCode(): string | null;
     /** 列出远端已有快照（按 createdAt 升序）—— 供「选择历史快照」下拉。 */
     listSnapshots(): Promise<SyncSnapshotMeta[]>;
     /**