@logictan/dsh-config-manager 0.1.60

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

@@ -0,0 +1,100 @@
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from '../transport.ts';
+import type { MsgFunc } from '../../core/messages.ts';
+/** git 命令执行结果（code ≠ 0 = git 命令失败/退出非零） */
+export interface GitExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+/** 可注入的 git 执行器（测试 mock 用）；默认实现 = child_process.execFile promise 封装 */
+export type GitExecFn = (cmd: string, args: string[], opts: {
+    cwd?: string;
+    timeoutMs?: number;
+}) => Promise<GitExecResult>;
+/** 凭据提供者：token 只从这里读取，绝不在任何地方持久化 */
+export interface GitCredentialProvider {
+    getToken(): Promise<string>;
+}
+export interface GitAuthor {
+    name: string;
+    email: string;
+}
+export interface GitTransportOptions {
+    /** 远端私有仓库地址（https/ssh/本地路径）；token 绝不拼入此 URL */
+    repoUrl: string;
+    /** 本地 git 工作副本目录（不存在则创建；已 clone 则复用） */
+    workDir: string;
+    /** token 提供者（http(s) 远端必填；本地/ssh 远端不会被调用） */
+    credentials: GitCredentialProvider;
+    /** 单条 git 命令超时 ms，默认 60000 */
+    timeoutMs?: number;
+    /** 注入 exec（测试 mock 用）；缺省 = execFile 封装 */
+    exec?: GitExecFn;
+    /** 提交作者（写入远端历史），默认 DSH Config Sync <sync@dsh.local> */
+    author?: GitAuthor;
+    /** credential 用户名（GitHub PAT 用 oauth2），默认 'oauth2' */
+    credentialUsername?: string;
+    /** 消息翻译器（缺省 zh） */
+    msg?: MsgFunc;
+}
+export declare class GitTransportError extends Error {
+    constructor(message: string);
+}
+/** 实现 SyncTransport 的 git 通道。所有操作前 ensureRepo() 保证工作副本就绪，网络命令带凭据。 */
+export declare class GitTransport implements SyncTransport {
+    readonly type = "git";
+    private readonly o;
+    private repoReady;
+    private privateHint;
+    private readonly msg;
+    constructor(options: GitTransportOptions);
+    /** 最近一次 checkIsPrivate() 的结果；null = 尚未检查 */
+    get isPrivateHint(): boolean | null;
+    /** 列出远端已有快照（按 createdAt 升序）。读取工作副本 snapshots/（明文散文件）
+     *  与 snapshots-encrypted/（密文单文件）两个目录（先 pull 同步远端）。 */
+    list(): Promise<SyncSnapshotMeta[]>;
+    /**
+     * 上传快照：写散文件目录（明文）或密文单文件（加密）→ add → commit → push；
+     * 同 id 覆盖；内容无变化时幂等（不产生 commit）。
+     * 双形态互斥：同 id 从一种形态切到另一种时先清掉旧形态残留，保证工作副本/远端布局自洽。
+     */
+    upload(snapshot: SyncSnapshot): Promise<SyncSnapshotMeta>;
+    /** 下载快照完整载荷。明文 → 读回散文件目录；加密 → 读回密文单文件。不存在的 id 必须抛错（契约）。 */
+    download(id: string): Promise<SyncSnapshot>;
+    /** 删除远端快照（明文散文件目录或密文单文件；不存在视为成功，契约）。 */
+    delete(id: string): Promise<void>;
+    /**
+     * 私有仓库可见性探测（结果缓存于 isPrivateHint）：
+     * 匿名 ls-remote 成功 → 公开；匿名失败 + 凭据探测成功 → 私有；两者都失败 → 抛错。
+     * UI 层可用 isPrivateHint 提示「私有仓库推荐」；公开仓库也可用（内容需自行评估）。
+     */
+    checkIsPrivate(): Promise<boolean>;
+    private ensureRepo;
+    /** pull --ff-only 同步远端；无本地提交（全新仓库）或无 upstream 时静默跳过 */
+    private pullFromRemote;
+    /** 执行 git 命令；withCredential=true 时注入 credential helper（token 不进 argv），失败时错误消息脱敏 */
+    private runGit;
+    /**
+     * 为网络命令构造 credential helper 参数：
+     * 仅 http(s) 远端需要 token；本地路径 / ssh 走 git 原生认证（密钥），不调用 provider。
+     * token 写入 os.tmpdir() 下临时 store 文件（权限 0600），命令后立即删除 —— 永不落工作副本/远端。
+     */
+    private buildCredentialArgs;
+    /** 从 repoUrl 提取 credential 匹配用的 host[:port] */
+    private repoHost;
+    /** 读取一次 token（错误消息脱敏用）；非 http(s) 场景返回空 */
+    private readTokenOnce;
+    /** 错误/日志脱敏：token（原文与 URL 编码两种形态）与 repoUrl 一律替换 */
+    private mask;
+    private assertSafeId;
+    private snapshotDir;
+    private snapshotsDir;
+    /** 加密快照密文单文件目录（<workDir>/snapshots-encrypted/） */
+    private encryptedSnapshotsDir;
+    /** 加密快照密文单文件路径（<id>.json） */
+    private encryptedSnapshotFile;
+    /** 读密文单文件快照（解析失败 → null，调用方跳过，不静默失败整体 list）。 */
+    private readEncryptedSnapshotFile;
+    /** 读快照目录 manifest.json（结构不合法 → null，调用方跳过） */
+    private readDirManifest;
+}

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

