dsh-session-cloud 0.1.0

package/lib/sync/engine.js

@@ -0,0 +1,379 @@
+/**
+ * 上行同步引擎（docs/02 §4.2、§10）。
+ *
+ * 职责：变更发现（listSnapshots revision 对比 + 定时兜底）→ 按字节偏移读新增
+ * → zstd 帧边界扫描取完整帧 → 链式 GCM 分段加密 → append 上传（409 幂等判定）
+ * → meta 覆写 → 推进本地 state。与 cordis 解耦，纯类便于单测。
+ */
+import fsp from 'node:fs/promises';
+import { LogEncryptor, encryptMeta, verifyTailSegment } from '../crypto/envelope.js';
+import { detectEncoding, emptyFold, foldFrame, scanZstdFrames } from './frames.js';
+import { ProtocolError } from './http-client.js';
+const BACKOFF_INITIAL_MS = 1000;
+const BACKOFF_MAX_MS = 5 * 60 * 1000;
+/** flush 钩子触发 scan 的合并窗口：一轮对话多次 flush 只做一次变更发现。 */
+const SCAN_DEBOUNCE_MS = 500;
+/** 409 幂等校验不通过：写入方冲突（疑似同名设备的另一台机器）。 */
+export class ConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConflictError';
+    }
+}
+export function logKey(device, sessionId) {
+    return `sessions/${device}/${sessionId}.log.enc`;
+}
+export function metaKey(device, sessionId) {
+    return `sessions/${device}/${sessionId}.meta.enc`;
+}
+export function freshSessionState() {
+    return {
+        uploadedBytes: 0,
+        remoteBytes: 0,
+        lastSegmentIndex: -1,
+        lastTag: '',
+        localRevision: '',
+        eventCount: 0,
+        updatedAt: 0,
+    };
+}
+export class SyncEngine {
+    options;
+    scheduled = new Map();
+    latest = new Map();
+    inFlight = new Set();
+    rerunRequested = new Set();
+    backoff = new Map();
+    scanTimer;
+    disposed = false;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * 外部触发的变更发现入口（session/flush 钩子接线，M5）：把窗口内的多次
+     * 触发合并为一次 scan。listener 必须轻——flush 是 awaited durability
+     * checkpoint，重活留给 scan/防抖队列，这里只拨一个 timer。
+     */
+    requestScan() {
+        if (this.disposed || !this.options.getConfig().autoUpload)
+            return;
+        if (this.scanTimer !== undefined)
+            return;
+        this.scanTimer = setTimeout(() => {
+            this.scanTimer = undefined;
+            void this.scan();
+        }, SCAN_DEBOUNCE_MS);
+        this.scanTimer.unref?.();
+    }
+    /** 一轮变更发现：revision 对比，变化的进防抖队列。 */
+    async scan() {
+        if (this.disposed || !this.options.getConfig().autoUpload)
+            return;
+        let snapshots;
+        try {
+            snapshots = await this.options.persistence.listSnapshots();
+        }
+        catch (error) {
+            this.emit({ kind: 'error', sessionId: '', message: `listSnapshots failed: ${String(error)}` });
+            return;
+        }
+        for (const snapshot of snapshots) {
+            if (!this.needsSync(snapshot))
+                continue;
+            this.schedule(snapshot);
+        }
+    }
+    /** 变更判定：revision 与 state 不一致（或处于退避待重试）才需要同步。 */
+    needsSync(snapshot) {
+        const state = this.options.state.getSession(snapshot.header.id);
+        if (state?.status === 'conflict' || state?.status === 'skipped-plain')
+            return false;
+        const wait = this.backoff.get(snapshot.header.id);
+        if (wait !== undefined && wait.revision !== snapshot.revision) {
+            // 会话有新变更：重置退避立即重试（docs/02 §10「下一次会话变更重置退避」）
+            this.backoff.delete(snapshot.header.id);
+            return true;
+        }
+        if (state?.localRevision === snapshot.revision && wait === undefined)
+            return false;
+        return true;
+    }
+    /**
+     * 立即全部同步（设置卡「立即全部同步」按钮，docs/01 §5.3）：
+     * 用户显式触发，无视 autoUpload 开关；全量扫描后把所有待同步会话
+     * 调度进队列并 await 完成（复用 schedule/flush 防抖-冲刷机制）。
+     */
+    async syncAllNow() {
+        if (this.disposed)
+            return { ok: 0, failed: 0 };
+        // 用户显式触发：重置全部退避（手动同步的语义至少等同一次会话变更）
+        this.backoff.clear();
+        let snapshots;
+        try {
+            snapshots = await this.options.persistence.listSnapshots();
+        }
+        catch (error) {
+            return { ok: 0, failed: 1, firstError: `listSnapshots failed: ${String(error)}`.slice(0, 300) };
+        }
+        const targets = snapshots.filter((snapshot) => this.needsSync(snapshot));
+        for (const snapshot of targets)
+            this.schedule(snapshot);
+        await this.flush();
+        let ok = 0;
+        let failed = 0;
+        let firstError;
+        for (const snapshot of targets) {
+            const state = this.options.state.getSession(snapshot.header.id);
+            if (state?.status === 'error' || state?.status === 'conflict') {
+                failed += 1;
+                firstError ??= `${snapshot.header.id}: ${state.error ?? ''}`.slice(0, 300);
+            }
+            else {
+                ok += 1;
+            }
+        }
+        return { ok, failed, firstError };
+    }
+    /** 同会话变更在防抖窗口内合并为一次上传。 */
+    schedule(snapshot) {
+        if (this.disposed)
+            return;
+        const id = snapshot.header.id;
+        this.latest.set(id, snapshot);
+        const existing = this.scheduled.get(id);
+        if (existing)
+            clearTimeout(existing.timer);
+        const timer = setTimeout(() => {
+            this.scheduled.delete(id);
+            void this.pump(id);
+        }, this.options.getConfig().uploadDebounceMs);
+        timer.unref?.();
+        this.scheduled.set(id, { snapshot, timer });
+    }
+    /** 进程退出前冲刷：立即执行所有防抖中的会话并等待在途上传结束。 */
+    async flush() {
+        const ids = [...this.scheduled.keys()];
+        for (const { timer } of this.scheduled.values())
+            clearTimeout(timer);
+        this.scheduled.clear();
+        await Promise.all(ids.map((id) => this.pump(id)));
+    }
+    async dispose() {
+        if (this.scanTimer !== undefined) {
+            clearTimeout(this.scanTimer);
+            this.scanTimer = undefined;
+        }
+        await this.flush(); // 退出前强制冲刷在途批次
+        this.disposed = true;
+        // 等在途上传收尾（dispose 不发起新同步）
+        while (this.inFlight.size > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    /** 启动：解除 conflict 状态（配置如设备名可能已更换，允许重试），然后做一轮变更发现。 */
+    async start() {
+        for (const [id, state] of this.options.state.entries()) {
+            if (state.status === 'conflict' || state.status === 'error') {
+                await this.options.state.putSession(id, { ...state, status: 'ok', error: undefined });
+            }
+        }
+        await this.scan();
+    }
+    /** 每会话串行泵：在途期间到来的变更置 rerun 标记，结束后立即再跑一轮。 */
+    async pump(sessionId) {
+        if (this.disposed)
+            return;
+        if (this.inFlight.has(sessionId)) {
+            this.rerunRequested.add(sessionId);
+            return;
+        }
+        this.inFlight.add(sessionId);
+        try {
+            do {
+                this.rerunRequested.delete(sessionId);
+                const snapshot = this.latest.get(sessionId);
+                if (!snapshot)
+                    break;
+                await this.syncSession(snapshot);
+            } while (this.rerunRequested.has(sessionId) && !this.disposed);
+        }
+        finally {
+            this.inFlight.delete(sessionId);
+        }
+    }
+    emit(event) {
+        this.options.onEvent?.(event);
+    }
+    async syncSession(snapshot) {
+        const id = snapshot.header.id;
+        const state = this.options.state.getSession(id) ?? freshSessionState();
+        try {
+            await this.syncSessionOnce(snapshot, state);
+            this.backoff.delete(id);
+        }
+        catch (error) {
+            if (error instanceof ConflictError) {
+                state.status = 'conflict';
+                state.error = error.message;
+                await this.options.state.putSession(id, state);
+                this.emit({ kind: 'conflict', sessionId: id, message: error.message });
+                return;
+            }
+            const prev = this.backoff.get(id);
+            const delayMs = Math.min(prev ? prev.delayMs * 2 : BACKOFF_INITIAL_MS, BACKOFF_MAX_MS);
+            this.backoff.set(id, { delayMs, nextRetryAt: this.now() + delayMs, revision: snapshot.revision });
+            state.status = 'error';
+            state.error = String(error);
+            await this.options.state.putSession(id, state);
+            await this.options.state.setGlobal({ lastError: String(error) });
+            this.emit({ kind: 'error', sessionId: id, message: String(error) });
+            // 退避到点后由下一轮 scan 兜底重试（revision 与 state 不一致会再次 schedule）
+        }
+    }
+    async syncSessionOnce(snapshot, state) {
+        const { header, revision } = snapshot;
+        const id = header.id;
+        const { client, state: store } = this.options;
+        const wait = this.backoff.get(id);
+        if (wait && this.now() < wait.nextRetryAt)
+            return;
+        const location = this.options.persistence.locate(header);
+        if (!location) {
+            // 无单文件 artifact 的后端（如 SQLite）：不同步，标记后不再扫描
+            state.status = 'skipped-plain';
+            state.error = 'persistence backend exposes no file artifact';
+            state.localRevision = revision;
+            await store.putSession(id, state);
+            return;
+        }
+        const stat = await fsp.stat(location.path);
+        if (stat.size < state.uploadedBytes) {
+            // 文件变短（防御：正常不可达）——回退全量重传
+            Object.assign(state, freshSessionState());
+        }
+        // 明文 profile 检测（仅首传判断，之后由 state 记住）
+        if (state.uploadedBytes === 0 && state.lastSegmentIndex === -1) {
+            const handle = await fsp.open(location.path, 'r');
+            try {
+                const prefix = Buffer.alloc(4);
+                await handle.read(prefix, 0, 4, 0);
+                if (detectEncoding(prefix) !== 'zstd') {
+                    state.status = 'skipped-plain';
+                    state.error = 'session artifact is not zstd-compressed (compression: none profile)';
+                    state.localRevision = revision;
+                    await store.putSession(id, state);
+                    this.emit({ kind: 'skipped-plain', sessionId: id });
+                    return;
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        const newBytes = await readTail(location.path, state.uploadedBytes);
+        if (newBytes.length === 0) {
+            state.localRevision = revision;
+            await store.putSession(id, state);
+            return;
+        }
+        const scan = scanZstdFrames(newBytes);
+        if (scan.frames.length === 0) {
+            // 没有完整帧（写入进行中），等下一窗口
+            state.localRevision = revision;
+            await store.putSession(id, state);
+            return;
+        }
+        const last = scan.frames[scan.frames.length - 1];
+        const plaintext = newBytes.subarray(0, last.end);
+        // 链式分段加密（从 state 恢复段序号与前段 tag）
+        const nextIndex = state.lastSegmentIndex + 1;
+        const encryptor = new LogEncryptor(this.options.key, this.options.salt, id, nextIndex, state.lastTag ? Buffer.from(state.lastTag, 'hex') : undefined);
+        const segment = encryptor.append(plaintext);
+        const payload = state.remoteBytes === 0 ? Buffer.concat([encryptor.objectHeader(), segment]) : segment;
+        const key = logKey(this.options.device, id);
+        try {
+            if (state.remoteBytes === 0) {
+                await client.overwrite(key, payload);
+            }
+            else {
+                await client.append(key, state.remoteBytes, payload);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ProtocolError) || error.status !== 409)
+                throw error;
+            // 409 幂等判定：通过则不重传、直接随下方流程推进 state
+            await this.resolve409(key, id, nextIndex, state, segment, plaintext, error.currentLength);
+        }
+        // meta 折叠：解压本段全部帧
+        const fold = emptyFold();
+        for (const frame of scan.frames) {
+            await foldFrame(newBytes.subarray(frame.start, frame.end), fold);
+        }
+        state.uploadedBytes += plaintext.length;
+        state.remoteBytes += payload.length;
+        state.lastSegmentIndex = nextIndex;
+        state.lastTag = encryptor.lastTag.toString('hex');
+        state.localRevision = revision;
+        state.eventCount += fold.eventCount;
+        if (fold.title !== undefined)
+            state.title = fold.title;
+        state.updatedAt = Math.max(state.updatedAt, fold.updatedAt);
+        state.status = 'ok';
+        state.error = undefined;
+        const meta = {
+            sessionId: id,
+            title: state.title ?? '',
+            createdAt: header.createdAt,
+            updatedAt: state.updatedAt || header.createdAt,
+            eventCount: state.eventCount,
+            formatVersion: header.version,
+            cwd: header.cwd ?? '',
+            device: this.options.device,
+        };
+        await client.overwrite(metaKey(this.options.device, id), encryptMeta(this.options.key, this.options.salt, id, meta));
+        await store.putSession(id, state);
+        await store.setGlobal({ lastSyncAt: this.now(), lastError: undefined });
+        this.emit({ kind: 'uploaded', sessionId: id, bytes: payload.length });
+    }
+    /**
+     * 409 幂等判定（docs/02 §10）：服务端长度恰等于「state 偏移 + 待传段长」时，
+     * 下载末段做链式 AAD 校验并比对明文——通过则视为上次上传已成功（不重复上传）；
+     * 否则判定写入方冲突，抛 ConflictError 停止该会话同步，不做盲目全量覆写。
+     */
+    async resolve409(key, sessionId, segmentIndex, state, segment, plaintext, serverLength) {
+        const expected = state.remoteBytes + segment.length;
+        if (serverLength === undefined || serverLength !== expected) {
+            throw new ConflictError(`409 on ${key}: server length ${serverLength ?? '?'} != state ${state.remoteBytes} + segment ${segment.length}`);
+        }
+        const tail = await this.options.client.downloadRange(key, serverLength - segment.length, serverLength - 1);
+        const prevTag = state.lastTag ? Buffer.from(state.lastTag, 'hex') : null;
+        let decoded;
+        try {
+            decoded = verifyTailSegment(this.options.key, sessionId, segmentIndex, prevTag, tail);
+        }
+        catch {
+            throw new ConflictError(`409 on ${key}: tail segment failed chained-AAD verification`);
+        }
+        if (!decoded.equals(plaintext)) {
+            throw new ConflictError(`409 on ${key}: tail segment plaintext differs from local`);
+        }
+        // 幂等确认：上次上传其实成功了，只是 state 未推进
+    }
+}
+async function readTail(file, offset) {
+    const handle = await fsp.open(file, 'r');
+    try {
+        const stat = await handle.stat();
+        if (stat.size <= offset)
+            return Buffer.alloc(0);
+        const buffer = Buffer.alloc(stat.size - offset);
+        await handle.read(buffer, 0, buffer.length, offset);
+        return buffer;
+    }
+    finally {
+        await handle.close();
+    }
+}

package/lib/sync/frames.d.ts

@@ -0,0 +1,35 @@
+import { constants, zstdCompress, zstdDecompress } from 'node:zlib';
+export declare const ZSTD_MAGIC = 4247762216;
+export declare const zstdCompressAsync: typeof zstdCompress.__promisify__;
+export declare const zstdDecompressAsync: typeof zstdDecompress.__promisify__;
+/** 与 dsh 一致：压缩帧带 checksum（compressZstdFrame 的 CHECKSUM_OPTIONS）。 */
+export declare const ZSTD_CHECKSUM_OPTIONS: {
+    params: {
+        [constants.ZSTD_c_checksumFlag]: number;
+    };
+};
+export interface ZstdFrameRange {
+    start: number;
+    end: number;
+}
+export interface ZstdFrameScan {
+    frames: ZstdFrameRange[];
+    tornStart?: number;
+}
+export declare function scanZstdFrames(buffer: Buffer, maxFrames?: number): ZstdFrameScan;
+/** 会话文件的物理编码检测：zstd 魔数或明文（`compression: none` profile）。 */
+export declare function detectEncoding(prefix: Buffer): 'zstd' | 'plain';
+/** 事件折叠累积器：标题 latest-wins，updatedAt 取最大事件时间，事件按解码后计数。 */
+export interface MetaFold {
+    title?: string;
+    updatedAt: number;
+    eventCount: number;
+}
+export declare function emptyFold(): MetaFold;
+/**
+ * 把一段完整帧解压后的 JSONL 明文折叠进 meta 累积器。
+ * 会话首帧的首行是 header 行（type 'session'），跳过不计数。
+ */
+export declare function foldPlaintext(plaintext: Buffer, acc: MetaFold): void;
+/** 解压一个完整帧并折叠。 */
+export declare function foldFrame(frameBytes: Buffer, acc: MetaFold): Promise<void>;

package/lib/sync/frames.js

@@ -0,0 +1,121 @@
+/**
+ * zstd 帧结构扫描与事件折叠（M2 上行链路只读本地会话文件）。
+ *
+ * scanZstdFrames 复刻自 dsh（packages/session/session-persistence-jsonl/src/zstd.ts），
+ * 纯结构扫描不解压；帧边界即 dsh 的提交边界（每事件批次一个完整帧）。
+ * 事件折叠按存储行解码规则自行计数：chunk 行（text-chunks 等）一行打包多个事件，
+ * 按 data.texts/data.args 长度计数（与 decodeStorageRecord 的展开数一致）。
+ */
+import { promisify } from 'node:util';
+import { constants, zstdCompress, zstdDecompress } from 'node:zlib';
+export const ZSTD_MAGIC = 0xfd2fb528;
+export const zstdCompressAsync = promisify(zstdCompress);
+export const zstdDecompressAsync = promisify(zstdDecompress);
+/** 与 dsh 一致：压缩帧带 checksum（compressZstdFrame 的 CHECKSUM_OPTIONS）。 */
+export const ZSTD_CHECKSUM_OPTIONS = { params: { [constants.ZSTD_c_checksumFlag]: 1 } };
+export function scanZstdFrames(buffer, maxFrames = Number.POSITIVE_INFINITY) {
+    const frames = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const start = offset;
+        if (buffer.length - offset < 4)
+            return { frames, tornStart: start };
+        if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) {
+            throw new Error(`corrupt Zstandard session log: invalid frame magic at byte ${offset}`);
+        }
+        offset += 4;
+        if (offset === buffer.length)
+            return { frames, tornStart: start };
+        const descriptor = buffer.readUInt8(offset);
+        offset += 1;
+        if ((descriptor & 0x18) !== 0) {
+            throw new Error(`corrupt Zstandard session log: reserved frame-header bit at byte ${offset - 1}`);
+        }
+        const contentSizeFlag = descriptor >>> 6;
+        const singleSegment = (descriptor & 0x20) !== 0;
+        const checksum = (descriptor & 0x04) !== 0;
+        const dictionaryFlag = descriptor & 0x03;
+        const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+        const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+        const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+        if (buffer.length - offset < remainingHeaderBytes)
+            return { frames, tornStart: start };
+        offset += remainingHeaderBytes;
+        for (;;) {
+            if (buffer.length - offset < 3)
+                return { frames, tornStart: start };
+            const blockHeader = buffer.readUIntLE(offset, 3);
+            offset += 3;
+            const lastBlock = (blockHeader & 1) !== 0;
+            const blockType = (blockHeader >>> 1) & 0x03;
+            const blockSize = blockHeader >>> 3;
+            if (blockType === 0x03) {
+                throw new Error(`corrupt Zstandard session log: reserved block type at byte ${offset - 3}`);
+            }
+            const payloadBytes = blockType === 0x01 ? 1 : blockSize;
+            if (buffer.length - offset < payloadBytes)
+                return { frames, tornStart: start };
+            offset += payloadBytes;
+            if (lastBlock)
+                break;
+        }
+        if (checksum) {
+            if (buffer.length - offset < 4)
+                return { frames, tornStart: start };
+            offset += 4;
+        }
+        frames.push({ start, end: offset });
+        if (frames.length === maxFrames)
+            return { frames };
+    }
+    return { frames };
+}
+/** 会话文件的物理编码检测：zstd 魔数或明文（`compression: none` profile）。 */
+export function detectEncoding(prefix) {
+    return prefix.length >= 4 && prefix.readUInt32LE(0) === ZSTD_MAGIC ? 'zstd' : 'plain';
+}
+export function emptyFold() {
+    return { updatedAt: 0, eventCount: 0 };
+}
+const CHUNK_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks']);
+/**
+ * 把一段完整帧解压后的 JSONL 明文折叠进 meta 累积器。
+ * 会话首帧的首行是 header 行（type 'session'），跳过不计数。
+ */
+export function foldPlaintext(plaintext, acc) {
+    const text = plaintext.toString('utf8');
+    for (const line of text.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const row = JSON.parse(line);
+        const type = row.type;
+        if (type === 'session')
+            continue; // header 行
+        if (typeof type !== 'string')
+            throw new Error('corrupt event row: missing type');
+        if (CHUNK_ROW_TYPES.has(type)) {
+            const data = row.data;
+            const count = (data.texts ?? data.args ?? []).length;
+            acc.eventCount += count;
+            const time0 = typeof row.time0 === 'number' ? row.time0 : undefined;
+            if (time0 !== undefined) {
+                const dt = Array.isArray(data.dt) ? data.dt.reduce((a, b) => a + b, 0) : 0;
+                acc.updatedAt = Math.max(acc.updatedAt, time0 + dt);
+            }
+        }
+        else {
+            acc.eventCount += 1;
+            if (typeof row.time === 'number')
+                acc.updatedAt = Math.max(acc.updatedAt, row.time);
+            if (type === 'session/title') {
+                const data = row.data;
+                if (typeof data.title === 'string')
+                    acc.title = data.title;
+            }
+        }
+    }
+}
+/** 解压一个完整帧并折叠。 */
+export async function foldFrame(frameBytes, acc) {
+    foldPlaintext(await zstdDecompressAsync(frameBytes), acc);
+}

package/lib/sync/http-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh-cloud-sync protocol v1 客户端（docs/03-server-protocol.md §4/§7）。
+ * 仅依赖全局 fetch，无第三方依赖。
+ */
+export interface RemoteObject {
+    key: string;
+    size: number;
+    revision: string;
+    lastModified: string;
+}
+/** 带状态码的协议错误；409 额外携带服务端当前长度。 */
+export declare class ProtocolError extends Error {
+    readonly status: number;
+    readonly currentLength?: number | undefined;
+    constructor(status: number, message: string, currentLength?: number | undefined);
+}
+export interface SyncClientOptions {
+    serverUrl: string;
+    token: string;
+    /** 用户名（可选）：多用户服务端的配对校验，非空时随请求发送 X-DSH-User。 */
+    username?: string;
+    timeoutMs?: number;
+}
+export declare class SyncClient {
+    private base;
+    private token;
+    private username;
+    private timeoutMs;
+    constructor(options: SyncClientOptions);
+    private request;
+    /** 列表（可选前缀过滤），按 key 字典序。 */
+    list(prefix?: string): Promise<RemoteObject[]>;
+    /** 全量下载；key 不存在抛 ProtocolError(404)。 */
+    download(key: string): Promise<Buffer>;
+    /** Range 下载 [start, end]（含端点）。 */
+    downloadRange(key: string, start: number, end: number): Promise<Buffer>;
+    /** 全量覆写（首传、meta 更新）。 */
+    overwrite(key: string, content: Buffer): Promise<void>;
+    /** 追加；offset 与服务端当前长度不一致抛 ProtocolError(409, currentLength)。 */
+    append(key: string, offset: number, content: Buffer): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** 连通性测试：列表接口通且鉴权通过即成功（healthz 不鉴权，不用）。 */
+    ping(): Promise<void>;
+}

package/lib/sync/http-client.js

@@ -0,0 +1,87 @@
+/**
+ * dsh-cloud-sync protocol v1 客户端（docs/03-server-protocol.md §4/§7）。
+ * 仅依赖全局 fetch，无第三方依赖。
+ */
+/** 带状态码的协议错误；409 额外携带服务端当前长度。 */
+export class ProtocolError extends Error {
+    status;
+    currentLength;
+    constructor(status, message, currentLength) {
+        super(message);
+        this.status = status;
+        this.currentLength = currentLength;
+        this.name = 'ProtocolError';
+    }
+}
+export class SyncClient {
+    base;
+    token;
+    username;
+    timeoutMs;
+    constructor(options) {
+        this.base = options.serverUrl.replace(/\/+$/, '');
+        this.token = options.token;
+        this.username = options.username || undefined;
+        this.timeoutMs = options.timeoutMs ?? 15000;
+    }
+    async request(method, path, body, headers = {}) {
+        const response = await fetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                ...(this.username ? { 'X-DSH-User': this.username } : {}),
+                ...(body ? { 'Content-Type': 'application/octet-stream' } : {}),
+                ...headers,
+            },
+            body: body,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const responseBody = Buffer.from(await response.arrayBuffer());
+        if (!response.ok) {
+            let currentLength;
+            if (response.status === 409) {
+                try {
+                    currentLength = JSON.parse(responseBody.toString('utf8')).currentLength;
+                }
+                catch {
+                    // 哑存储规范要求 409 带 currentLength；缺失按无长度处理
+                }
+            }
+            throw new ProtocolError(response.status, `${method} ${path} → ${response.status}`, currentLength);
+        }
+        return { status: response.status, headers: response.headers, body: responseBody };
+    }
+    /** 列表（可选前缀过滤），按 key 字典序。 */
+    async list(prefix) {
+        const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : '';
+        const { body } = await this.request('GET', `/v1/sessions${query}`);
+        return JSON.parse(body.toString('utf8')).objects;
+    }
+    /** 全量下载；key 不存在抛 ProtocolError(404)。 */
+    async download(key) {
+        const { body } = await this.request('GET', `/v1/${key}`);
+        return body;
+    }
+    /** Range 下载 [start, end]（含端点）。 */
+    async downloadRange(key, start, end) {
+        const { body } = await this.request('GET', `/v1/${key}`, undefined, {
+            Range: `bytes=${start}-${end}`,
+        });
+        return body;
+    }
+    /** 全量覆写（首传、meta 更新）。 */
+    async overwrite(key, content) {
+        await this.request('PUT', `/v1/${key}`, content);
+    }
+    /** 追加；offset 与服务端当前长度不一致抛 ProtocolError(409, currentLength)。 */
+    async append(key, offset, content) {
+        await this.request('PUT', `/v1/${key}`, content, { 'X-Append-Offset': String(offset) });
+    }
+    async delete(key) {
+        await this.request('DELETE', `/v1/${key}`);
+    }
+    /** 连通性测试：列表接口通且鉴权通过即成功（healthz 不鉴权，不用）。 */
+    async ping() {
+        await this.list('sessions/');
+    }
+}

package/lib/sync/kdf.d.ts

@@ -0,0 +1,14 @@
+import { type SyncClient } from './http-client.js';
+export interface KdfDeps {
+    client: SyncClient;
+    device: string;
+    passphrase: string;
+    /** 采纳他机 sidecar 时回调（日志/状态行提示） */
+    onAdopt?: (message: string) => void;
+}
+export interface KdfKey {
+    key: Buffer;
+    salt: Buffer;
+}
+/** kdf 引导（见模块注释的解析顺序）。 */
+export declare function bootstrapKdf(deps: KdfDeps): Promise<KdfKey>;