@loro-dev/streams-crdt 0.6.1 → 0.7.0

package/dist/{stream-id-0dTFsiaO.js → stream-id-CbVwCS3g.js}

@@ -206,6 +206,127 @@ function computeRetryDelay(attempt, config = DEFAULT_RECONNECT_CONFIG) {
 	return applyJitter(base, jitterFraction);
 }
 //#endregion
+//#region src/deque.ts
+const DEFAULT_COMPACT_THRESHOLD = 64;
+const DEFAULT_MIN_CAPACITY = 16;
+var Deque = class {
+	buffer;
+	head = 0;
+	tail = 0;
+	compactThreshold;
+	minCapacity;
+	constructor(values, options = {}) {
+		this.compactThreshold = Math.max(1, options.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD);
+		this.minCapacity = Math.max(1, options.minCapacity ?? DEFAULT_MIN_CAPACITY);
+		const seed = values == null ? [] : Array.from(values);
+		this.buffer = seed.slice();
+		this.tail = seed.length;
+	}
+	get length() {
+		return this.tail - this.head;
+	}
+	isEmpty() {
+		return this.length === 0;
+	}
+	clear() {
+		this.buffer = [];
+		this.head = 0;
+		this.tail = 0;
+	}
+	peekFront() {
+		if (this.length === 0) return;
+		const value = this.buffer[this.head];
+		return value == null ? void 0 : value;
+	}
+	peekBack() {
+		if (this.length === 0) return;
+		const value = this.buffer[this.tail - 1];
+		return value == null ? void 0 : value;
+	}
+	at(index) {
+		const length = this.length;
+		if (length === 0) return;
+		let offset = index;
+		if (offset < 0) offset += length;
+		if (offset < 0 || offset >= length) return;
+		const value = this.buffer[this.head + offset];
+		return value == null ? void 0 : value;
+	}
+	pushBack(value) {
+		this.ensureBackCapacity();
+		this.buffer[this.tail] = value;
+		this.tail += 1;
+		return this.length;
+	}
+	pushFront(value) {
+		if (this.head === 0) this.recenter(1, 0);
+		this.head -= 1;
+		this.buffer[this.head] = value;
+		return this.length;
+	}
+	popFront() {
+		if (this.length === 0) return;
+		const value = this.buffer[this.head];
+		this.buffer[this.head] = null;
+		this.head += 1;
+		this.compactIfNeeded();
+		return value == null ? void 0 : value;
+	}
+	popBack() {
+		if (this.length === 0) return;
+		this.tail -= 1;
+		const value = this.buffer[this.tail];
+		this.buffer[this.tail] = null;
+		this.compactIfNeeded();
+		return value == null ? void 0 : value;
+	}
+	toArray() {
+		const out = [];
+		for (let i = this.head; i < this.tail; i += 1) out.push(this.buffer[i]);
+		return out;
+	}
+	*[Symbol.iterator]() {
+		for (let i = this.head; i < this.tail; i += 1) yield this.buffer[i];
+	}
+	ensureBackCapacity() {
+		if (this.tail < this.buffer.length) return;
+		if (this.head > 0) {
+			this.compactToFront();
+			if (this.tail < this.buffer.length) return;
+		}
+		this.recenter(0, 1);
+	}
+	recenter(extraFront, extraBack) {
+		const length = this.length;
+		const needed = length + extraFront + extraBack;
+		const currentCapacity = this.buffer.length;
+		let nextCapacity = Math.max(currentCapacity, this.minCapacity);
+		if (nextCapacity < needed) nextCapacity = Math.max(nextCapacity * 2, needed, this.minCapacity);
+		const free = nextCapacity - length;
+		const nextHead = Math.max(extraFront, Math.floor(free / 2));
+		const next = new Array(nextCapacity);
+		for (let i = 0; i < length; i += 1) next[nextHead + i] = this.buffer[this.head + i];
+		this.buffer = next;
+		this.head = nextHead;
+		this.tail = nextHead + length;
+	}
+	compactIfNeeded() {
+		const length = this.length;
+		if (length === 0) {
+			this.clear();
+			return;
+		}
+		if (this.head < this.compactThreshold || this.head < length) return;
+		this.compactToFront();
+	}
+	compactToFront() {
+		const length = this.length;
+		this.buffer = this.buffer.slice(this.head, this.tail);
+		this.head = 0;
+		this.tail = length;
+	}
+};
+//#endregion
 //#region src/items.ts
 const BINARY_CONTENT_TYPE = "application/octet-stream";
 function encodeItems(items) {
@@ -236,6 +357,290 @@ function decodeItems(payload) {
 	return out;
 }
 //#endregion
+//#region src/payload-protection.ts
+const MAGIC = new Uint8Array([
+	76,
+	83,
+	67,
+	69
+]);
+const ENVELOPE_VERSION = 1;
+const SUITE_AES_256_GCM = 1;
+const UPDATE_BATCH_KIND = 1;
+const SNAPSHOT_KIND = 2;
+const AES_GCM_NONCE_BYTES = 12;
+const HEADER_BYTES = 10;
+const AES_GCM_TAG_BITS = 128;
+const RAW_AES_256_KEY_BYTES = 32;
+const textEncoder$1 = new TextEncoder();
+const textDecoder = new TextDecoder();
+var PayloadProtectionError = class extends Error {
+	reason;
+	keyId;
+	constructor(reason, message, options = {}) {
+		super(message, options.cause == null ? void 0 : { cause: options.cause });
+		this.name = "PayloadProtectionError";
+		this.reason = reason;
+		this.keyId = options.keyId;
+	}
+};
+var PayloadProtectionRuntime = class {
+	readPolicy;
+	writePolicy;
+	scope;
+	writeKey;
+	readKeys;
+	importedWriteKey;
+	importedReadKeys = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.readPolicy = options.readPolicy;
+		this.writePolicy = options.writePolicy;
+		this.scope = options.scope;
+		this.writeKey = options.writeKey;
+		this.readKeys = options.readKeys;
+	}
+	async encodeUpdateItems(clearUpdates) {
+		if (this.writePolicy === "plaintext") return clearUpdates;
+		return [await this.encryptPayload("update_batch", encodeItems(clearUpdates))];
+	}
+	measureEncodedUpdateItemsByteLength(clearUpdates) {
+		if (this.writePolicy === "plaintext") return encodedItemsByteLength(clearUpdates);
+		const writeKey = this.writeKey;
+		if (writeKey == null || this.scope == null) throw new PayloadProtectionError("encrypt_failed", "E2EE write encryption requires encryption.writeKey and encryption.scope");
+		const clearBatchBytes = encodedItemsByteLength(clearUpdates);
+		const keyIdBytes = textEncoder$1.encode(writeKey.id);
+		if (keyIdBytes.byteLength === 0 || keyIdBytes.byteLength > 255) throw new PayloadProtectionError("encrypt_failed", "E2EE key id must be 1..255 UTF-8 bytes", { keyId: writeKey.id });
+		return 4 + (HEADER_BYTES + keyIdBytes.byteLength + AES_GCM_NONCE_BYTES + clearBatchBytes + AES_GCM_TAG_BITS / 8);
+	}
+	async decodeUpdateItems(wireItems) {
+		const out = [];
+		for (const item of wireItems) {
+			if (isEncryptedEnvelope(item)) {
+				const clearBatch = await this.decryptPayload("update_batch", item);
+				out.push(...decodeItems(clearBatch));
+				continue;
+			}
+			this.assertPlaintextAllowed("update batch");
+			out.push(item);
+		}
+		return out;
+	}
+	async encodeSnapshot(snapshot) {
+		if (this.writePolicy === "plaintext") return snapshot;
+		return await this.encryptPayload("snapshot", snapshot);
+	}
+	async decodeSnapshot(snapshot) {
+		if (isEncryptedEnvelope(snapshot)) return await this.decryptPayload("snapshot", snapshot);
+		this.assertPlaintextAllowed("snapshot");
+		return snapshot;
+	}
+	async encryptPayload(kind, plaintext) {
+		const writeKey = this.writeKey;
+		if (writeKey == null || this.scope == null) throw new PayloadProtectionError("encrypt_failed", "E2EE write encryption requires encryption.writeKey and encryption.scope");
+		try {
+			const key = await (this.importedWriteKey ??= importAesGcmKey(writeKey.key));
+			const nonce = createNonce();
+			return concatBytes(createEnvelopeHeader(kind, writeKey.id, nonce), new Uint8Array(await getSubtleCrypto().encrypt({
+				name: "AES-GCM",
+				iv: toArrayBuffer(nonce),
+				tagLength: AES_GCM_TAG_BITS,
+				additionalData: toArrayBuffer(createAad({
+					kind,
+					keyId: writeKey.id,
+					scope: this.scope
+				}))
+			}, key, toArrayBuffer(plaintext))));
+		} catch (error) {
+			if (error instanceof PayloadProtectionError) throw error;
+			throw new PayloadProtectionError("encrypt_failed", "failed to encrypt streams-crdt payload", {
+				keyId: writeKey.id,
+				cause: error
+			});
+		}
+	}
+	async decryptPayload(expectedKind, envelope) {
+		const parsed = parseEnvelope(envelope);
+		if (parsed.kind !== expectedKind) throw new PayloadProtectionError("wrong_payload_kind", `expected ${expectedKind} payload, got ${parsed.kind}`, { keyId: parsed.keyId });
+		if (this.scope == null) throw new PayloadProtectionError("missing_read_key", "E2EE read decryption requires encryption.scope", { keyId: parsed.keyId });
+		const key = await this.getReadKey(parsed.keyId);
+		try {
+			return new Uint8Array(await getSubtleCrypto().decrypt({
+				name: "AES-GCM",
+				iv: toArrayBuffer(parsed.nonce),
+				tagLength: AES_GCM_TAG_BITS,
+				additionalData: toArrayBuffer(createAad({
+					kind: parsed.kind,
+					keyId: parsed.keyId,
+					scope: this.scope
+				}))
+			}, key, toArrayBuffer(parsed.ciphertext)));
+		} catch (error) {
+			throw new PayloadProtectionError("decrypt_failed", "failed to decrypt streams-crdt payload", {
+				keyId: parsed.keyId,
+				cause: error
+			});
+		}
+	}
+	async getReadKey(keyId) {
+		const cached = this.importedReadKeys.get(keyId);
+		if (cached != null) return await cached;
+		const imported = importAesGcmKey((await this.resolveReadKey(keyId)).key);
+		this.importedReadKeys.set(keyId, imported);
+		return await imported;
+	}
+	async resolveReadKey(keyId) {
+		for (const key of await this.resolveReadKeys()) if (key.id === keyId) return key;
+		throw new PayloadProtectionError("missing_read_key", `missing read key for protected streams-crdt payload '${keyId}'`, { keyId });
+	}
+	async resolveReadKeys() {
+		const readKeys = typeof this.readKeys === "function" ? await this.readKeys() : this.readKeys;
+		if (readKeys != null) return readKeys;
+		return this.writeKey == null ? [] : [this.writeKey];
+	}
+	assertPlaintextAllowed(label) {
+		if (this.readPolicy === "allow-plaintext") return;
+		throw new PayloadProtectionError("plaintext_forbidden", `received plaintext streams-crdt ${label} while readPolicy is encrypted-only`);
+	}
+};
+function normalizePayloadProtection(options, label = "payloadProtection") {
+	if (options == null) return;
+	const readPolicy = options.readPolicy ?? "encrypted-only";
+	const writePolicy = options.writePolicy ?? "encrypt";
+	if (readPolicy !== "encrypted-only" && readPolicy !== "allow-plaintext") throw new Error(`${label}.readPolicy must be encrypted-only or allow-plaintext`);
+	if (writePolicy !== "encrypt" && writePolicy !== "plaintext") throw new Error(`${label}.writePolicy must be encrypt or plaintext`);
+	const encryption = options.encryption;
+	if (encryption != null && encryption.scope == null) throw new Error(`${label}.encryption.scope is required when encryption is configured`);
+	if (writePolicy === "encrypt" && encryption?.writeKey == null) throw new Error(`${label}.encryption.writeKey is required when writePolicy is encrypt`);
+	if (writePolicy === "encrypt" && encryption?.scope == null) throw new Error(`${label}.encryption.scope is required when writePolicy is encrypt`);
+	validateKey(encryption?.writeKey, `${label}.encryption.writeKey`);
+	const readKeys = normalizeReadKeys(encryption?.readKeys, `${label}.encryption.readKeys`);
+	return new PayloadProtectionRuntime({
+		readPolicy,
+		writePolicy,
+		scope: encryption?.scope,
+		writeKey: encryption?.writeKey,
+		readKeys
+	});
+}
+function isPayloadProtectionError(error) {
+	return error instanceof PayloadProtectionError;
+}
+function isEncryptedEnvelope(payload) {
+	return payload.byteLength >= MAGIC.byteLength && MAGIC.every((byte, index) => payload[index] === byte);
+}
+function createEnvelopeHeader(kind, keyId, nonce) {
+	const keyIdBytes = textEncoder$1.encode(keyId);
+	if (keyIdBytes.byteLength === 0 || keyIdBytes.byteLength > 255) throw new PayloadProtectionError("encrypt_failed", "E2EE key id must be 1..255 UTF-8 bytes", { keyId });
+	if (nonce.byteLength !== AES_GCM_NONCE_BYTES) throw new PayloadProtectionError("encrypt_failed", `AES-GCM nonce must be ${AES_GCM_NONCE_BYTES} bytes`, { keyId });
+	const header = new Uint8Array(HEADER_BYTES + keyIdBytes.byteLength + nonce.byteLength);
+	header.set(MAGIC, 0);
+	header[4] = ENVELOPE_VERSION;
+	header[5] = encodeKind(kind);
+	header[6] = SUITE_AES_256_GCM;
+	header[7] = keyIdBytes.byteLength;
+	header[8] = nonce.byteLength;
+	header[9] = 0;
+	header.set(keyIdBytes, HEADER_BYTES);
+	header.set(nonce, HEADER_BYTES + keyIdBytes.byteLength);
+	return header;
+}
+function parseEnvelope(payload) {
+	if (!isEncryptedEnvelope(payload) || payload.byteLength < HEADER_BYTES) throw new PayloadProtectionError("invalid_envelope", "invalid streams-crdt encrypted payload envelope");
+	const version = payload[4];
+	const suite = payload[6];
+	const keyIdLen = payload[7] ?? 0;
+	const nonceLen = payload[8] ?? 0;
+	const reserved = payload[9];
+	if (version !== ENVELOPE_VERSION || suite !== SUITE_AES_256_GCM || nonceLen !== AES_GCM_NONCE_BYTES || reserved !== 0) throw new PayloadProtectionError("invalid_envelope", "unsupported streams-crdt encrypted payload envelope");
+	const kind = decodeKind(payload[5]);
+	const keyIdStart = HEADER_BYTES;
+	const nonceStart = keyIdStart + keyIdLen;
+	const ciphertextStart = nonceStart + nonceLen;
+	if (keyIdLen === 0 || payload.byteLength <= ciphertextStart) throw new PayloadProtectionError("invalid_envelope", "truncated streams-crdt encrypted payload envelope");
+	return {
+		kind,
+		keyId: textDecoder.decode(payload.slice(keyIdStart, nonceStart)),
+		nonce: payload.slice(nonceStart, ciphertextStart),
+		ciphertext: payload.slice(ciphertextStart)
+	};
+}
+function encodeKind(kind) {
+	return kind === "update_batch" ? UPDATE_BATCH_KIND : SNAPSHOT_KIND;
+}
+function decodeKind(encoded) {
+	if (encoded === UPDATE_BATCH_KIND) return "update_batch";
+	if (encoded === SNAPSHOT_KIND) return "snapshot";
+	throw new PayloadProtectionError("invalid_envelope", "unsupported streams-crdt encrypted payload kind");
+}
+function createNonce() {
+	const nonce = new Uint8Array(AES_GCM_NONCE_BYTES);
+	getCrypto().getRandomValues(nonce);
+	return nonce;
+}
+function createAad(input) {
+	return textEncoder$1.encode(JSON.stringify({
+		keyId: input.keyId,
+		kind: input.kind,
+		protocol: "loro-streams-crdt-payload-protection",
+		scope: normalizeScope(input.scope),
+		suite: "aes_256_gcm",
+		version: ENVELOPE_VERSION
+	}));
+}
+function normalizeScope(scope) {
+	return typeof scope === "string" ? scope : `bucket:${scope.bucketId}\nstream:${scope.streamId}`;
+}
+function concatBytes(left, right) {
+	const out = new Uint8Array(left.byteLength + right.byteLength);
+	out.set(left);
+	out.set(right, left.byteLength);
+	return out;
+}
+function encodedItemsByteLength(items) {
+	return items.reduce((sum, item) => sum + 4 + item.byteLength, 0);
+}
+async function importAesGcmKey(key) {
+	if (isCryptoKey(key)) return key;
+	validateRawKey(key);
+	return await getSubtleCrypto().importKey("raw", toArrayBuffer(key), "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+function toArrayBuffer(bytes) {
+	return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function validateKey(key, label) {
+	if (key == null) return;
+	if (key.id.trim().length === 0) throw new Error(`${label}.id must be non-empty`);
+	if (key.key instanceof Uint8Array) validateRawKey(key.key);
+}
+function normalizeReadKeys(readKeys, label) {
+	if (readKeys == null) return;
+	if (typeof readKeys === "function") return async () => {
+		const resolved = await readKeys();
+		validateKeys(resolved, label);
+		return resolved;
+	};
+	validateKeys(readKeys, label);
+	return readKeys;
+}
+function validateKeys(keys, label) {
+	for (const [index, key] of keys.entries()) validateKey(key, `${label}[${index}]`);
+}
+function isCryptoKey(key) {
+	return typeof CryptoKey !== "undefined" && key instanceof CryptoKey;
+}
+function validateRawKey(key) {
+	if (key.byteLength !== RAW_AES_256_KEY_BYTES) throw new Error(`E2EE raw AES-GCM keys must be ${RAW_AES_256_KEY_BYTES} bytes`);
+}
+function getCrypto() {
+	if (globalThis.crypto == null) throw new PayloadProtectionError("encrypt_failed", "Web Crypto is unavailable in this runtime");
+	return globalThis.crypto;
+}
+function getSubtleCrypto() {
+	const subtle = getCrypto().subtle;
+	if (subtle == null) throw new PayloadProtectionError("encrypt_failed", "SubtleCrypto is unavailable in this runtime");
+	return subtle;
+}
+//#endregion
 //#region src/transport-internal.ts
 function createProducerId() {
 	if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
@@ -382,6 +787,12 @@ function classifyFetchError(err) {
 		retriable: true,
 		atMs: Date.now()
 	};
+	if (isPayloadProtectionError(err)) return {
+		code: "protocol",
+		message: err.message,
+		retriable: false,
+		atMs: Date.now()
+	};
 	return {
 		code: "internal",
 		message,
@@ -430,6 +841,13 @@ function toTransportError(error) {
 		retryable: true,
 		message: error.message
 	};
+	if (isPayloadProtectionError(error)) return {
+		code: "payload_protection_error",
+		retryable: false,
+		reason: error.reason,
+		keyId: error.keyId,
+		message: error.message
+	};
 	if (error instanceof TypeError) return {
 		code: "network_error",
 		retryable: true,
@@ -782,16 +1200,19 @@ var StreamsTransportClient = class {
 var TransportCursorManager = class {
 	adapter;
 	decodeSnapshot;
+	decodeUpdateItems;
 	saveRemoteCursor;
 	constructor(options) {
 		this.adapter = options.adapter;
 		this.decodeSnapshot = options.decodeSnapshot;
+		this.decodeUpdateItems = options.decodeUpdateItems;
 		this.saveRemoteCursor = options.saveRemoteCursor;
 	}
 	async applyBootstrapPayload(cursor, snapshot, updates, nextOffset) {
 		let nextVersion = cursor.serverLowerBoundVersion;
 		if (snapshot.byteLength > 0) nextVersion = await this.adapter.applySnapshot(this.decodeSnapshot == null ? snapshot : await this.decodeSnapshot(snapshot));
-		if (updates.length > 0) nextVersion = await this.adapter.applyRemoteUpdates([...updates], nextVersion);
+		const clearUpdates = await this.decodeRemoteUpdateItems(updates);
+		if (clearUpdates.length > 0) nextVersion = await this.adapter.applyRemoteUpdates(clearUpdates, nextVersion);
 		return await this.finalizeCursor({
 			...cursor,
 			nextOffset,
@@ -811,8 +1232,9 @@ var TransportCursorManager = class {
 	async applyLiveResult(cursor, requestOffset, result, onRemoteVersionApplied) {
 		const previousVersion = cursor.serverLowerBoundVersion;
 		let nextVersion = previousVersion;
-		if (result.updates.length > 0) {
-			nextVersion = await this.adapter.applyRemoteUpdates([...result.updates], nextVersion);
+		const clearUpdates = await this.decodeRemoteUpdateItems(result.updates);
+		if (clearUpdates.length > 0) {
+			nextVersion = await this.adapter.applyRemoteUpdates(clearUpdates, nextVersion);
 			await onRemoteVersionApplied?.(previousVersion, nextVersion);
 		}
 		return await this.finalizeCursor({
@@ -824,8 +1246,9 @@ var TransportCursorManager = class {
 	async applyRemotePayload(cursor, updates, nextOffset, source, onRemoteVersionApplied) {
 		const previousVersion = cursor.serverLowerBoundVersion;
 		let nextVersion = previousVersion;
-		if (updates.length > 0) {
-			nextVersion = await this.adapter.applyRemoteUpdates([...updates], nextVersion);
+		const clearUpdates = await this.decodeRemoteUpdateItems(updates);
+		if (clearUpdates.length > 0) {
+			nextVersion = await this.adapter.applyRemoteUpdates(clearUpdates, nextVersion);
 			await onRemoteVersionApplied?.(previousVersion, nextVersion);
 		}
 		return await this.finalizeCursor({
@@ -837,126 +1260,9 @@ var TransportCursorManager = class {
 	async finalizeCursor(cursor, source) {
 		return await this.saveRemoteCursor(cursor, source);
 	}
-};
-//#endregion
-//#region src/deque.ts
-const DEFAULT_COMPACT_THRESHOLD = 64;
-const DEFAULT_MIN_CAPACITY = 16;
-var Deque = class {
-	buffer;
-	head = 0;
-	tail = 0;
-	compactThreshold;
-	minCapacity;
-	constructor(values, options = {}) {
-		this.compactThreshold = Math.max(1, options.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD);
-		this.minCapacity = Math.max(1, options.minCapacity ?? DEFAULT_MIN_CAPACITY);
-		const seed = values == null ? [] : Array.from(values);
-		this.buffer = seed.slice();
-		this.tail = seed.length;
-	}
-	get length() {
-		return this.tail - this.head;
-	}
-	isEmpty() {
-		return this.length === 0;
-	}
-	clear() {
-		this.buffer = [];
-		this.head = 0;
-		this.tail = 0;
-	}
-	peekFront() {
-		if (this.length === 0) return;
-		const value = this.buffer[this.head];
-		return value == null ? void 0 : value;
-	}
-	peekBack() {
-		if (this.length === 0) return;
-		const value = this.buffer[this.tail - 1];
-		return value == null ? void 0 : value;
-	}
-	at(index) {
-		const length = this.length;
-		if (length === 0) return;
-		let offset = index;
-		if (offset < 0) offset += length;
-		if (offset < 0 || offset >= length) return;
-		const value = this.buffer[this.head + offset];
-		return value == null ? void 0 : value;
-	}
-	pushBack(value) {
-		this.ensureBackCapacity();
-		this.buffer[this.tail] = value;
-		this.tail += 1;
-		return this.length;
-	}
-	pushFront(value) {
-		if (this.head === 0) this.recenter(1, 0);
-		this.head -= 1;
-		this.buffer[this.head] = value;
-		return this.length;
-	}
-	popFront() {
-		if (this.length === 0) return;
-		const value = this.buffer[this.head];
-		this.buffer[this.head] = null;
-		this.head += 1;
-		this.compactIfNeeded();
-		return value == null ? void 0 : value;
-	}
-	popBack() {
-		if (this.length === 0) return;
-		this.tail -= 1;
-		const value = this.buffer[this.tail];
-		this.buffer[this.tail] = null;
-		this.compactIfNeeded();
-		return value == null ? void 0 : value;
-	}
-	toArray() {
-		const out = [];
-		for (let i = this.head; i < this.tail; i += 1) out.push(this.buffer[i]);
-		return out;
-	}
-	*[Symbol.iterator]() {
-		for (let i = this.head; i < this.tail; i += 1) yield this.buffer[i];
-	}
-	ensureBackCapacity() {
-		if (this.tail < this.buffer.length) return;
-		if (this.head > 0) {
-			this.compactToFront();
-			if (this.tail < this.buffer.length) return;
-		}
-		this.recenter(0, 1);
-	}
-	recenter(extraFront, extraBack) {
-		const length = this.length;
-		const needed = length + extraFront + extraBack;
-		const currentCapacity = this.buffer.length;
-		let nextCapacity = Math.max(currentCapacity, this.minCapacity);
-		if (nextCapacity < needed) nextCapacity = Math.max(nextCapacity * 2, needed, this.minCapacity);
-		const free = nextCapacity - length;
-		const nextHead = Math.max(extraFront, Math.floor(free / 2));
-		const next = new Array(nextCapacity);
-		for (let i = 0; i < length; i += 1) next[nextHead + i] = this.buffer[this.head + i];
-		this.buffer = next;
-		this.head = nextHead;
-		this.tail = nextHead + length;
-	}
-	compactIfNeeded() {
-		const length = this.length;
-		if (length === 0) {
-			this.clear();
-			return;
-		}
-		if (this.head < this.compactThreshold || this.head < length) return;
-		this.compactToFront();
-	}
-	compactToFront() {
-		const length = this.length;
-		this.buffer = this.buffer.slice(this.head, this.tail);
-		this.head = 0;
-		this.tail = length;
+	async decodeRemoteUpdateItems(items) {
+		if (items.length === 0) return [];
+		return this.decodeUpdateItems == null ? [...items] : await this.decodeUpdateItems(items);
 	}
 };
 //#endregion
@@ -1102,7 +1408,8 @@ function createJoinState(cursor, liveMode = "sse") {
 		liveMode,
 		snapshot: createTransportSnapshotState(),
 		started: Promise.resolve(),
-		syncWaiters: []
+		syncWaiters: [],
+		initialSyncFailed: false
 	};
 }
 async function disposeJoinState(state, options) {
@@ -1113,6 +1420,7 @@ async function disposeJoinState(state, options) {
 	const unsubscribeLocal = state.unsubscribeLocal;
 	state.unsubscribeLocal = void 0;
 	requestController?.abort();
+	state.retrySleepController.abort();
 	unsubscribeLocal?.();
 	const disposedError = /* @__PURE__ */ new Error("subscription closed");
 	for (const waiter of state.syncWaiters.splice(0)) waiter.reject(disposedError);
@@ -1132,6 +1440,10 @@ var StreamsCrdt = class StreamsCrdt {
 	cursorManager;
 	volatileCursorManager;
 	decodeSnapshot;
+	encodeSnapshot;
+	decodeUpdateItems;
+	encodeUpdateItems;
+	measureUpdateItemsByteLength;
 	reconnectConfig;
 	debug;
 	beforeRemoteCursorSave;
@@ -1139,6 +1451,10 @@ var StreamsCrdt = class StreamsCrdt {
 	producerId = createProducerId();
 	producerEpoch = 0;
 	nextProducerSeq = 0;
+	pendingWriteOnly = new Deque();
+	writeOnlyCursor;
+	unsubscribeWriteOnlyLocal;
+	writeOnlyDisabledReason;
 	joinState;
 	opQueue = Promise.resolve();
 	/**
@@ -1163,8 +1479,17 @@ var StreamsCrdt = class StreamsCrdt {
 		this.debug = options.debug ?? false;
 		this.beforeRemoteCursorSave = composeBeforeRemoteCursorSaveHooks(options.beforeRemoteCursorSave, ...options.beforeRemoteCursorSaveHooks ?? []);
 		const snapshotCodec = normalizeSnapshotCodec(options.snapshotCodec);
+		if (options.e2ee != null && options.payloadProtection != null) throw new Error("Specify only one of e2ee or payloadProtection");
+		const payloadProtectionOption = options.e2ee ?? options.payloadProtection;
+		const payloadProtectionLabel = options.e2ee != null ? "e2ee" : "payloadProtection";
+		const payloadProtection = normalizePayloadProtection(payloadProtectionOption, payloadProtectionLabel);
+		if (payloadProtection?.writePolicy === "plaintext" && options.snapshotUpload != null && options.snapshotUpload.enabled !== false) throw new Error(`snapshotUpload is not supported when ${payloadProtectionLabel}.writePolicy is plaintext`);
 		const snapshotUploadConfig = normalizeSnapshotUploadConfig(options.snapshotUpload);
-		this.decodeSnapshot = snapshotCodec?.decompress;
+		this.decodeSnapshot = this.composeSnapshotDecoder(payloadProtection, snapshotCodec?.decompress);
+		this.encodeSnapshot = this.composeSnapshotEncoder(payloadProtection, snapshotCodec?.compress);
+		this.decodeUpdateItems = payloadProtection == null ? void 0 : (items) => payloadProtection.decodeUpdateItems(items);
+		this.encodeUpdateItems = payloadProtection == null ? void 0 : (updates) => payloadProtection.encodeUpdateItems(updates);
+		this.measureUpdateItemsByteLength = payloadProtection == null ? void 0 : (updates) => payloadProtection.measureEncodedUpdateItemsByteLength(updates);
 		this.client = new StreamsTransportClient({
 			streamUrl: this.streamUrl,
 			adapter: this.adapter,
@@ -1177,7 +1502,7 @@ var StreamsCrdt = class StreamsCrdt {
 		this.snapshotManager = new TransportSnapshotManager({
 			adapter: this.adapter,
 			config: snapshotUploadConfig,
-			encodeSnapshot: snapshotCodec?.compress,
+			encodeSnapshot: this.encodeSnapshot,
 			readSnapshotOffsetValue: () => this.client.readSnapshotOffsetValue(),
 			putSnapshotAt: (snapshotOffset, snapshot) => this.client.putSnapshotAt(snapshotOffset, snapshot),
 			enqueueExclusive: (task) => this.enqueueExclusive(task),
@@ -1185,11 +1510,31 @@ var StreamsCrdt = class StreamsCrdt {
 			logError: (message, error, detail) => this.logError(message, error, detail),
 			isCurrentState: (state) => this.joinState === state
 		});
+		this.writeOnlyCursor = this.createInitialCursor();
+		this.unsubscribeWriteOnlyLocal = this.adapter.subscribeLocalUpdates((batch) => {
+			if (this.writeOnlyDisabledReason != null) return;
+			this.pendingWriteOnly.pushBack(batch);
+		});
+	}
+	composeSnapshotDecoder(payloadProtection, decompressSnapshot) {
+		if (payloadProtection == null && decompressSnapshot == null) return;
+		return async (snapshot) => {
+			const clearSnapshot = payloadProtection == null ? snapshot : await payloadProtection.decodeSnapshot(snapshot);
+			return decompressSnapshot == null ? clearSnapshot : await decompressSnapshot(clearSnapshot);
+		};
+	}
+	composeSnapshotEncoder(payloadProtection, compressSnapshot) {
+		if (payloadProtection == null && compressSnapshot == null) return;
+		return async (snapshot) => {
+			const compressedSnapshot = compressSnapshot == null ? snapshot : await compressSnapshot(snapshot);
+			return payloadProtection == null ? compressedSnapshot : await payloadProtection.encodeSnapshot(compressedSnapshot);
+		};
 	}
 	/**
 	* Stops any active live join and releases transport-owned state.
 	*/
 	async close() {
+		this.disableWriteOnlyMode("transport closed");
 		const state = this.joinState;
 		if (state != null) await this.disposeJoinState(state);
 	}
@@ -1206,7 +1551,27 @@ var StreamsCrdt = class StreamsCrdt {
 	rejoin() {
 		const state = this.joinState;
 		if (state == null || state.closed) return;
-		if (state.readSubStatus === "ok" && state.writeSubStatus === "ok") return;
+		if (state.initialSyncFailed) {
+			state.initialSyncFailed = false;
+			state.lastError = void 0;
+			state.retryAttempt = 0;
+			state.retrySleepController.abort();
+			state.retrySleepController = new AbortController();
+			state.readSubStatus = "connecting";
+			state.writeSubStatus = "ok";
+			this.recomputeJoinStatus(state);
+			state.started = this.startJoin(state);
+			state.started.catch((error) => {
+				if (state.closed) return;
+				const transportError = toTransportError(error);
+				if (transportError.retryable) {
+					state.initialSyncFailed = true;
+					state.lastError = transportError;
+				} else this.disposeJoinState(state);
+			});
+			return;
+		}
+		if ((state.readSubStatus === "ok" || state.readSubStatus === "connecting") && state.writeSubStatus === "ok") return;
 		state.retryAttempt = 0;
 		state.retrySleepController.abort();
 		state.retrySleepController = new AbortController();
@@ -1240,6 +1605,33 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	/**
+	* Uploads a full adapter snapshot at the current remote tail.
+	*
+	* @internal Intended for end-to-end tests that must deterministically create
+	* a remote snapshot without waiting for the best-effort join() debounce.
+	*/
+	async uploadSnapshotForTesting() {
+		try {
+			await this.adapter.flushLocalExports?.();
+			const cursor = await this.syncOnce();
+			const rawSnapshot = this.adapter.exportSnapshot();
+			const snapshot = this.encodeSnapshot == null ? rawSnapshot : await this.encodeSnapshot(rawSnapshot);
+			await this.client.putSnapshotAt(cursor.nextOffset, snapshot);
+			return {
+				ok: true,
+				value: {
+					snapshotOffset: cursor.nextOffset,
+					snapshotByteLength: snapshot.byteLength
+				}
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: toTransportError(error)
+			};
+		}
+	}
+	/**
 	* Explicitly creates the target stream.
 	*/
 	async createStream() {
@@ -1283,6 +1675,7 @@ var StreamsCrdt = class StreamsCrdt {
 	*/
 	async sync() {
 		try {
+			this.disableWriteOnlyMode("appendWriteOnly cannot be used after sync() on the same transport");
 			return {
 				ok: true,
 				value: { cursor: await this.syncOnce() }
@@ -1295,27 +1688,75 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	/**
+	* Appends local CRDT updates without reading the stream first.
+	*
+	* Use this for write-only actors whose auth token may POST to the stream but
+	* may not bootstrap, catch up, or join live reads. The method does not save a
+	* RemoteCursorStore cursor and does not apply remote updates.
+	*/
+	async appendWriteOnly() {
+		return await this.enqueueExclusive(async () => {
+			try {
+				if (this.writeOnlyDisabledReason != null) throw new Error(this.writeOnlyDisabledReason);
+				await this.adapter.flushLocalExports?.();
+				const drained = await this.drainPendingWriteOnlyBatch();
+				if (drained == null) return {
+					ok: true,
+					value: {
+						appended: false,
+						localVersion: this.writeOnlyCursor.serverLowerBoundVersion
+					}
+				};
+				const nextCursor = await this.appendLocalBatch(this.writeOnlyCursor, drained.batch, false);
+				for (let i = 0; i < drained.count; i += 1) this.pendingWriteOnly.popFront();
+				this.writeOnlyCursor = nextCursor;
+				return {
+					ok: true,
+					value: {
+						appended: true,
+						nextOffset: nextCursor.nextOffset,
+						localVersion: nextCursor.serverLowerBoundVersion
+					}
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: toTransportError(error)
+				};
+			}
+		});
+	}
+	/**
 	* Replays remote state, flushes queued local updates, then enters live read mode.
 	*/
 	async join(params) {
+		this.disableWriteOnlyMode("appendWriteOnly cannot be used after join() on the same transport");
 		const existing = this.joinState;
-		if (existing != null) try {
-			await existing.started;
-			return {
+		if (existing != null) {
+			if (existing.initialSyncFailed && !existing.closed) return {
 				ok: true,
 				value: this.createSubscription(existing, params)
 			};
-		} catch (error) {
-			return {
-				ok: false,
-				error: toTransportError(error)
-			};
+			try {
+				await existing.started;
+				return {
+					ok: true,
+					value: this.createSubscription(existing, params)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: toTransportError(error)
+				};
+			}
 		}
 		const state = createJoinState(createInitialRemoteCursor({
 			streamUrl: this.streamUrl,
 			nextOffset: "-1",
 			serverLowerBoundVersion: this.adapter.emptyVersion()
 		}));
+		const statusListener = params?.onStatusChange;
+		if (statusListener != null) state.statusListeners.add(statusListener);
 		state.started = this.startJoin(state);
 		this.joinState = state;
 		try {
@@ -1325,10 +1766,20 @@ var StreamsCrdt = class StreamsCrdt {
 				value: this.createSubscription(state, params)
 			};
 		} catch (error) {
+			const transportError = toTransportError(error);
+			if (transportError.retryable && !state.closed) {
+				state.initialSyncFailed = true;
+				state.lastError = transportError;
+				if (statusListener != null) state.statusListeners.delete(statusListener);
+				return {
+					ok: false,
+					error: transportError
+				};
+			}
 			await this.disposeJoinState(state);
 			return {
 				ok: false,
-				error: toTransportError(error)
+				error: transportError
 			};
 		}
 	}
@@ -1336,8 +1787,10 @@ var StreamsCrdt = class StreamsCrdt {
 		state.refCount += 1;
 		const statusListener = params?.onStatusChange;
 		if (statusListener != null) {
-			state.statusListeners.add(statusListener);
-			statusListener(state.status);
+			if (!state.statusListeners.has(statusListener)) {
+				state.statusListeners.add(statusListener);
+				statusListener(state.status);
+			}
 		}
 		let unsubscribed = false;
 		return {
@@ -1353,7 +1806,10 @@ var StreamsCrdt = class StreamsCrdt {
 				return state.status === "joined";
 			},
 			get status() {
-				return state.status;
+				return state.status === "connecting" ? "reconnecting" : state.status;
+			},
+			get lastError() {
+				return state.lastError;
 			},
 			onStatusChange: (listener) => {
 				state.statusListeners.add(listener);
@@ -1363,6 +1819,20 @@ var StreamsCrdt = class StreamsCrdt {
 				};
 			},
 			waitUntilSynced: async () => {
+				if (state.initialSyncFailed) {
+					const msg = state.lastError?.code ? `initial sync failed: ${state.lastError.code}` : "initial sync failed";
+					throw new Error(msg);
+				}
+				if (state.readSubStatus === "connecting") try {
+					await state.started;
+				} catch (error) {
+					const te = toTransportError(error);
+					throw new Error(te.code ? `initial sync failed: ${te.code}` : "initial sync failed");
+				}
+				if (state.writeSubStatus === "error") {
+					const msg = state.lastError?.code ? `local append failed: ${state.lastError.code}` : "local append failed";
+					throw new Error(msg);
+				}
 				await this.adapter.flushLocalExports?.();
 				if (state.closed) throw new Error("subscription closed");
 				const remaining = state.pendingLocal.length;
@@ -1405,12 +1875,14 @@ var StreamsCrdt = class StreamsCrdt {
 				if (state.status === "error" || state.status === "disconnected") throw new Error("join local sync failed before subscription became ready");
 			}
 			if (state.closed) return;
+			state.lastError = void 0;
 			this.setReadSubStatus(state, "ok");
 			this.setWriteSubStatus(state, "ok");
 			this.runReadLoop(state);
 		} catch (error) {
 			if (state.closed) return;
 			this.snapshotManager.dispose(state);
+			state.lastError = toTransportError(error);
 			this.logError("join first sync failed", error, { streamUrl: this.streamUrl });
 			state.readSubStatus = "error";
 			state.writeSubStatus = "error";
@@ -1533,7 +2005,8 @@ var StreamsCrdt = class StreamsCrdt {
 		for (let attempt = 0; attempt < 3; attempt += 1) {
 			let result;
 			try {
-				result = await this.client.appendUpdates(batch.updates, producerSession);
+				const wireUpdates = this.encodeUpdateItems == null ? batch.updates : await this.encodeUpdateItems(batch.updates);
+				result = await this.client.appendUpdates(wireUpdates, producerSession);
 			} catch (error) {
 				if (isStreamNotFoundError(error) && this.createStreamIfMissing) {
 					await this.ensureStreamExists();
@@ -1597,6 +2070,7 @@ var StreamsCrdt = class StreamsCrdt {
 		return new TransportCursorManager({
 			adapter,
 			decodeSnapshot: this.decodeSnapshot,
+			decodeUpdateItems: this.decodeUpdateItems,
 			saveRemoteCursor
 		});
 	}
@@ -1718,6 +2192,9 @@ var StreamsCrdt = class StreamsCrdt {
 							}
 						});
 						this.setReadSubStatus(state, "ok");
+					}).catch((flushError) => {
+						this.logError("sse flush chain error", flushError, { streamUrl: this.streamUrl });
+						capturedController?.abort(flushError);
 					});
 				}, () => {
 					resetInactivity();
@@ -1738,10 +2215,12 @@ var StreamsCrdt = class StreamsCrdt {
 					continue;
 				}
 				if (sseResult.kind === "not-found") {
-					this.logError("live read failed", new HttpError("stream not found", 404), {
+					const notFoundError = new HttpError("stream not found", 404);
+					this.logError("live read failed", notFoundError, {
 						streamUrl: this.streamUrl,
 						code: "stream_not_found"
 					});
+					state.lastError = toTransportError(notFoundError);
 					this.setReadSubStatus(state, "error");
 					return;
 				}
@@ -1767,12 +2246,32 @@ var StreamsCrdt = class StreamsCrdt {
 								streamUrl: this.streamUrl,
 								attempts: state.retryAttempt
 							});
+							state.lastError = {
+								code: "timeout",
+								retryable: true,
+								phase: "poll",
+								message: "SSE inactivity timeout exhausted retry budget"
+							};
 							this.setReadSubStatus(state, "disconnected");
 							return;
 						}
 						state.retryAttempt += 1;
 						continue;
 					}
+					const abortReason = capturedController.signal.reason;
+					const flushError = abortReason instanceof Error ? abortReason : error;
+					if (flushError instanceof Error && !(flushError instanceof DOMException && flushError.name === "AbortError")) {
+						const flushClassified = classifyFetchError(flushError);
+						if (!flushClassified.retriable || isAuthOrProtocolError(flushError)) {
+							this.logError("live read failed (flush chain)", flushError, {
+								streamUrl: this.streamUrl,
+								code: flushClassified.code
+							});
+							state.lastError = toTransportError(flushError);
+							this.setReadSubStatus(state, "error");
+							return;
+						}
+					}
 					state.retryAttempt = 0;
 					this.setReadSubStatus(state, "reconnecting");
 					continue;
@@ -1783,6 +2282,7 @@ var StreamsCrdt = class StreamsCrdt {
 						streamUrl: this.streamUrl,
 						code: classified.code
 					});
+					state.lastError = toTransportError(error);
 					this.setReadSubStatus(state, "error");
 					return;
 				}
@@ -1793,6 +2293,7 @@ var StreamsCrdt = class StreamsCrdt {
 						streamUrl: this.streamUrl,
 						attempts: state.retryAttempt
 					});
+					state.lastError = toTransportError(error);
 					this.setReadSubStatus(state, "disconnected");
 					return;
 				}
@@ -1810,20 +2311,19 @@ var StreamsCrdt = class StreamsCrdt {
 	*
 	* Returns `undefined` when the queue is empty.
 	*/
-	drainPendingBatch(state) {
-		const first = state.pendingLocal.peekFront();
+	async drainQueuedBatch(pendingLocal) {
+		const first = pendingLocal.peekFront();
 		if (first == null) return;
 		const maxBytes = StreamsCrdt.MAX_BATCH_BYTES;
-		let totalBytes = first.updates.reduce((sum, u) => sum + 4 + u.byteLength, 0);
 		let mergedVersion = first.version;
 		const allUpdates = Array.from(first.updates);
 		let count = 1;
-		while (count < state.pendingLocal.length) {
-			const next = state.pendingLocal.at(count);
-			const nextBytes = next.updates.reduce((sum, u) => sum + 4 + u.byteLength, 0);
-			if (totalBytes + nextBytes > maxBytes) break;
+		await this.measureAppendBodyByteLength(allUpdates);
+		while (count < pendingLocal.length) {
+			const next = pendingLocal.at(count);
+			const candidateUpdates = [...allUpdates, ...next.updates];
+			if (await this.measureAppendBodyByteLength(candidateUpdates) > maxBytes) break;
 			allUpdates.push(...next.updates);
-			totalBytes += nextBytes;
 			mergedVersion = this.adapter.mergeVersions(mergedVersion, next.version);
 			count += 1;
 		}
@@ -1839,12 +2339,18 @@ var StreamsCrdt = class StreamsCrdt {
 			count
 		};
 	}
+	drainPendingBatch(state) {
+		return this.drainQueuedBatch(state.pendingLocal);
+	}
+	drainPendingWriteOnlyBatch() {
+		return this.drainQueuedBatch(this.pendingWriteOnly);
+	}
 	async flushPendingLocal(state) {
 		if (state.flushingLocal || state.closed) return;
 		state.flushingLocal = true;
 		try {
 			while (!state.closed) {
-				const drained = this.drainPendingBatch(state);
+				const drained = await this.drainPendingBatch(state);
 				if (drained == null) return;
 				let attempts = 0;
 				while (!state.closed) try {
@@ -1861,12 +2367,14 @@ var StreamsCrdt = class StreamsCrdt {
 							streamUrl: this.streamUrl,
 							code: classified.code
 						});
+						state.lastError = toTransportError(error);
 						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error(`local append failed: ${classified.code}`));
 						this.setWriteSubStatus(state, "error");
 						return;
 					}
 					const maxAttempts = this.reconnectConfig.maxAttempts;
 					if (attempts >= maxAttempts) {
+						state.lastError = toTransportError(error);
 						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error("local append retry budget exhausted"));
 						this.setWriteSubStatus(state, "error");
 						return;
@@ -1922,6 +2430,7 @@ var StreamsCrdt = class StreamsCrdt {
 		const status = this.computeOverallStatus(state);
 		if (state.status === status) return;
 		state.status = status;
+		if (status === "joined") state.lastError = void 0;
 		for (const listener of state.statusListeners) listener(status);
 	}
 	computeOverallStatus(state) {
@@ -1937,6 +2446,17 @@ var StreamsCrdt = class StreamsCrdt {
 		this.opQueue = run.then(() => void 0, () => void 0);
 		return run;
 	}
+	async measureAppendBodyByteLength(updates) {
+		if (this.measureUpdateItemsByteLength != null) return await this.measureUpdateItemsByteLength(updates);
+		return updates.reduce((sum, update) => sum + 4 + update.byteLength, 0);
+	}
+	disableWriteOnlyMode(reason) {
+		if (this.writeOnlyDisabledReason != null) return;
+		this.writeOnlyDisabledReason = reason;
+		this.pendingWriteOnly.clear();
+		this.unsubscribeWriteOnlyLocal?.();
+		this.unsubscribeWriteOnlyLocal = void 0;
+	}
 	logDebug(message, detail) {
 		if (!this.debug) return;
 		if (detail == null) {
@@ -1988,6 +2508,6 @@ function createStreamUrl(input) {
 	return `${baseUrl}/ds/${encodeURIComponent(input.bucketId)}/${encodeURIComponent(streamId)}`;
 }
 //#endregion
-export { InMemoryRemoteCursorStore as a, StreamsCrdt as i, isValidBucketId as n, IndexedDbRemoteCursorStore as o, isValidRillId as r, createInitialRemoteCursor as s, createStreamUrl as t };
+export { PayloadProtectionError as a, createInitialRemoteCursor as c, StreamsCrdt as i, isValidBucketId as n, InMemoryRemoteCursorStore as o, isValidRillId as r, IndexedDbRemoteCursorStore as s, createStreamUrl as t };
 
-//# sourceMappingURL=stream-id-0dTFsiaO.js.map
+//# sourceMappingURL=stream-id-CbVwCS3g.js.map