dsh-session-cloud 0.1.0

package/lib/crypto/envelope.js

@@ -0,0 +1,162 @@
+/**
+ * dsh-cloud-sync 加密信封（protocol v1，见 docs/03-server-protocol.md §5）。
+ *
+ * 字节布局：
+ *   数据对象：magic "DCS1"(4) + kdf salt(16) + 加密段*，段顺序即段序号
+ *   每段：    段密文长度 L uint32BE(4) + nonce(12) + 密文(L) + GCM tag(16)
+ *   元数据对象：magic + salt + 单个段（AAD "meta|<sessionId>"）
+ *
+ * 链式 AAD：log 段 i 的 AAD = "log|<sessionId>|<i>|<hex(prevTag)>"，
+ * i=0 时 prevTag 为 32 个字符 "0"。截断、重排、跨对象拼接均解密失败。
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+export const MAGIC = Buffer.from('DCS1');
+export const SALT_LENGTH = 16;
+export const HEADER_LENGTH = MAGIC.length + SALT_LENGTH;
+export const NONCE_LENGTH = 12;
+export const TAG_LENGTH = 16;
+const LENGTH_FIELD = 4;
+/** 段固定开销：长度字段 + nonce + tag */
+export const SEGMENT_OVERHEAD = LENGTH_FIELD + NONCE_LENGTH + TAG_LENGTH;
+export const KDF_DEFAULTS = { N: 2 ** 15, r: 8, p: 1 };
+export function generateSalt() {
+    return randomBytes(SALT_LENGTH);
+}
+export function deriveKey(passphrase, salt, params = KDF_DEFAULTS) {
+    if (salt.length !== SALT_LENGTH)
+        throw new Error(`salt must be ${SALT_LENGTH} bytes`);
+    // Node 默认 maxmem=32MB 不够 N=2^15,r=8（需 128*N*r*p ≈ 32MB 外加余量）
+    const maxmem = Math.max(64 * 1024 * 1024, 256 * params.N * params.r * params.p);
+    return scryptSync(passphrase, salt, 32, { N: params.N, r: params.r, p: params.p, maxmem });
+}
+export function encodeKdfSidecar(salt, params = KDF_DEFAULTS) {
+    return Buffer.from(JSON.stringify({ salt: salt.toString('hex'), ...params }), 'utf8');
+}
+export function decodeKdfSidecar(bytes) {
+    const parsed = JSON.parse(bytes.toString('utf8'));
+    const salt = Buffer.from(parsed.salt, 'hex');
+    if (salt.length !== SALT_LENGTH)
+        throw new Error('invalid salt in kdf sidecar');
+    return { salt, params: { N: parsed.N, r: parsed.r, p: parsed.p } };
+}
+const ZERO_TAG_HEX = '0'.repeat(TAG_LENGTH * 2);
+function logAad(sessionId, index, prevTagHex) {
+    return Buffer.from(`log|${sessionId}|${index}|${prevTagHex}`, 'utf8');
+}
+function metaAad(sessionId) {
+    return Buffer.from(`meta|${sessionId}`, 'utf8');
+}
+function sealSegment(key, nonce, aad, plaintext) {
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    cipher.setAAD(aad);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const header = Buffer.alloc(LENGTH_FIELD + NONCE_LENGTH);
+    header.writeUInt32BE(ciphertext.length, 0);
+    nonce.copy(header, LENGTH_FIELD);
+    return Buffer.concat([header, ciphertext, tag]);
+}
+function openSegment(key, aad, segment) {
+    if (segment.length < SEGMENT_OVERHEAD)
+        throw new Error('truncated segment');
+    const length = segment.readUInt32BE(0);
+    if (segment.length !== SEGMENT_OVERHEAD + length) {
+        throw new Error(`segment length mismatch: field=${length}, actual=${segment.length - SEGMENT_OVERHEAD}`);
+    }
+    const nonce = segment.subarray(LENGTH_FIELD, LENGTH_FIELD + NONCE_LENGTH);
+    const ciphertext = segment.subarray(LENGTH_FIELD + NONCE_LENGTH, LENGTH_FIELD + NONCE_LENGTH + length);
+    const tag = segment.subarray(segment.length - TAG_LENGTH);
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAAD(aad);
+    decipher.setAuthTag(tag);
+    try {
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return { plaintext, tag: Buffer.from(tag) };
+    }
+    catch {
+        throw new Error('segment authentication failed');
+    }
+}
+function checkHeader(bytes, context) {
+    if (bytes.length < HEADER_LENGTH)
+        throw new Error(`${context}: object too short`);
+    if (!bytes.subarray(0, MAGIC.length).equals(MAGIC))
+        throw new Error(`${context}: bad magic`);
+}
+/**
+ * 数据对象的增量加密器。一次上传 = `append(完整 zstd 帧区间)` 产出一个段，
+ * 段字节直接 PUT append 到服务端对象尾部。
+ */
+export class LogEncryptor {
+    key;
+    salt;
+    sessionId;
+    index;
+    prevTagHex;
+    constructor(key, salt, sessionId, startIndex = 0, prevTag) {
+        this.key = key;
+        this.salt = salt;
+        this.sessionId = sessionId;
+        if (salt.length !== SALT_LENGTH)
+            throw new Error(`salt must be ${SALT_LENGTH} bytes`);
+        this.index = startIndex;
+        this.prevTagHex = prevTag ? prevTag.toString('hex') : ZERO_TAG_HEX;
+    }
+    /** 新对象的文件头（magic + salt），仅在首传时写入一次。 */
+    objectHeader() {
+        return Buffer.concat([MAGIC, this.salt]);
+    }
+    get segmentIndex() {
+        return this.index;
+    }
+    get lastTag() {
+        return Buffer.from(this.prevTagHex, 'hex');
+    }
+    /** 加密一段明文（完整 zstd 帧的字节区间），返回可追加的段字节。 */
+    append(plaintext) {
+        const aad = logAad(this.sessionId, this.index, this.prevTagHex);
+        const segment = sealSegment(this.key, randomBytes(NONCE_LENGTH), aad, plaintext);
+        this.prevTagHex = segment.subarray(segment.length - TAG_LENGTH).toString('hex');
+        this.index += 1;
+        return segment;
+    }
+}
+/** 解密完整数据对象（恢复路径）：校验 magic/salt，逐段链式解密。 */
+export function decryptLog(key, sessionId, bytes) {
+    checkHeader(bytes, 'log');
+    const parts = [];
+    let offset = HEADER_LENGTH;
+    let index = 0;
+    let prevTagHex = ZERO_TAG_HEX;
+    while (offset < bytes.length) {
+        if (bytes.length - offset < SEGMENT_OVERHEAD)
+            throw new Error('truncated: incomplete trailing segment');
+        const length = bytes.readUInt32BE(offset);
+        const end = offset + SEGMENT_OVERHEAD + length;
+        if (end > bytes.length)
+            throw new Error('truncated: segment extends past end of object');
+        const { plaintext, tag } = openSegment(key, logAad(sessionId, index, prevTagHex), bytes.subarray(offset, end));
+        parts.push(plaintext);
+        prevTagHex = tag.toString('hex');
+        index += 1;
+        offset = end;
+    }
+    return Buffer.concat(parts);
+}
+/**
+ * 409 幂等判定（见 docs/02 §10）：下载服务端末段，以预期 AAD 校验解密。
+ * 返回明文供与本地比对；任何不匹配抛错。
+ */
+export function verifyTailSegment(key, sessionId, segmentIndex, prevTag, segmentBytes) {
+    const prevTagHex = prevTag ? prevTag.toString('hex') : ZERO_TAG_HEX;
+    return openSegment(key, logAad(sessionId, segmentIndex, prevTagHex), segmentBytes).plaintext;
+}
+export function encryptMeta(key, salt, sessionId, meta) {
+    const plaintext = Buffer.from(JSON.stringify(meta), 'utf8');
+    return Buffer.concat([MAGIC, salt, sealSegment(key, randomBytes(NONCE_LENGTH), metaAad(sessionId), plaintext)]);
+}
+export function decryptMeta(key, sessionId, bytes) {
+    checkHeader(bytes, 'meta');
+    const { plaintext } = openSegment(key, metaAad(sessionId), bytes.subarray(HEADER_LENGTH));
+    return JSON.parse(plaintext.toString('utf8'));
+}

