dscs-server 0.0.0-stage → 0.1.0

package/dist/shared/batches.js

@@ -0,0 +1,230 @@
+import { sha256 } from './crypto.js';
+import { stableStringify } from './chain.js';
+import { openSealedFrame, sealFrame } from './sealed-frame.js';
+export const HEADER_INDEX = 0;
+export const HEADER_SEQ = -1;
+export const DEFAULT_BATCH_EVENTS = 50;
+export const DEFAULT_BATCH_BYTES = 256 * 1024;
+export function headerMetaOf(header, inheritedEventCount) {
+    return {
+        formatVersion: header.version,
+        createdAt: header.createdAt,
+        isSeeded: header.isSeeded,
+        delegationDepth: header.delegationDepth ?? 0,
+        ...header.agentPreset === undefined ? {} : {
+            agentPreset: header.agentPreset
+        },
+        ...header.parentSession === undefined ? {} : {
+            parentSession: header.parentSession
+        },
+        ...header.origin === undefined ? {} : {
+            origin: header.origin
+        },
+        ...header.isSeeded ? {
+            inheritedEventCount: inheritedEventCount ?? 0
+        } : {}
+    };
+}
+export function headerChainHash(meta) {
+    return sha256(stableStringify(meta));
+}
+export function sealHeader(meta, sessionId, sessionKey, compression = 'none') {
+    const plain = Buffer.from(stableStringify(meta), 'utf8');
+    return sealFrame(plain, {
+        sessionId,
+        index: HEADER_INDEX,
+        seqFrom: HEADER_SEQ,
+        seqTo: HEADER_SEQ
+    }, sessionKey, compression === 'zstd' ? {
+        compression: 'zstd'
+    } : {});
+}
+export function openHeader(sealed, ref, sessionId, sessionKey) {
+    if (ref.index !== HEADER_INDEX || ref.seqFrom !== HEADER_SEQ || ref.seqTo !== HEADER_SEQ) {
+        throw new Error('第 0 个链条目不是会话头');
+    }
+    const plain = openSealedFrame(sealed, {
+        sessionId,
+        index: ref.index,
+        seqFrom: ref.seqFrom,
+        seqTo: ref.seqTo,
+        chainHash: ref.chainHash,
+        ...ref.compression === undefined ? {} : {
+            compression: ref.compression
+        },
+        ...ref.compressedHash === undefined ? {} : {
+            compressedHash: ref.compressedHash
+        }
+    }, sessionKey);
+    return parseHeaderMeta(JSON.parse(plain.toString('utf8')));
+}
+function parseEvents(value) {
+    if (!Array.isArray(value)) throw new Error('批次不是事件数组');
+    return value.map((entry, position)=>{
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) throw new Error(`批次第 ${position} 项不是事件对象`);
+        const seq = entry['seq'];
+        if (!Number.isSafeInteger(seq) || seq < 0) throw new Error(`批次第 ${position} 项的 seq 非法`);
+        return entry;
+    });
+}
+function parseHeaderMeta(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('会话头不是对象');
+    const record = value;
+    const formatVersion = record['formatVersion'];
+    const createdAt = record['createdAt'];
+    const isSeeded = record['isSeeded'];
+    const delegationDepth = record['delegationDepth'];
+    if (!Number.isSafeInteger(formatVersion) || formatVersion < 1) throw new Error('会话头 formatVersion 非法');
+    if (!Number.isSafeInteger(createdAt)) throw new Error('会话头 createdAt 非法');
+    if (typeof isSeeded !== 'boolean') throw new Error('会话头 isSeeded 非法');
+    if (!Number.isSafeInteger(delegationDepth) || delegationDepth < 0) throw new Error('会话头 delegationDepth 非法');
+    const stringField = (key)=>{
+        const field = record[key];
+        if (field === undefined) return undefined;
+        if (typeof field !== 'string') throw new Error(`会话头 ${key} 非法`);
+        return field;
+    };
+    const inherited = record['inheritedEventCount'];
+    if (inherited !== undefined && (!Number.isSafeInteger(inherited) || inherited < 0)) {
+        throw new Error('会话头 inheritedEventCount 非法');
+    }
+    const agentPreset = stringField('agentPreset');
+    const parentSession = stringField('parentSession');
+    const origin = stringField('origin');
+    return {
+        formatVersion: formatVersion,
+        createdAt: createdAt,
+        isSeeded,
+        delegationDepth: delegationDepth,
+        ...agentPreset === undefined ? {} : {
+            agentPreset
+        },
+        ...parentSession === undefined ? {} : {
+            parentSession
+        },
+        ...origin === undefined ? {} : {
+            origin
+        },
+        ...inherited === undefined ? {} : {
+            inheritedEventCount: inherited
+        }
+    };
+}
+export function serializeEventBatch(events) {
+    return stableStringify(events);
+}
+export function eventBatchHash(events) {
+    return sha256(serializeEventBatch(events));
+}
+export function sealEventBatchFromText(text, sessionId, index, seqFrom, seqTo, sessionKey, compression = 'none') {
+    if (index < 1) throw new Error('事件批次的链下标必须 >= 1');
+    if (seqFrom > seqTo) throw new Error('事件批次的 seq 区间非法');
+    return sealFrame(Buffer.from(text, 'utf8'), {
+        sessionId,
+        index,
+        seqFrom,
+        seqTo
+    }, sessionKey, compression === 'zstd' ? {
+        compression: 'zstd'
+    } : {});
+}
+export function sealEventBatch(events, sessionId, index, sessionKey, compression = 'none') {
+    if (index < 1) throw new Error('事件批次的链下标必须 >= 1');
+    if (events.length === 0) throw new Error('不能封空批次');
+    const seqFrom = events[0].seq;
+    const seqTo = events[events.length - 1].seq;
+    assertContiguous(events, seqFrom, seqTo);
+    return sealEventBatchFromText(serializeEventBatch(events), sessionId, index, seqFrom, seqTo, sessionKey, compression);
+}
+export function openEventBatch(sealed, ref, sessionId, sessionKey) {
+    const plain = openSealedFrame(sealed, {
+        sessionId,
+        index: ref.index,
+        seqFrom: ref.seqFrom,
+        seqTo: ref.seqTo,
+        chainHash: ref.chainHash,
+        ...ref.compression === undefined ? {} : {
+            compression: ref.compression
+        },
+        ...ref.compressedHash === undefined ? {} : {
+            compressedHash: ref.compressedHash
+        }
+    }, sessionKey);
+    const events = parseEvents(JSON.parse(plain.toString('utf8')));
+    if (events.length !== ref.seqTo - ref.seqFrom + 1) throw new Error('批次事件数与 seq 区间不符');
+    if (events.length === 0 || events[0].seq !== ref.seqFrom || events[events.length - 1].seq !== ref.seqTo) {
+        throw new Error('批次首尾 seq 与清单不符');
+    }
+    assertContiguous(events, ref.seqFrom, ref.seqTo);
+    return events;
+}
+function assertContiguous(events, seqFrom, seqTo) {
+    if (events.length !== seqTo - seqFrom + 1) throw new Error('事件数与 seq 区间不符');
+    events.forEach((event, offset)=>{
+        if (event.seq !== seqFrom + offset) throw new Error(`第 ${offset} 个事件的 seq 应为 ${seqFrom + offset}，实际是 ${event.seq}`);
+    });
+}
+export function* iterateEventBatches(events, startAfterSeq, options = {}, includeText = true) {
+    const maxEvents = options.maxEvents ?? DEFAULT_BATCH_EVENTS;
+    const maxBytes = options.maxBytes ?? DEFAULT_BATCH_BYTES;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) throw new Error('maxEvents 必须是正整数');
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error('maxBytes 必须是正整数');
+    events.forEach((event, offset)=>{
+        if (!Number.isSafeInteger(event.seq) || event.seq < 0) throw new Error(`第 ${offset} 个事件的 seq 非法`);
+        if (offset > 0 && events[offset - 1].seq + 1 !== event.seq) throw new Error(`事件 seq 不连续：${events[offset - 1].seq} -> ${event.seq}`);
+    });
+    const pending = events.filter((event)=>event.seq > startAfterSeq);
+    if (pending.length === 0) return;
+    if (pending[0].seq !== startAfterSeq + 1) throw new Error(`待传事件应从 ${startAfterSeq + 1} 开始，实际是 ${pending[0].seq}`);
+    let current = [];
+    let currentTexts = includeText ? [] : undefined;
+    let currentBytes = 2;
+    for (const event of pending){
+        const eventText = stableStringify(event);
+        const eventBytes = Buffer.byteLength(eventText, 'utf8');
+        const candidateBytes = current.length === 0 ? currentBytes + eventBytes : currentBytes + 1 + eventBytes;
+        const candidateLength = current.length + 1;
+        if (current.length > 0 && (candidateLength > maxEvents || candidateBytes > maxBytes)) {
+            yield {
+                seqFrom: current[0].seq,
+                seqTo: current[current.length - 1].seq,
+                events: current,
+                bytes: currentBytes,
+                text: currentTexts === undefined ? '' : `[${currentTexts.join(',')}]`
+            };
+            current = [
+                event
+            ];
+            currentTexts = includeText ? [
+                eventText
+            ] : undefined;
+            currentBytes = 2 + eventBytes;
+        } else {
+            current.push(event);
+            currentTexts?.push(eventText);
+            currentBytes = candidateBytes;
+        }
+    }
+    if (current.length > 0) {
+        yield {
+            seqFrom: current[0].seq,
+            seqTo: current[current.length - 1].seq,
+            events: current,
+            bytes: currentBytes,
+            text: currentTexts === undefined ? '' : `[${currentTexts.join(',')}]`
+        };
+    }
+}
+export function planEventBatches(events, startAfterSeq, options = {}) {
+    return [
+        ...iterateEventBatches(events, startAfterSeq, options, false)
+    ].map(({ seqFrom, seqTo, events: batchEvents, bytes })=>({
+            seqFrom,
+            seqTo,
+            events: batchEvents,
+            bytes
+        }));
+}
+
+
+//# sourceURL=batches.ts