@@ -0,0 +1,437 @@
+/**
+ * m-git-channel：Git 私有仓库通道（SyncTransport 的 git 实现）。
+ *
+ * 设计：
+ * - 明文快照以「散文件目录」提交到 git 仓库：工作副本 <workDir>/snapshots/<id>/ 即 t2 layout 布局
+ *   （manifest.json + 平铺 JSON 分区 + 文件类分区目录），每次 sync 一次 commit + push；
+ * - 加密快照（EncryptedSections 密文载荷，无法平铺为明文 JSON 分区）走「密文单文件」布局：
+ *   整个快照 JSON 提交到 <workDir>/snapshots-encrypted/<id>.json（远端已存密文；
+ *   本地工作副本即远端镜像，不产生额外明文审计副本）。
+ * - 命令执行走 node:child_process execFile（promise 封装，数组参数无 shell 注入），
+ *   始终使用系统 PATH 中的 git（固定命令 'git'），可注入 exec 便于测试。
+ * - 认证：token 仅从注入的 credentials provider 读取（每次网络操作时 getToken()），
+ *   经 git credential helper（store --file=<临时文件>）传给 git —— token 不进入 argv、
+ *   不进入 repoUrl、不写入任何同步内容/commit message/日志；临时凭据文件用后即删。
+ * - 私有仓库判定：checkIsPrivate() 先匿名 ls-remote（成功=公开），失败再用凭据探测
+ *   （成功=私有），isPrivateHint 缓存最近结果供 UI 提示（私有仓库为推荐使用场景）。
+ * - 契约：同 id 重复 upload = 覆盖（幂等友好：内容无变化时不产生 commit）；download 不存在抛错；
+ *   delete 不存在视为成功。
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { createSnapshotFs, joinFs } from '../fs.js';
+import { readSnapshotFromDir, SNAPSHOT_KEEP_CONTENT, SNAPSHOT_KEEP_FILE, SNAPSHOT_MANIFEST_FILE, writeSnapshotToDir } from '../layout.js';
+import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.js';
+import { computeSnapshotMeta, isEncryptedSections } from '../transport.js';
+import { parseJsonSafe } from '../../utils/json.js';
+import { atomicWriteFile } from '../../utils/atomic-write.js';
+import { SECTION_FILE_PREFIXES } from '../../schema/config.js';
+import { zhMsg } from '../../core/messages.js';
+const execFileAsync = promisify(execFile);
+export class GitTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitTransportError';
+    }
+}
+const SNAPSHOTS_REL = 'snapshots';
+/** 加密快照的「密文单文件」目录：整个快照 JSON（含密文载荷）以 <id>.json 提交。
+ *  加密快照不写散文件目录（密文无法平铺为明文 JSON 分区；远端已存密文）。 */
+const SNAPSHOTS_ENCRYPTED_REL = 'snapshots-encrypted';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_AUTHOR = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
+const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
+/** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
+const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const defaultExec = async (cmd, args, opts) => {
+    try {
+        const { stdout, stderr } = await execFileAsync(cmd, args, {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs,
+            maxBuffer: 16 * 1024 * 1024,
+            windowsHide: true,
+            encoding: 'utf8',
+        });
+        return { stdout: String(stdout), stderr: String(stderr), code: 0 };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            stdout: String(e.stdout ?? ''),
+            stderr: String(e.stderr ?? (err instanceof Error ? err.message : String(err))),
+            code: typeof e.code === 'number' ? e.code : 1,
+        };
+    }
+};
+/** git config 值里的路径转义：含空白/引号时用引号包裹（Windows 路径转正斜杠） */
+function quoteGitValue(value) {
+    return /[\s"']/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+/** 实现 SyncTransport 的 git 通道。所有操作前 ensureRepo() 保证工作副本就绪，网络命令带凭据。 */
+export class GitTransport {
+    type = 'git';
+    o;
+    repoReady = false;
+    privateHint = null;
+    msg;
+    constructor(options) {
+        if (typeof options.repoUrl !== 'string' || options.repoUrl.length === 0) {
+            throw new GitTransportError(zhMsg('sync.git.repoUrlRequired'));
+        }
+        if (typeof options.workDir !== 'string' || options.workDir.length === 0) {
+            throw new GitTransportError(zhMsg('sync.git.workDirRequired'));
+        }
+        if (options.credentials === null || typeof options.credentials !== 'object'
+            || typeof options.credentials.getToken !== 'function') {
+            throw new GitTransportError(zhMsg('sync.git.credentialsRequired'));
+        }
+        this.msg = options.msg ?? zhMsg;
+        this.o = {
+            repoUrl: options.repoUrl,
+            workDir: options.workDir,
+            credentials: options.credentials,
+            gitBin: 'git',
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            exec: options.exec ?? defaultExec,
+            author: options.author ?? DEFAULT_AUTHOR,
+            credentialUsername: options.credentialUsername ?? DEFAULT_CREDENTIAL_USERNAME,
+        };
+    }
+    /** 最近一次 checkIsPrivate() 的结果；null = 尚未检查 */
+    get isPrivateHint() {
+        return this.privateHint;
+    }
+    /** 列出远端已有快照（按 createdAt 升序）。读取工作副本 snapshots/（明文散文件）
+     *  与 snapshots-encrypted/（密文单文件）两个目录（先 pull 同步远端）。 */
+    async list() {
+        await this.ensureRepo();
+        await this.pullFromRemote();
+        const fsx = createSnapshotFs();
+        const metas = [];
+        // 明文散文件目录
+        const snapsAbs = this.snapshotsDir();
+        const names = await fsx.readdir(snapsAbs);
+        for (const name of names) {
+            if (name === '' || name === '.' || name === '..')
+                continue;
+            const dirAbs = joinFs(snapsAbs, name);
+            if (!(await fsx.isDir(dirAbs)))
+                continue;
+            const m = await this.readDirManifest(dirAbs);
+            if (m === null)
+                continue; // 损坏/不完整 → 跳过（防御工作副本污染，不静默失败整体 list）
+            metas.push({
+                id: m.id,
+                createdAt: m.createdAt,
+                sections: m.sectionHashes,
+                manifest: m.manifest,
+            });
+        }
+        // 密文单文件目录（snapshots-encrypted/<id>.json）：整体 JSON 快照
+        const encAbs = this.encryptedSnapshotsDir();
+        const encNames = await fsx.readdir(encAbs);
+        for (const name of encNames) {
+            if (!name.endsWith('.json'))
+                continue;
+            const id = name.slice(0, -'.json'.length);
+            if (id === '' || id === '.' || id === '..' || id.includes('/') || id.includes('\\'))
+                continue;
+            const snap = await this.readEncryptedSnapshotFile(joinFs(encAbs, name));
+            if (snap === null)
+                continue; // 损坏/解析失败 → 跳过
+            metas.push({ id: snap.id, createdAt: snap.createdAt, sections: {}, manifest: snap.manifest });
+        }
+        metas.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
+        return metas;
+    }
+    /**
+     * 上传快照：写散文件目录（明文）或密文单文件（加密）→ add → commit → push；
+     * 同 id 覆盖；内容无变化时幂等（不产生 commit）。
+     * 双形态互斥：同 id 从一种形态切到另一种时先清掉旧形态残留，保证工作副本/远端布局自洽。
+     */
+    async upload(snapshot) {
+        this.assertSafeId(snapshot.id);
+        await this.ensureRepo();
+        await this.pullFromRemote();
+        const fsx = createSnapshotFs();
+        const encrypted = isEncryptedSections(snapshot.sections);
+        // 覆盖判定：任一种旧形态（散文件目录 / 密文单文件）已存在 → update
+        const existed = await fsx.exists(this.snapshotDir(snapshot.id))
+            || await fsx.exists(this.encryptedSnapshotFile(snapshot.id));
+        let rel;
+        if (encrypted) {
+            // 密文单文件：整个快照 JSON（sections 为 EncryptedSections，纯字符串 JSON 安全）
+            const file = this.encryptedSnapshotFile(snapshot.id);
+            await fsx.remove(file); // 覆盖语义：先删旧文件
+            await fsx.mkdir(this.encryptedSnapshotsDir());
+            await fsx.writeFile(file, new TextEncoder().encode(serializeSnapshot(snapshot)));
+            // 同 id 旧散文件目录残留 → 一并清理（形态切换不残留）
+            await fsx.remove(this.snapshotDir(snapshot.id));
+            rel = `${SNAPSHOTS_ENCRYPTED_REL}/${snapshot.id}.json`;
+        }
+        else {
+            const dir = this.snapshotDir(snapshot.id);
+            if (await fsx.exists(dir))
+                await fsx.remove(dir); // 覆盖语义：先清旧目录，避免残留旧文件
+            await writeSnapshotToDir(snapshot, dir, fsx);
+            // git 不跟踪空目录：为空文件类分区目录写占位文件，保证远端保留目录。
+            // 占位文件不参与 manifest.sectionHashes（基于传入数据计算）；读回时按名+内容过滤。
+            // 否则空分区（如未安装 skills）上传后目录在远端丢失，B 机全新 clone 下载即失败。
+            const plain = snapshot.sections;
+            for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+                const data = plain[sid];
+                if (data === undefined || data.files.length > 0)
+                    continue;
+                // joinFs 只接受两个参数，占位路径拼进 prefix 一起传
+                await fsx.writeFile(joinFs(dir, `${prefix}${SNAPSHOT_KEEP_FILE}`), new TextEncoder().encode(SNAPSHOT_KEEP_CONTENT));
+            }
+            // 同 id 旧密文单文件残留 → 一并清理（形态切换不残留）
+            await fsx.remove(this.encryptedSnapshotFile(snapshot.id));
+            rel = `${SNAPSHOTS_REL}/${snapshot.id}`;
+        }
+        await this.runGit(['add', '--', rel]);
+        const diff = await this.runGit(['diff', '--cached', '--quiet'], { allowNonZero: true });
+        if (diff.code !== 0) {
+            const verb = existed ? 'update' : 'add';
+            await this.runGit(['commit', '-m', `sync: ${verb} snapshot ${snapshot.id}`]);
+            await this.runGit(['push', '-u', 'origin', 'HEAD'], { withCredential: true });
+        }
+        return computeSnapshotMeta(snapshot);
+    }
+    /** 下载快照完整载荷。明文 → 读回散文件目录；加密 → 读回密文单文件。不存在的 id 必须抛错（契约）。 */
+    async download(id) {
+        this.assertSafeId(id);
+        await this.ensureRepo();
+        await this.pullFromRemote();
+        const fsx = createSnapshotFs();
+        // 优先散文件目录（明文布局）；其次密文单文件（加密布局）
+        // missingFileDir='empty'：git 不跟踪空目录 → 目录缺失 = 空文件分区（非损坏；
+        // 提交原子性保证非空目录不会缺失），兼容旧版插件上传的无占位快照
+        if (await fsx.isDir(this.snapshotDir(id))) {
+            return readSnapshotFromDir(this.snapshotDir(id), fsx, { missingFileDir: 'empty' });
+        }
+        const encFile = this.encryptedSnapshotFile(id);
+        if (await fsx.exists(encFile)) {
+            const raw = Buffer.from(await fsx.readFile(encFile)).toString('utf8');
+            try {
+                return deserializeSnapshot(raw);
+            }
+            catch (err) {
+                throw new GitTransportError(this.msg('sync.git.snapshotCorrupt', {
+                    id, dir: encFile, err: this.mask(String(err?.message ?? ''), null),
+                }));
+            }
+        }
+        throw new GitTransportError(this.msg('sync.git.snapshotMissing', { id, dir: this.snapshotDir(id) }));
+    }
+    /** 删除远端快照（明文散文件目录或密文单文件；不存在视为成功，契约）。 */
+    async delete(id) {
+        this.assertSafeId(id);
+        await this.ensureRepo();
+        await this.pullFromRemote();
+        const fsx = createSnapshotFs();
+        const plainDir = this.snapshotDir(id);
+        const encFile = this.encryptedSnapshotFile(id);
+        const plainExists = await fsx.exists(plainDir);
+        const encExists = await fsx.exists(encFile);
+        if (!plainExists && !encExists)
+            return; // 不存在视为成功
+        let rel;
+        if (plainExists) {
+            await fsx.remove(plainDir);
+            rel = `${SNAPSHOTS_REL}/${id}`;
+        }
+        else {
+            await fsx.remove(encFile);
+            rel = `${SNAPSHOTS_ENCRYPTED_REL}/${id}.json`;
+        }
+        await this.runGit(['add', '-A', '--', rel]);
+        const diff = await this.runGit(['diff', '--cached', '--quiet'], { allowNonZero: true });
+        if (diff.code !== 0) {
+            await this.runGit(['commit', '-m', `sync: delete snapshot ${id}`]);
+            await this.runGit(['push', '-u', 'origin', 'HEAD'], { withCredential: true });
+        }
+    }
+    /**
+     * 私有仓库可见性探测（结果缓存于 isPrivateHint）：
+     * 匿名 ls-remote 成功 → 公开；匿名失败 + 凭据探测成功 → 私有；两者都失败 → 抛错。
+     * UI 层可用 isPrivateHint 提示「私有仓库推荐」；公开仓库也可用（内容需自行评估）。
+     */
+    async checkIsPrivate() {
+        if (this.privateHint !== null)
+            return this.privateHint;
+        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 });
+        if (authed.code === 0) {
+            this.privateHint = true;
+            return true;
+        }
+        throw new GitTransportError(this.msg('sync.git.repoUnreachable', { url: this.mask(this.o.repoUrl, null) }));
+    }
+    /* ---------------- 内部实现 ---------------- */
+    async ensureRepo() {
+        if (this.repoReady)
+            return;
+        const fsx = createSnapshotFs();
+        await fsx.mkdir(this.o.workDir); // 不存在则创建
+        if (await fsx.exists(path.join(this.o.workDir, '.git'))) {
+            this.repoReady = true;
+            return;
+        }
+        const entries = await fsx.readdir(this.o.workDir);
+        if (entries.length > 0) {
+            throw new GitTransportError(this.msg('sync.git.workDirNotRepo', { dir: this.o.workDir }));
+        }
+        await this.runGit(['clone', this.o.repoUrl, '.'], { cwd: this.o.workDir, withCredential: true });
+        // 仓库级提交身份（写入远端历史，可经 author 选项覆盖；不改全局配置）
+        await this.runGit(['config', 'user.name', this.o.author.name]);
+        await this.runGit(['config', 'user.email', this.o.author.email]);
+        this.repoReady = true;
+    }
+    /** pull --ff-only 同步远端；无本地提交（全新仓库）或无 upstream 时静默跳过 */
+    async pullFromRemote() {
+        const head = await this.runGit(['rev-parse', '--verify', '--quiet', 'HEAD'], { allowNonZero: true });
+        if (head.code !== 0)
+            return; // 无本地提交 → 无可 pull
+        const res = await this.runGit(['pull', '--ff-only'], { withCredential: true, allowNonZero: true });
+        if (res.code === 0)
+            return;
+        if (/no tracking information/i.test(res.stderr))
+            return; // 无 upstream（初始状态）→ 跳过
+        throw new GitTransportError(this.msg('sync.git.pullFailed', { err: this.mask(res.stderr, await this.readTokenOnce()) }));
+    }
+    /** 执行 git 命令；withCredential=true 时注入 credential helper（token 不进 argv），失败时错误消息脱敏 */
+    async runGit(args, opts = {}) {
+        const cwd = opts.cwd === undefined ? this.o.workDir : opts.cwd;
+        let extra = [];
+        let token = null;
+        let cleanup = null;
+        if (opts.withCredential) {
+            const cred = await this.buildCredentialArgs();
+            extra = cred.extraArgs;
+            token = cred.token;
+            cleanup = cred.cleanup;
+        }
+        try {
+            const result = await this.o.exec(this.o.gitBin, [...extra, ...args], { cwd, timeoutMs: this.o.timeoutMs });
+            if (result.code !== 0 && !opts.allowNonZero) {
+                throw new GitTransportError(this.msg('sync.git.cmdFailed', { args: args.join(' '), code: String(result.code), err: this.mask(result.stderr, token) }));
+            }
+            return result;
+        }
+        finally {
+            if (cleanup)
+                await cleanup();
+        }
+    }
+    /**
+     * 为网络命令构造 credential helper 参数：
+     * 仅 http(s) 远端需要 token；本地路径 / ssh 走 git 原生认证（密钥），不调用 provider。
+     * token 写入 os.tmpdir() 下临时 store 文件（权限 0600），命令后立即删除 —— 永不落工作副本/远端。
+     */
+    async buildCredentialArgs() {
+        if (!/^https?:\/\//i.test(this.o.repoUrl)) {
+            return { extraArgs: [], token: '', cleanup: async () => { } };
+        }
+        const token = await this.o.credentials.getToken();
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-git-cred-'));
+        const credFile = path.join(tmpDir, 'credential');
+        const host = this.repoHost();
+        const fileArg = quoteGitValue(credFile.replace(/\\/g, '/'));
+        await atomicWriteFile(credFile, `https://${this.o.credentialUsername}:${token}@${host}\n`, { mode: 0o600, symlink: 'reject' });
+        return {
+            extraArgs: ['-c', 'credential.helper=', '-c', `credential.helper=store --file=${fileArg}`],
+            token,
+            cleanup: async () => { await fs.rm(tmpDir, { recursive: true, force: true }); },
+        };
+    }
+    /** 从 repoUrl 提取 credential 匹配用的 host[:port] */
+    repoHost() {
+        try {
+            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 }));
+        }
+    }
+    /** 读取一次 token（错误消息脱敏用）；非 http(s) 场景返回空 */
+    async readTokenOnce() {
+        if (!/^https?:\/\//i.test(this.o.repoUrl))
+            return null;
+        try {
+            return await this.o.credentials.getToken();
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 错误/日志脱敏：token（原文与 URL 编码两种形态）与 repoUrl 一律替换 */
+    mask(text, token) {
+        let out = text.split(this.o.repoUrl).join('[REPO_URL]');
+        if (token && token.length >= 4) {
+            out = out.split(token).join('[REDACTED]').split(encodeURIComponent(token)).join('[REDACTED]');
+        }
+        return out;
+    }
+    assertSafeId(id) {
+        if (typeof id !== 'string' || !SAFE_ID_RE.test(id)) {
+            throw new GitTransportError(this.msg('sync.git.invalidSnapshotId', { id: JSON.stringify(id) }));
+        }
+    }
+    snapshotDir(id) {
+        return joinFs(this.snapshotsDir(), id);
+    }
+    snapshotsDir() {
+        return joinFs(this.o.workDir, SNAPSHOTS_REL);
+    }
+    /** 加密快照密文单文件目录（<workDir>/snapshots-encrypted/） */
+    encryptedSnapshotsDir() {
+        return joinFs(this.o.workDir, SNAPSHOTS_ENCRYPTED_REL);
+    }
+    /** 加密快照密文单文件路径（<id>.json） */
+    encryptedSnapshotFile(id) {
+        return joinFs(this.encryptedSnapshotsDir(), `${id}.json`);
+    }
+    /** 读密文单文件快照（解析失败 → null，调用方跳过，不静默失败整体 list）。 */
+    async readEncryptedSnapshotFile(file) {
+        try {
+            const raw = Buffer.from(await createSnapshotFs().readFile(file)).toString('utf8');
+            return deserializeSnapshot(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 读快照目录 manifest.json（结构不合法 → null，调用方跳过） */
+    async readDirManifest(dir) {
+        const fsx = createSnapshotFs();
+        try {
+            const abs = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
+            if (!(await fsx.exists(abs)))
+                return null;
+            const raw = Buffer.from(await fsx.readFile(abs)).toString('utf8');
+            const parsed = parseJsonSafe(raw);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                return null;
+            const m = parsed;
+            if (typeof m['id'] !== 'string' || typeof m['createdAt'] !== 'string'
+                || m['manifest'] === null || typeof m['manifest'] !== 'object'
+                || m['sectionHashes'] === null || typeof m['sectionHashes'] !== 'object') {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=git-transport.js.map

package/lib/sync/github-auth.d.ts

@@ -0,0 +1,131 @@
+/** GitHub device flow 第一步：请求设备码 */
+export declare const GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code";
+/** GitHub device flow 第三步：轮询换取 access token */
+export declare const GITHUB_ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
+/** 缺省 scope：repo（读写私有仓库，同步通道需要） */
+export declare const GITHUB_DEVICE_FLOW_SCOPE = "repo";
+/** GitHub 缺省轮询间隔（秒） */
+export declare const GITHUB_DEFAULT_INTERVAL = 5;
+/** slow_down 时按 RFC 8628 额外增加的等待秒数 */
+export declare const SLOW_DOWN_EXTRA_SECONDS = 5;
+export interface GitHubAuthOptions {
+    /** 可注入 fetcher（测试 mock 用）；缺省 = global fetch */
+    fetcher?: typeof fetch;
+    /** 可注入时钟（epoch ms；测试过期清理用）；缺省 = Date.now */
+    now?: () => number;
+}
+/** startDeviceFlow 产出：UI 展示用户码 + 授权页，宿主侧登记设备码 */
+export interface DeviceFlowStartResult {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** 设备码过期秒数（GitHub 默认 900） */
+    expiresIn: number;
+    /** GitHub 建议的轮询间隔秒数（缺省 5） */
+    interval: number;
+}
+/** 轮询结果状态：success 携带 token（宿主立即入库）；pending 继续等；其余为终止态 */
+export type DeviceFlowPollStatus = 'pending' | 'success' | 'denied' | 'expired' | 'error';
+export interface DeviceFlowPollResult {
+    status: DeviceFlowPollStatus;
+    /** status=success 时：access token（调用方负责立即写入 credentials，绝不落日志/回传 UI） */
+    accessToken?: string;
+    /** status=pending 时：下次轮询应等待的毫秒数（按 GitHub interval；slow_down 额外 +5s） */
+    pollDelayMs?: number;
+    /** status=error 时：GitHub 返回的 error code */
+    errorCode?: string;
+    /** 可展示的错误描述（来自 GitHub error_description，不含 token） */
+    message?: string;
+}
+/** GitHub OAuth 可预期错误：code = GitHub error / 固定内部码，status = HTTP 状态（网络层无） */
+export declare class GitHubAuthError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(message: string, code: string, status?: number);
+}
+/** exchangeDeviceCode 入参（client_secret 仅 confidential OAuth app 需要，缺省不发送） */
+export interface ExchangeDeviceCodeParams {
+    clientId: string;
+    deviceCode: string;
+    clientSecret?: string;
+    /** 轮询间隔秒数（pollForToken 计算下次延迟用；缺省 5） */
+    interval?: number;
+}
+/** 单次 token 交换结果：成功 = access token；失败 = GitHub error code + 描述 */
+export type ExchangeDeviceCodeResult = {
+    ok: true;
+    accessToken: string;
+} | {
+    ok: false;
+    error: string;
+    errorDescription?: string;
+};
+/**
+ * GitHub OAuth device flow 客户端。
+ * 无状态（设备码登记由宿主侧的 DeviceFlowStore 负责），fetch 可注入。
+ */
+export declare class GitHubAuthClient {
+    private readonly fetcher;
+    private readonly now;
+    constructor(options?: GitHubAuthOptions);
+    /**
+     * 用给定 token 验证身份并取回当前用户（GET /user）。
+     *
+     * 供 /sync/github/validate 判定「已存 token 是否仍有效」：401 → `unauthorized`，
+     * 其余错误按 `http_error` 抛出（调用方据此区分「未登录」与「真实故障」，不误判登出）。
+     * token 只作为本次请求的 Authorization 头，绝不回传、不落盘、不进日志。
+     */
+    getUser(token: string): Promise<{
+        login: string;
+        id: number;
+    }>;
+    /**
+     * 第一步：请求设备码。产出一次性 user_code + 授权页 URL + device_code
+     * （device_code 由宿主登记，只在本模块与宿主间流转，绝不发给浏览器）。
+     */
+    startDeviceFlow(clientId: string, scope?: string): Promise<DeviceFlowStartResult>;
+    /**
+     * 单次 token 交换（device flow 第三步的原子操作）。
+     * 返回类型化结果：成功 = access token；失败 = GitHub error code（pending/slow_down
+     * 等由 pollForToken 归并为轮询状态）。
+     */
+    exchangeDeviceCode(params: ExchangeDeviceCodeParams): Promise<ExchangeDeviceCodeResult>;
+    /**
+     * 轮询换取 access token，把 GitHub 错误码归并为 UI 可消费的轮询状态：
+     * - authorization_pending → pending（按 interval 继续等）
+     * - slow_down → pending（interval + 5s，RFC 8628）
+     * - expired_token → expired（终止，重新开始）
+     * - access_denied → denied（终止）
+     * - 其他 error → error（终止，携带 errorCode + 描述）
+     */
+    pollForToken(params: ExchangeDeviceCodeParams): Promise<DeviceFlowPollResult>;
+}
+/** DeviceFlowStore 登记的条目（device_code 只存宿主内存，绝不发往浏览器） */
+export interface DeviceFlowEntry {
+    deviceCode: string;
+    clientId: string;
+    clientSecret?: string;
+    /** 轮询间隔秒数（来自 start 响应，pollForToken 计算下次延迟用） */
+    interval: number;
+    /** 过期时刻（epoch ms）：now > expiresAt 视为已过期，get 返回 undefined 并清理 */
+    expiresAt: number;
+}
+/**
+ * 宿主内存设备码登记表（进程生命周期，跨请求共享 —— 与 RunRegistry 同模式）。
+ * device_code 的持有者是宿主：UI 只拿 flowId（随机 id），轮询时宿主凭 flowId 取回
+ * device_code 去 GitHub 换 token。过期条目惰性清理，防止无限增长。
+ */
+export declare class DeviceFlowStore {
+    private readonly flows;
+    private readonly now;
+    constructor(now?: () => number);
+    get size(): number;
+    /** 登记一个设备码流；flowId 由调用方生成（随机，不可猜） */
+    set(flowId: string, entry: DeviceFlowEntry): void;
+    /** 取回设备码流；过期条目视为不存在并立即清理 */
+    get(flowId: string): DeviceFlowEntry | undefined;
+    /** 主动移除（取消/完成后清理） */
+    delete(flowId: string): void;
+    /** 生成不可猜的 flowId（路由层用） */
+    static newFlowId(): string;
+}