package/lib/dsh-types.d.ts

@@ -0,0 +1,69 @@
+/** @deepseek-ai/dsh-session-persistence 的 SessionHeader（packages/core/session/src/types.ts:56）。 */
+export interface SessionHeaderLike {
+    readonly version: number;
+    readonly id: string;
+    readonly createdAt: number;
+    readonly cwd?: string;
+    readonly parentSession?: string;
+    readonly seedLength?: number;
+    readonly origin?: 'subagent';
+    readonly delegationDepth?: number;
+    readonly agentPreset?: string;
+}
+export interface SessionSnapshotLike {
+    readonly header: SessionHeaderLike;
+    /** 后端持有的不透明 revision 令牌，变更必变 */
+    readonly revision: string;
+}
+/** locate() 的返回；无单文件 artifact 的后端（如 SQLite）返回 undefined。 */
+export interface SessionLocationLike {
+    readonly kind: string;
+    readonly path: string;
+}
+export interface SessionPersistenceLike {
+    listSnapshots(signal?: AbortSignal): Promise<SessionSnapshotLike[]>;
+    list(signal?: AbortSignal): Promise<SessionHeaderLike[]>;
+    locate(meta: SessionHeaderLike): SessionLocationLike | undefined;
+}
+/** @deepseek-ai/dsh-workspace 的 Workspace（恢复挂载用到 attachSession）。 */
+export interface WorkspaceLike {
+    readonly path: string;
+    /** 把会话记入本工作区成员（cwd 校验：realpath 后须等于工作区 path） */
+    attachSession(sessionId: string): Promise<void>;
+}
+export interface WorkspaceRegistryLike {
+    list(): WorkspaceLike[];
+    /** 按本机 canonical path 查找已有 workspace；不存在返回 undefined */
+    resolveByPath(path: string): Promise<WorkspaceLike | undefined>;
+    /** 为已存在目录新建 workspace（realpath + isDirectory 校验，目录不存在会抛） */
+    create(path: string, title?: string): Promise<WorkspaceLike>;
+}
+/** settings 服务的最小切面（@deepseek-ai/dsh-settings 的 installSection）。 */
+export interface SettingsSectionHooksLike<T> {
+    setSource(source: () => T): void;
+    onChange(): void;
+    validate?(value: T): void;
+}
+export interface SettingsLike {
+    installSection<T>(owner: unknown, ns: string, schema: unknown, entry: T, hooks: SettingsSectionHooksLike<T>): void;
+    /** merge 写 user 层并持久化；Host 状态回写走这条通道（settings/src/index.ts:562） */
+    update(ns: string, patch: object): Promise<void>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sessionPersistence: SessionPersistenceLike;
+        settings?: SettingsLike;
+        workspaceRegistry?: WorkspaceRegistryLike;
+        dshHomePath?: (...segments: string[]) => string;
+    }
+    /**
+     * dsh 的 durability checkpoint 事件（core/session Events，包只做结构声明）：
+     * 缓冲事件落盘时触发，插件用它做 flush 驱动的变更发现（M5，见 sync/engine
+     * requestScan）。真实载荷是 Session 对象，插件只关心触发时机。
+     */
+    interface Events {
+        'session/flush'(session: {
+            id: string;
+        }): void;
+    }
+}

package/lib/dsh-types.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * dsh-cloud-sync Host 半入口：settings 注册、state 打开、kdf 引导、引擎生命周期。
+ * 同步逻辑全部在 ./sync/engine.ts，这里只做与 cordis 的接线。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, StatusConfig, type Config as ConfigT } from './config.js';
+export declare const name = "cloud-sync";
+export declare const inject: string[];
+export { Config, StatusConfig };
+export declare function configKey(cfg: ConfigT): string;
+export declare function apply(ctx: Context, config: ConfigT): Promise<() => Promise<void>>;