package/dist/shared/blob-batch.js

@@ -0,0 +1,85 @@
+import { sha256 } from './crypto.js';
+export const BLOB_BATCH_CONTENT_TYPE = 'application/x-dsh-blob-batch';
+export const BLOB_BATCH_HEADER_BYTES = 12;
+export const BLOB_BATCH_ENTRY_HEADER_BYTES = 40;
+export const MAX_BATCH_BLOBS = 64;
+export const MAX_BATCH_BODY_BYTES = 8 * 1024 * 1024;
+export const MAX_BLOB_BYTES = 32 * 1024 * 1024;
+const MAGIC = Buffer.from('DSHB', 'ascii');
+const VERSION = 1;
+const KIND_TO_CODE = {
+    frame: 1,
+    attachment: 2,
+    vault: 3
+};
+const CODE_TO_KIND = {
+    1: 'frame',
+    2: 'attachment',
+    3: 'vault'
+};
+export function encodeBlobBatch(entries) {
+    if (entries.length < 1 || entries.length > MAX_BATCH_BLOBS) {
+        throw new Error(`批量 blob 条数必须在 1–${MAX_BATCH_BLOBS} 之间`);
+    }
+    let total = BLOB_BATCH_HEADER_BYTES;
+    for (const entry of entries){
+        if (entry.data.length === 0) throw new Error('批量 blob 不能包含空内容');
+        if (entry.data.length > MAX_BLOB_BYTES) throw new Error(`单个 blob 超过上限 ${MAX_BLOB_BYTES} 字节`);
+        total += BLOB_BATCH_ENTRY_HEADER_BYTES + entry.data.length;
+    }
+    if (total > MAX_BATCH_BODY_BYTES) throw new Error(`批量 blob 超过上限 ${MAX_BATCH_BODY_BYTES} 字节`);
+    const output = Buffer.allocUnsafe(total);
+    MAGIC.copy(output, 0);
+    output.writeUInt8(VERSION, 4);
+    output.writeUInt8(0, 5);
+    output.writeUInt16BE(0, 6);
+    output.writeUInt32BE(entries.length, 8);
+    let offset = BLOB_BATCH_HEADER_BYTES;
+    for (const entry of entries){
+        const digest = sha256(entry.data);
+        output.writeUInt8(KIND_TO_CODE[entry.kind], offset);
+        output.fill(0, offset + 1, offset + 4);
+        output.writeUInt32BE(entry.data.length, offset + 4);
+        Buffer.from(digest, 'hex').copy(output, offset + 8);
+        entry.data.copy(output, offset + BLOB_BATCH_ENTRY_HEADER_BYTES);
+        offset += BLOB_BATCH_ENTRY_HEADER_BYTES + entry.data.length;
+    }
+    return output;
+}
+export function decodeBlobBatch(bytes) {
+    if (bytes.length < BLOB_BATCH_HEADER_BYTES) throw new Error('批量 blob 头被截断');
+    if (!bytes.subarray(0, 4).equals(MAGIC)) throw new Error('不是 DSHB 批量 blob');
+    if (bytes.readUInt8(4) !== VERSION) throw new Error(`不支持的批量 blob 版本：${bytes.readUInt8(4)}`);
+    if (bytes.readUInt8(5) !== 0) throw new Error('批量 blob flags 非零');
+    if (bytes.readUInt16BE(6) !== 0) throw new Error('批量 blob reserved 非零');
+    const count = bytes.readUInt32BE(8);
+    if (count < 1 || count > MAX_BATCH_BLOBS) throw new Error(`批量 blob 条数非法：${count}`);
+    const entries = [];
+    let offset = BLOB_BATCH_HEADER_BYTES;
+    for(let index = 0; index < count; index += 1){
+        if (offset + BLOB_BATCH_ENTRY_HEADER_BYTES > bytes.length) throw new Error(`批量 blob 第 ${index} 条头被截断`);
+        const kind = CODE_TO_KIND[bytes.readUInt8(offset)];
+        if (kind === undefined) throw new Error(`批量 blob 第 ${index} 条类别非法`);
+        if (bytes.readUInt8(offset + 1) !== 0 || bytes.readUInt8(offset + 2) !== 0 || bytes.readUInt8(offset + 3) !== 0) {
+            throw new Error(`批量 blob 第 ${index} 条 reserved 非零`);
+        }
+        const length = bytes.readUInt32BE(offset + 4);
+        if (length === 0) throw new Error(`批量 blob 第 ${index} 条为空`);
+        if (length > MAX_BLOB_BYTES) throw new Error(`批量 blob 第 ${index} 条超过单 blob 上限`);
+        const start = offset + BLOB_BATCH_ENTRY_HEADER_BYTES;
+        const end = start + length;
+        if (end > bytes.length) throw new Error(`批量 blob 第 ${index} 条数据被截断`);
+        entries.push({
+            kind,
+            sha256: bytes.subarray(offset + 8, offset + 8 + 32).toString('hex'),
+            data: bytes.subarray(start, end)
+        });
+        offset = end;
+    }
+    if (offset !== bytes.length) throw new Error('批量 blob 尾部有多余字节');
+    if (bytes.length > MAX_BATCH_BODY_BYTES) throw new Error(`批量 blob 超过上限 ${MAX_BATCH_BODY_BYTES} 字节`);
+    return entries;
+}
+
+
+//# sourceURL=blob-batch.ts

