@loro-dev/streams-crdt 0.14.1 → 0.15.1

package/dist/{stream-id-BuXMoCvo.d.ts → stream-id-CVCOLgSp.d.ts}

@@ -379,8 +379,7 @@ type TransportError =
 } | {
   readonly code: "payload_protection_error";
   readonly retryable: false;
-  readonly reason: "plaintext_forbidden" | "missing_read_key" | "decrypt_failed" | "invalid_envelope" | "wrong_payload_kind" | "encrypt_failed";
-  readonly keyId?: string;
+  readonly reason: PayloadProtectionFailureReason;
   readonly message: string;
 };
 interface WriteOnlyAppendResult<TVersion extends JsonObject> {
@@ -523,34 +522,74 @@ interface SnapshotCodec {
   readonly compress: SnapshotTransformHook;
   readonly decompress: SnapshotTransformHook;
 }
+type PayloadProtectionFailureReason = "plaintext_forbidden" | "missing_read_key" | "decrypt_failed" | "invalid_envelope" | "wrong_payload_kind" | "encrypt_failed";
 type PayloadProtectionReadPolicy = "encrypted-only" | "allow-plaintext";
 type PayloadProtectionWritePolicy = "encrypt" | "plaintext";
-type PayloadProtectionScope = string | {
-  readonly bucketId: string;
-  readonly streamId: string;
-};
-interface PayloadProtectionKey {
-  readonly id: string;
-  readonly key: CryptoKey | Uint8Array;
+/** Durable CRDT payload class authenticated by the protection boundary. */
+type PayloadProtectionKind = "update_batch" | "snapshot";
+/** Stable envelope context shared by provider-backed seal/open calls. */
+interface PayloadProtectionContext {
+  readonly protocol: "loro-streams-crdt-payload-protection";
+  readonly version: 2;
+  readonly kind: PayloadProtectionKind;
 }
-type PayloadProtectionKeyProvider = () => MaybePromise<readonly PayloadProtectionKey[]>;
-interface PayloadProtectionEncryptionOptions {
+interface PayloadProtectionSealInput {
+  readonly plaintext: Uint8Array;
+  readonly context: PayloadProtectionContext;
   /**
-   * Stable encryption context authenticated with every encrypted payload.
+   * Returns the exact AAD for the opaque authenticated header the provider
+   * will return.
    *
-   * Prefer bucket/stream identity or an application-stable string. Do not use
-   * a full gateway URL unless old encrypted bytes should become unreadable
-   * after host/proxy migration.
+   * Providers MUST pass their final header to this function exactly once
+   * before sealing and MUST authenticate the returned bytes. A provider may
+   * frame and append caller-owned room/application AAD before passing the
+   * combined value to its AEAD. streams-crdt deliberately does not know or
+   * derive that application identity.
    */
-  readonly scope: PayloadProtectionScope;
-  /** Key used for new encrypted writes. Required when writePolicy is "encrypt". */
-  readonly writeKey?: PayloadProtectionKey;
+  readonly additionalData: (header: Uint8Array) => Uint8Array;
+}
+interface PayloadProtectionSealResult {
+  /** Opaque authenticated provider header; limited to 512 bytes. */
+  readonly header: Uint8Array;
   /**
-   * Keys accepted for remote encrypted reads.
-   *
-   * When omitted, `writeKey` is also used as the only read key.
+   * Provider-defined sealed bytes. Nonces and authentication tags stay opaque
+   * to streams-crdt, so providers may use formats such as
+   * `nonce[24] || XChaCha20-Poly1305 ciphertext+tag`.
+   */
+  readonly sealed: Uint8Array;
+}
+interface PayloadProtectionOpenInput {
+  readonly sealed: Uint8Array;
+  /** Opaque authenticated provider header returned by the writer. */
+  readonly header: Uint8Array;
+  readonly context: PayloadProtectionContext;
+  /** Exact envelope AAD that the provider must authenticate. */
+  readonly additionalData: Uint8Array;
+}
+/**
+ * Caller-owned authenticated payload codec.
+ *
+ * streams-crdt owns only the versioned envelope, its fixed envelope AAD,
+ * placement at the framing boundary, and fail-closed policies. The provider
+ * owns the audited AEAD primitive, nonce generation, application/room AAD,
+ * current write-key selection, and historical key lookup.
+ */
+interface PayloadProtectionProvider {
+  /**
+   * Maximum `header.byteLength + sealed.byteLength - plaintext.byteLength`
+   * this provider can return. This lets streams-crdt batch without performing
+   * a speculative seal or consuming a nonce. The runtime rejects a seal that
+   * exceeds the declared bound.
    */
-  readonly readKeys?: readonly PayloadProtectionKey[] | PayloadProtectionKeyProvider;
+  readonly maxSealOverheadBytes: number;
+  seal(input: PayloadProtectionSealInput): MaybePromise<PayloadProtectionSealResult>;
+  open(input: PayloadProtectionOpenInput): MaybePromise<Uint8Array>;
+}
+/** Scope-free provider config suitable for direct repo/room forwarding. */
+interface PayloadProtectionProviderConfig {
+  readonly provider: PayloadProtectionProvider;
+  readonly readPolicy?: PayloadProtectionReadPolicy;
+  readonly writePolicy?: PayloadProtectionWritePolicy;
 }
 interface PayloadProtectionOptions {
   /**
@@ -562,14 +601,20 @@ interface PayloadProtectionOptions {
    * Local write policy. Defaults to "encrypt" when E2EE is provided.
    */
   readonly writePolicy?: PayloadProtectionWritePolicy;
-  readonly encryption?: PayloadProtectionEncryptionOptions;
+  /**
+   * Provider for protected writes and reads.
+   *
+   * The provider owns the opaque header used to resolve historical keys. A
+   * write-key transition is an application session boundary: drain pending
+   * appends, close this transport, then construct a replacement with the new
+   * finalized write epoch. streams-crdt does not invent that rekey barrier.
+   */
+  readonly provider?: PayloadProtectionProvider;
 }
 type E2eeReadPolicy = PayloadProtectionReadPolicy;
 type E2eeWritePolicy = PayloadProtectionWritePolicy;
-type E2eeScope = PayloadProtectionScope;
-type E2eeKey = PayloadProtectionKey;
-type E2eeKeyProvider = PayloadProtectionKeyProvider;
-type E2eeEncryptionOptions = PayloadProtectionEncryptionOptions;
+type E2eeProvider = PayloadProtectionProvider;
+type E2eeProviderConfig = PayloadProtectionProviderConfig;
 type E2eeOptions = PayloadProtectionOptions;
 /**
  * Active live subscription returned by `join()`.
@@ -798,7 +843,11 @@ interface EphemeralStreamCrdtOptions {
  * Each instance is bound to exactly one stream URL and one local CRDT adapter.
  */
 interface StreamsCrdtOptions<TVersion extends JsonObject> {
-  /** Full stream URL, typically built with `createStreamUrl()`. */
+  /**
+   * Full, opaque Durable Streams URL used for HTTP requests and cursor keys.
+   * Payload-protection providers own any separate application/room identity
+   * they authenticate; streams-crdt never parses this URL to derive AAD.
+   */
   readonly streamUrl: string;
   /** CRDT adapter for the local document or replica. */
   readonly adapter: CrdtAdapter<TVersion>;
@@ -861,11 +910,15 @@ interface StreamsCrdtOptions<TVersion extends JsonObject> {
    */
   readonly e2ee?: E2eeOptions;
   /**
-   * Deprecated alias for `e2ee`.
+   * Fail construction when `e2ee` is absent.
+   * Repo integrations can set this after enabling protection globally so a
+   * missing per-room config never becomes an implicit plaintext room.
    *
-   * Prefer `e2ee`. Passing both `e2ee` and `payloadProtection` is an error.
+   * This is a missing-config guard, not a policy override. An explicitly
+   * supplied config may still opt into `allow-plaintext` / `plaintext`, for
+   * example for the public write-only mode.
    */
-  readonly payloadProtection?: PayloadProtectionOptions;
+  readonly payloadProtectionRequired?: boolean;
   readonly snapshotUpload?: SnapshotUploadOptions;
   /** Optional origin pools for routing transport requests. */
   readonly shardUrls?: StreamsCrdtShardUrlsOptions;
@@ -1046,6 +1099,35 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   private disposeJoinState;
   private runInitialSyncWithDeadline;
   private startJoin;
+  /**
+   * Join-time salvage for a stream whose head cannot be fully applied
+   * (apply_incomplete at `up_to_date`, even after bootstrap): before the
+   * join surfaces the error, durably append everything this replica holds
+   * that the server does not.
+   *
+   * Why this exists: the dual-author wedge is usually two-sided — the stream
+   * is missing some author's ops, and a replica that HOLDS those ops (e.g.
+   * received out-of-band over a local data plane) may itself be unable to
+   * complete the join because of a second gap. The regular join-time export
+   * runs only AFTER a successful initial sync, so without this salvage such
+   * a replica can never publish the healing ops, and its own backlog from a
+   * previous process run stays local for as long as the stream stays
+   * poisoned.
+   *
+   * `error.appliedVersion` advances only from success spans, so
+   * `exportUpdates(appliedVersion)` is exactly "ops this replica holds that
+   * the server does not" — the failed initial sync already imported
+   * everything the server DOES have, so the delta cannot re-append
+   * server-known data. Cursor safety is untouched: the append is write-only
+   * style (producer-acked, no read catch-up, no durable-cursor save), and
+   * the retried initial sync re-derives its cursor from the server.
+   *
+   * Returns `true` when anything was durably appended; the caller then
+   * retries the initial sync once. Best-effort: a salvage failure logs and
+   * returns `false` so the original apply-incomplete error is what callers
+   * observe.
+   */
+  private salvageLocalBacklogOnIncompleteInitialSync;
   private syncOnce;
   private performInitialJoinSync;
   private createInitialCursor;
@@ -1160,6 +1242,12 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
    * `"error"` write status (with `lastWriteError` set) and then retries via
    * this flush's own backoff timer (`maybeScheduleWriteRetry`) — it does not
    * depend on a future local op to re-trigger the flush.
+   *
+   * While the cursor is incomplete (unresolved remote spans), the flush
+   * degrades to an append-only mode instead of pausing: batches still reach
+   * the server, but read progress, durable-cursor saves, and snapshot
+   * scheduling stay untouched. See the inline comment in the incomplete
+   * branch and specs/loro-pending.md "Local Append Rules".
    */
   private flushPendingLocal;
   /**
@@ -1265,33 +1353,16 @@ declare class LocalAppendFailedError extends Error {
 }
 //#endregion
 //#region src/payload-protection.d.ts
-type PayloadProtectionFailureReason = "plaintext_forbidden" | "missing_read_key" | "decrypt_failed" | "invalid_envelope" | "wrong_payload_kind" | "encrypt_failed";
 declare class PayloadProtectionError extends Error {
   readonly reason: PayloadProtectionFailureReason;
-  readonly keyId?: string;
-  constructor(reason: PayloadProtectionFailureReason, message: string, options?: {
-    readonly keyId?: string;
-    readonly cause?: unknown;
-  });
+  constructor(reason: PayloadProtectionFailureReason, message?: string);
 }
 //#endregion
 //#region src/stream-id.d.ts
 /**
- * Validates a stream id accepted by `createStreamUrl()`.
+ * Validates a Durable Streams stream id.
  */
 declare function isValidRillId(id: string): boolean;
-/**
- * Validates a bucket id accepted by `createStreamUrl()`.
- */
-declare function isValidBucketId(id: string): boolean;
-/**
- * Builds a Durable Streams HTTP URL for one `(bucketId, streamId)` pair.
- */
-declare function createStreamUrl(input: {
-  bucketId: string;
-  streamId: string;
-  baseUrl?: string;
-}): string;
 //#endregion
-export { WriteOnlyAppendResult as $, PayloadProtectionKeyProvider as A, StreamsAuthProvider as B, EphemeralStreamSubscription as C, LocalSyncStats as D, JsonValue as E, Result as F, TransportCreateStreamSuccess as G, StreamsCrdtShardUrlsOptions as H, SnapshotCodec as I, TransportJoinParams as J, TransportDeleteStreamSuccess as K, SnapshotTransformHook as L, PayloadProtectionReadPolicy as M, PayloadProtectionScope as N, PayloadProtectionEncryptionOptions as O, PayloadProtectionWritePolicy as P, TransportSyncSuccess as Q, SnapshotUploadOptions as R, EphemeralStreamJoinParams as S, JsonObject as T, TransportCatchupParams as U, StreamsCrdtOptions as V, TransportCatchupSuccess as W, TransportSnapshotUploadSuccess as X, TransportRoomStatus as Y, TransportSubscription as Z, E2eeReadPolicy as _, LocalAppendFailedError as a, RemoteCursor as at, EphemeralStreamAdaptor as b, CrdtAdapter as c, createInitialRemoteCursor as ct, CrdtUnresolvedSpan as d, BeforeRemoteCursorSaveContext as et, CrdtUpdateBatch as f, E2eeOptions as g, E2eeKeyProvider as h, PayloadProtectionError as i, IndexedDbRemoteCursorStoreOptions as it, PayloadProtectionOptions as j, PayloadProtectionKey as k, CrdtApplyOutcome as l, E2eeKey as m, isValidBucketId as n, InMemoryRemoteCursorStore as nt, EphemeralStreamCrdt as o, RemoteCursorSaveSource as ot, E2eeEncryptionOptions as p, TransportError as q, isValidRillId as r, IndexedDbRemoteCursorStore as rt, StreamsCrdt as s, RemoteCursorStore as st, createStreamUrl as t, BeforeRemoteCursorSaveHook as tt, CrdtApplyReturn as u, E2eeScope as v, IsolatedCrdtAdapter as w, EphemeralStreamCrdtOptions as x, E2eeWritePolicy as y, StreamsAuthContext as z };
-//# sourceMappingURL=stream-id-BuXMoCvo.d.ts.map
+export { WriteOnlyAppendResult as $, PayloadProtectionProviderConfig as A, StreamsAuthProvider as B, LocalSyncStats as C, PayloadProtectionOpenInput as D, PayloadProtectionKind as E, Result as F, TransportCreateStreamSuccess as G, StreamsCrdtShardUrlsOptions as H, SnapshotCodec as I, TransportJoinParams as J, TransportDeleteStreamSuccess as K, SnapshotTransformHook as L, PayloadProtectionSealInput as M, PayloadProtectionSealResult as N, PayloadProtectionOptions as O, PayloadProtectionWritePolicy as P, TransportSyncSuccess as Q, SnapshotUploadOptions as R, JsonValue as S, PayloadProtectionFailureReason as T, TransportCatchupParams as U, StreamsCrdtOptions as V, TransportCatchupSuccess as W, TransportSnapshotUploadSuccess as X, TransportRoomStatus as Y, TransportSubscription as Z, EphemeralStreamCrdtOptions as _, StreamsCrdt as a, RemoteCursor as at, IsolatedCrdtAdapter as b, CrdtApplyReturn as c, createInitialRemoteCursor as ct, E2eeOptions as d, BeforeRemoteCursorSaveContext as et, E2eeProvider as f, EphemeralStreamAdaptor as g, E2eeWritePolicy as h, EphemeralStreamCrdt as i, IndexedDbRemoteCursorStoreOptions as it, PayloadProtectionReadPolicy as j, PayloadProtectionProvider as k, CrdtUnresolvedSpan as l, E2eeReadPolicy as m, PayloadProtectionError as n, InMemoryRemoteCursorStore as nt, CrdtAdapter as o, RemoteCursorSaveSource as ot, E2eeProviderConfig as p, TransportError as q, LocalAppendFailedError as r, IndexedDbRemoteCursorStore as rt, CrdtApplyOutcome as s, RemoteCursorStore as st, isValidRillId as t, BeforeRemoteCursorSaveHook as tt, CrdtUpdateBatch as u, EphemeralStreamJoinParams as v, PayloadProtectionContext as w, JsonObject as x, EphemeralStreamSubscription as y, StreamsAuthContext as z };
+//# sourceMappingURL=stream-id-CVCOLgSp.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loro-dev/streams-crdt",
   "description": "Transport/runtime layer for synchronizing CRDT state over Durable Streams.",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "license": "MIT",
   "author": "Loro Team",
   "homepage": "https://streams.loro.dev",