package/dist/shared/chain.js

@@ -0,0 +1,152 @@
+import { sha256 } from './crypto.js';
+const HASH_PATTERN = /^[0-9a-f]{64}$/u;
+export function assertChain(chain) {
+    chain.forEach((frame, position)=>{
+        if (frame.index !== position) throw new Error(`第 ${position} 帧的下标是 ${frame.index}，链不连续`);
+        if (!HASH_PATTERN.test(frame.chainHash)) throw new Error(`第 ${position} 帧的 chainHash 不是 64 位十六进制`);
+        if (!Number.isSafeInteger(frame.seqFrom) || !Number.isSafeInteger(frame.seqTo)) throw new Error(`第 ${position} 帧的 seq 不是整数`);
+        if (position === 0) {
+            if (frame.seqFrom !== -1 || frame.seqTo !== -1) throw new Error('header 帧的 seq 必须是 -1');
+            return;
+        }
+        const previous = chain[position - 1];
+        if (frame.seqFrom < 0 || frame.seqTo < frame.seqFrom) throw new Error(`第 ${position} 帧的 seq 区间非法`);
+        if (previous.seqTo + 1 !== frame.seqFrom) {
+            throw new Error(`第 ${position} 帧的 seq 应从 ${previous.seqTo + 1} 开始，实际是 ${frame.seqFrom}`);
+        }
+    });
+}
+export function commonPrefix(local, remote) {
+    let index = 0;
+    while(index < local.length && index < remote.length && local[index].chainHash === remote[index].chainHash)index += 1;
+    return index;
+}
+export function diffChains(local, remote) {
+    assertChain(local);
+    assertChain(remote);
+    const common = commonPrefix(local, remote);
+    const pull = remote.slice(common);
+    const push = local.slice(common);
+    if (pull.length === 0 && push.length === 0) return {
+        status: 'equal',
+        common,
+        pull,
+        push
+    };
+    if (push.length === 0) return {
+        status: 'remote-ahead',
+        common,
+        pull,
+        push
+    };
+    if (pull.length === 0) return {
+        status: 'local-ahead',
+        common,
+        pull,
+        push
+    };
+    if (pull.length === 1 && push.length === 1 && pull[0].index === push[0].index) {
+        return {
+            status: 'tail-mismatch',
+            common,
+            pull,
+            push
+        };
+    }
+    return {
+        status: 'diverged',
+        common,
+        pull,
+        push
+    };
+}
+export function buildManifest(input) {
+    input.frames.forEach((frame, position)=>{
+        if (frame.index !== position) throw new Error(`manifest 第 ${position} 条的 index 是 ${frame.index}`);
+        if (!HASH_PATTERN.test(frame.chainHash) || !HASH_PATTERN.test(frame.blobSha256)) throw new Error(`manifest 第 ${position} 条的哈希非法`);
+        if (frame.sealedVersion < 1) throw new Error(`manifest 第 ${position} 条的封帧版本非法`);
+    });
+    const last = input.frames[input.frames.length - 1];
+    const lastSeq = last === undefined ? -1 : last.seqTo;
+    return {
+        sessionId: input.sessionId,
+        formatVersion: input.formatVersion,
+        createdAt: input.createdAt,
+        lastSeq,
+        ...input.workspaceKey === undefined ? {} : {
+            workspaceKey: input.workspaceKey
+        },
+        ...input.tailOpen === undefined ? {} : {
+            tailOpen: input.tailOpen
+        },
+        ...input.safeThroughSeq === undefined ? {} : {
+            safeThroughSeq: input.safeThroughSeq
+        },
+        frames: input.frames,
+        updatedAt: input.updatedAt
+    };
+}
+export function assertManifest(manifest) {
+    manifest.frames.forEach((frame, position)=>{
+        if (frame.index !== position) throw new Error(`manifest 第 ${position} 条的 index 是 ${frame.index}`);
+        if (!HASH_PATTERN.test(frame.chainHash) || !HASH_PATTERN.test(frame.blobSha256)) throw new Error(`manifest 第 ${position} 条的哈希非法`);
+        if (frame.compression === undefined) {
+            if (frame.sealedVersion !== 1 || frame.compressedHash !== undefined) throw new Error(`manifest 第 ${position} 条缺少压缩元数据`);
+        } else {
+            if (frame.compression !== 'zstd') throw new Error(`manifest 第 ${position} 条的压缩方式非法`);
+            if (frame.sealedVersion < 2) throw new Error(`manifest 第 ${position} 条的压缩帧版本非法`);
+            if (frame.compressedHash === undefined || !HASH_PATTERN.test(frame.compressedHash)) {
+                throw new Error(`manifest 第 ${position} 条的 compressedHash 非法`);
+            }
+        }
+    });
+    const last = manifest.frames[manifest.frames.length - 1];
+    if ((last === undefined ? -1 : last.seqTo) !== manifest.lastSeq) throw new Error('manifest 的 lastSeq 与最后一帧不一致');
+    const safe = manifest.safeThroughSeq ?? manifest.lastSeq;
+    if (!Number.isSafeInteger(safe) || safe < -1 || safe > manifest.lastSeq) throw new Error('manifest 的 safeThroughSeq 非法');
+    if (manifest.workspaceKey !== undefined && !/^[A-Za-z0-9_-]{16,64}$/u.test(manifest.workspaceKey)) {
+        throw new Error('manifest 的 workspaceKey 非法');
+    }
+    if (manifest.tailOpen !== undefined && typeof manifest.tailOpen !== 'boolean') throw new Error('manifest 的 tailOpen 非法');
+}
+function canonical(value) {
+    if (Array.isArray(value)) return value.map((entry)=>canonical(entry));
+    if (value !== null && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort())sorted[key] = canonical(value[key]);
+        return sorted;
+    }
+    return value;
+}
+export function stableStringify(value) {
+    return JSON.stringify(canonical(value));
+}
+export function manifestDigest(manifest) {
+    return sha256(stableStringify({
+        sessionId: manifest.sessionId,
+        formatVersion: manifest.formatVersion,
+        createdAt: manifest.createdAt,
+        lastSeq: manifest.lastSeq,
+        workspaceKey: manifest.workspaceKey ?? null,
+        tailOpen: manifest.tailOpen ?? null,
+        safeThroughSeq: manifest.safeThroughSeq ?? manifest.lastSeq,
+        frames: manifest.frames.map((frame)=>({
+                index: frame.index,
+                chainHash: frame.chainHash,
+                blobSha256: frame.blobSha256,
+                bytes: frame.bytes,
+                sealedVersion: frame.sealedVersion,
+                keyId: frame.keyId,
+                seqFrom: frame.seqFrom,
+                seqTo: frame.seqTo,
+                ...frame.compression === undefined ? {} : {
+                    compression: frame.compression,
+                    compressedHash: frame.compressedHash ?? null
+                }
+            })),
+        deletedAt: manifest.deletedAt ?? null
+    }));
+}
+
+
+//# sourceURL=chain.ts

package/dist/shared/crypto.js

@@ -0,0 +1,70 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, scrypt, scryptSync } from 'node:crypto';
+export const KEY_BYTES = 32;
+export const NONCE_BYTES = 12;
+export const TAG_BYTES = 16;
+export const SALT_BYTES = 16;
+export const SCRYPT = {
+    N: 1 << 15,
+    r: 8,
+    p: 1
+};
+export function newSalt() {
+    return randomBytes(SALT_BYTES);
+}
+export function deriveMasterKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, KEY_BYTES, {
+        ...SCRYPT,
+        maxmem: 128 * 1024 * 1024
+    });
+}
+export async function deriveMasterKeyAsync(passphrase, salt) {
+    return await new Promise((resolve, reject)=>{
+        scrypt(passphrase, salt, KEY_BYTES, {
+            ...SCRYPT,
+            maxmem: 128 * 1024 * 1024
+        }, (error, key)=>{
+            if (error !== null) reject(error);
+            else resolve(Buffer.from(key));
+        });
+    });
+}
+export function deriveSubkey(master, info) {
+    return Buffer.from(hkdfSync('sha256', master, Buffer.alloc(0), Buffer.from(info, 'utf8'), KEY_BYTES));
+}
+export function seal(key, plaintext, aad) {
+    const nonce = randomBytes(NONCE_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    cipher.setAAD(aad);
+    const body = Buffer.concat([
+        cipher.update(plaintext),
+        cipher.final()
+    ]);
+    return {
+        nonce,
+        ciphertext: Buffer.concat([
+            body,
+            cipher.getAuthTag()
+        ])
+    };
+}
+export function open(key, sealed, aad) {
+    if (sealed.ciphertext.length < TAG_BYTES) throw new Error('封装载荷比认证标签还短');
+    const body = sealed.ciphertext.subarray(0, sealed.ciphertext.length - TAG_BYTES);
+    const tag = sealed.ciphertext.subarray(sealed.ciphertext.length - TAG_BYTES);
+    const decipher = createDecipheriv('aes-256-gcm', key, sealed.nonce);
+    decipher.setAAD(aad);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([
+        decipher.update(body),
+        decipher.final()
+    ]);
+}
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+export function randomId(bytes = 16) {
+    return randomBytes(bytes).toString('hex');
+}
+
+
+//# sourceURL=crypto.ts

package/dist/shared/frames.js

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { zstdCompressSync, zstdDecompressSync } from 'node:zlib';
+export const ZSTD_MAGIC = Buffer.from([
+    0x28,
+    0xb5,
+    0x2f,
+    0xfd
+]);
+export function isZstd(buffer) {
+    return buffer.length >= 4 && buffer.subarray(0, 4).equals(ZSTD_MAGIC);
+}
+export function zstdFrameEnd(buffer, offset) {
+    if (offset + 5 > buffer.length || !buffer.subarray(offset, offset + 4).equals(ZSTD_MAGIC)) {
+        throw new Error(`offset ${offset} 处不是 zstd 帧`);
+    }
+    const descriptor = buffer[offset + 4];
+    if ((descriptor & 8) !== 0) throw new Error('zstd 帧声明了保留位');
+    const singleSegment = (descriptor & 32) !== 0;
+    const contentSizeBytes = [
+        singleSegment ? 1 : 0,
+        2,
+        4,
+        8
+    ][descriptor >>> 6];
+    let cursor = offset + 5 + (singleSegment ? 0 : 1) + [
+        0,
+        1,
+        2,
+        4
+    ][descriptor & 3] + contentSizeBytes;
+    let last = false;
+    while(!last){
+        if (cursor + 3 > buffer.length) throw new Error('zstd 块头被截断');
+        const header = buffer.readUIntLE(cursor, 3);
+        const type = header >>> 1 & 3;
+        if (type === 3) throw new Error('zstd 块声明了保留类型');
+        last = (header & 1) !== 0;
+        cursor += 3 + (type === 1 ? 1 : header >>> 3);
+        if (cursor > buffer.length) throw new Error('zstd 块被截断');
+    }
+    if ((descriptor & 4) !== 0) cursor += 4;
+    if (cursor > buffer.length) throw new Error('zstd 校验和被截断');
+    return cursor;
+}
+export function splitFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while(offset < buffer.length){
+        const end = zstdFrameEnd(buffer, offset);
+        frames.push(buffer.subarray(offset, end));
+        offset = end;
+    }
+    return frames;
+}
+export function decodeFrames(frames) {
+    return frames.map((frame)=>zstdDecompressSync(frame));
+}
+export function decodeLog(buffer) {
+    if (!isZstd(buffer)) return buffer.toString('utf8');
+    return Buffer.concat(decodeFrames(splitFrames(buffer))).toString('utf8');
+}
+export function splitRows(text) {
+    return text.split('\n').map((row)=>row.endsWith('\r') ? row.slice(0, -1) : row).filter((row)=>row.trim() !== '');
+}
+export function encodeLog(text, options = {}) {
+    const headerLines = options.headerLines ?? 1;
+    const rowsPerFrame = options.rowsPerFrame ?? 1;
+    const rows = splitRows(text);
+    if (rows.length === 0) return [];
+    const head = rows.slice(0, headerLines);
+    const frames = [
+        zstdCompressSync(Buffer.from(`${head.join('\n')}\n`, 'utf8'))
+    ];
+    let index = headerLines;
+    while(index < rows.length){
+        const chunk = rows.slice(index, index + rowsPerFrame);
+        frames.push(zstdCompressSync(Buffer.from(`${chunk.join('\n')}\n`, 'utf8')));
+        index += rowsPerFrame;
+    }
+    return frames;
+}
+export function joinFrames(frames) {
+    return Buffer.concat(frames);
+}
+export function hashFrame(frame) {
+    return createHash('sha256').update(frame).digest('hex');
+}
+export function readHeader(buffer) {
+    const text = isZstd(buffer) ? Buffer.concat(decodeFrames([
+        splitFrames(buffer)[0]
+    ])).toString('utf8') : buffer.toString('utf8');
+    const first = splitRows(text)[0];
+    if (first === undefined) throw new Error('会话日志为空');
+    const parsed = JSON.parse(first);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('会话日志 header 不是 JSON 对象');
+    }
+    return parsed;
+}
+
+
+//# sourceURL=frames.ts

package/dist/shared/index.js

@@ -0,0 +1,12 @@
+export * from './batches.js';
+export * from './blob-batch.js';
+export * from './chain.js';
+export * from './crypto.js';
+export * from './frames.js';
+export * from './protocol.js';
+export * from './sealed-frame.js';
+export * from './vault.js';
+export * from './wire.js';
+
+
+//# sourceURL=index.ts

package/dist/shared/protocol.js

@@ -0,0 +1,14 @@
+export const API_PREFIX = '/v2';
+export const PROTOCOL_VERSION = 3;
+export function errorBody(code, message) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message
+        }
+    };
+}
+
+
+//# sourceURL=protocol.ts