@korajs/sync 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,32 @@
-import { S as SyncMessage, a as SerializedOperation, W as WireFormat, b as SyncTransport, T as TransportOptions, c as TransportMessageHandler, d as TransportCloseHandler, e as TransportErrorHandler, Q as QueueStorage, f as SyncConfig, g as SyncStatusInfo, h as SyncState } from './transport-B5EFsr5F.cjs';
-export { A as AcknowledgmentMessage, E as ErrorMessage, H as HandshakeMessage, i as HandshakeResponseMessage, O as OperationBatchMessage, j as SYNC_STATES, k as SYNC_STATUSES, l as SyncScopeContext, m as SyncStatus, n as isAcknowledgmentMessage, o as isErrorMessage, p as isHandshakeMessage, q as isHandshakeResponseMessage, r as isOperationBatchMessage, s as isSyncMessage } from './transport-B5EFsr5F.cjs';
-import { VersionVector, Operation, KoraEventEmitter, TimeSource, ConnectionQuality } from '@korajs/core';
+import { S as SyncScopeMap, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig } from './transport-B-BIguq9.cjs';
+export { A as AcknowledgmentMessage, k as AwarenessStateWire, l as AwarenessUpdateMessage, E as EncryptedPayload, m as ErrorMessage, H as HandshakeMessage, n as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, o as SYNC_STATES, p as SYNC_STATUSES, q as ScopeViolationError, r as SyncEncryptionAlgorithm, s as SyncScopeContext, t as SyncStatus, u as isAcknowledgmentMessage, v as isAwarenessUpdateMessage, w as isErrorMessage, x as isHandshakeMessage, y as isHandshakeResponseMessage, z as isOperationBatchMessage, B as isSyncMessage } from './transport-B-BIguq9.cjs';
+import { Operation, VersionVector, TimeSource, SyncError, KoraEventEmitter, ConnectionQuality } from '@korajs/core';
+
+/**
+ * Check whether an operation matches the given scope map.
+ *
+ * Rules:
+ * - No scope map configured: operation is always in scope.
+ * - Collection not present in scope map: operation is out of scope.
+ * - Empty scope for a collection `{}`: no field restrictions, operation is in scope.
+ * - Scope has field/value pairs: all must match in the operation's data snapshot.
+ *
+ * For updates, the snapshot is built by merging `previousData` and `data` (data wins),
+ * which represents the record's state after the operation is applied.
+ *
+ * @param op - The operation to check
+ * @param scopeMap - Per-collection scope filters, or undefined for no filtering
+ * @returns true if the operation is within scope
+ */
+declare function operationMatchesScope(op: Operation, scopeMap: SyncScopeMap | undefined): boolean;
+/**
+ * Filter operations to only those matching the given scope map.
+ *
+ * @param operations - Array of operations to filter
+ * @param scopeMap - Per-collection scope filters
+ * @returns Operations that match the scope
+ */
+declare function filterOperationsByScope(operations: Operation[], scopeMap: SyncScopeMap | undefined): Operation[];
 
 /**
  * Result of applying a remote operation to the store.
@@ -229,6 +255,358 @@ declare class ChaosTransport implements SyncTransport {
     private flushReorderBuffer;
 }
 
+/**
+ * Configuration for the SyncMetricsCollector.
+ */
+interface MetricsCollectorConfig {
+    /** Number of RTT samples to keep for percentile calculations. Defaults to 100. */
+    rttWindowSize?: number;
+    /** Number of bandwidth samples to keep. Defaults to 20. */
+    bandwidthWindowSize?: number;
+    /** Interval in ms between periodic diagnostics emissions. Defaults to 5000. */
+    diagnosticsInterval?: number;
+    /** Injectable time source for deterministic testing. */
+    timeSource?: TimeSource;
+}
+
+/**
+ * Thrown when encryption of operation data fails.
+ */
+declare class EncryptionError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when decryption of operation data fails.
+ * This typically indicates a wrong key, tampered ciphertext, or corrupted data.
+ */
+declare class DecryptionError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Encrypts and decrypts operation `data` and `previousData` fields for
+ * end-to-end encryption in the sync layer.
+ *
+ * **Design principles:**
+ * - Only `data` and `previousData` are encrypted. Metadata (id, nodeId,
+ *   collection, timestamps, causalDeps, etc.) stays in cleartext so the
+ *   server can route, deduplicate, and order operations.
+ * - Each field encryption uses a unique random IV (12 bytes for AES-GCM),
+ *   ensuring that encrypting the same data twice produces different ciphertext.
+ * - Key rotation is supported via versioned keys. The key version is embedded
+ *   in the {@link EncryptedPayload} so the decryptor can select the correct key.
+ * - Unencrypted fields pass through during decryption (backward compatibility).
+ *
+ * @example
+ * ```typescript
+ * const encryptor = await SyncEncryptor.create({
+ *   enabled: true,
+ *   key: 'user-passphrase'
+ * })
+ *
+ * // Encrypt before sending
+ * const encrypted = await encryptor.encryptOperation(operation)
+ *
+ * // Decrypt after receiving
+ * const decrypted = await encryptor.decryptOperation(encrypted)
+ * ```
+ */
+declare class SyncEncryptor {
+    /**
+     * Map of key version -> VersionedKey. The current (latest) version is used
+     * for encryption. All versions are available for decryption (key rotation).
+     */
+    private readonly keys;
+    /** The current key version used for encryption. */
+    private currentVersion;
+    private constructor();
+    /**
+     * Creates a SyncEncryptor from a {@link SyncEncryptionConfig}.
+     *
+     * Derives the encryption key from the passphrase using PBKDF2. The key
+     * derivation is async because it uses the Web Crypto API.
+     *
+     * @param config - Encryption configuration with passphrase
+     * @param salt - Optional salt for deterministic key derivation (mainly for testing).
+     *              If omitted, a random salt is generated.
+     * @returns A configured SyncEncryptor instance
+     * @throws {EncryptionError} If configuration is invalid
+     * @throws {KeyDerivationError} If key derivation fails
+     */
+    static create(config: SyncEncryptionConfig, salt?: Uint8Array): Promise<SyncEncryptor>;
+    /**
+     * Creates a SyncEncryptor from pre-derived versioned keys.
+     *
+     * Use this when you need to support multiple key versions for key rotation,
+     * or when you have already derived the keys externally.
+     *
+     * @param versionedKeys - Array of versioned keys. The highest version is used for encryption.
+     * @returns A configured SyncEncryptor instance
+     * @throws {EncryptionError} If no keys are provided
+     */
+    static fromKeys(versionedKeys: VersionedKey[]): SyncEncryptor;
+    /**
+     * Add a new key version for key rotation.
+     *
+     * After adding, the new key becomes the current version used for encryption
+     * if its version number is higher than the current version. Previously-versioned
+     * keys remain available for decrypting older operations.
+     *
+     * @param key - The new versioned key to add
+     * @throws {EncryptionError} If the key version already exists
+     */
+    addKey(key: VersionedKey): void;
+    /**
+     * Get the current encryption key version number.
+     */
+    getCurrentKeyVersion(): number;
+    /**
+     * Encrypt an operation's `data` and `previousData` fields.
+     *
+     * Returns a new Operation with encrypted field values. The original
+     * operation is not mutated (operations are immutable).
+     *
+     * Fields that are null (e.g., delete operations) remain null.
+     *
+     * @param operation - The operation to encrypt
+     * @returns A new operation with encrypted data fields
+     * @throws {EncryptionError} If encryption fails
+     */
+    encryptOperation(operation: Operation): Promise<Operation>;
+    /**
+     * Decrypt an operation's `data` and `previousData` fields.
+     *
+     * Returns a new Operation with the original field values restored.
+     * The original operation is not mutated.
+     *
+     * If a field is null or not encrypted (no marker), it passes through unchanged.
+     * This enables mixed plaintext/encrypted operations during migration.
+     *
+     * @param operation - The operation to decrypt
+     * @returns A new operation with decrypted data fields
+     * @throws {DecryptionError} If decryption fails (wrong key, tampered data, unsupported version)
+     */
+    decryptOperation(operation: Operation): Promise<Operation>;
+    /**
+     * Encrypt a serialized operation's `data` and `previousData` fields.
+     *
+     * Same as {@link encryptOperation} but works with the wire-format
+     * {@link SerializedOperation} type used by the serializer.
+     *
+     * @param serialized - The serialized operation to encrypt
+     * @returns A new serialized operation with encrypted data fields
+     * @throws {EncryptionError} If encryption fails
+     */
+    encryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
+    /**
+     * Decrypt a serialized operation's `data` and `previousData` fields.
+     *
+     * Same as {@link decryptOperation} but works with the wire-format
+     * {@link SerializedOperation} type used by the serializer.
+     *
+     * @param serialized - The serialized operation to decrypt
+     * @returns A new serialized operation with decrypted data fields
+     * @throws {DecryptionError} If decryption fails
+     */
+    decryptSerializedOperation(serialized: SerializedOperation): Promise<SerializedOperation>;
+    /**
+     * Encrypt a batch of operations in parallel.
+     *
+     * @param operations - Operations to encrypt
+     * @returns New operations with encrypted data fields
+     */
+    encryptBatch(operations: Operation[]): Promise<Operation[]>;
+    /**
+     * Decrypt a batch of operations in parallel.
+     *
+     * @param operations - Operations to decrypt
+     * @returns New operations with decrypted data fields
+     */
+    decryptBatch(operations: Operation[]): Promise<Operation[]>;
+    /**
+     * Check if a field value contains an encrypted payload.
+     *
+     * @param field - An operation's `data` or `previousData` field
+     * @returns true if the field contains an encrypted payload
+     */
+    static isEncryptedPayload(field: Record<string, unknown> | null): boolean;
+    private encryptField;
+    private decryptField;
+}
+/**
+ * Check if a field value contains an encrypted payload.
+ *
+ * @param field - An operation's `data` or `previousData` field
+ * @returns true if the field contains an encrypted payload
+ */
+declare function isEncryptedPayload(field: Record<string, unknown> | null): boolean;
+
+/**
+ * Cursor position within a richtext field.
+ * Uses Yjs-compatible anchor/head positions for editor interop.
+ */
+interface AwarenessCursor {
+    /** Collection containing the record being edited */
+    collection: string;
+    /** ID of the record being edited */
+    recordId: string;
+    /** Field name of the richtext field */
+    field: string;
+    /** Cursor anchor position in Y.Text (start of selection) */
+    anchor: number;
+    /** Cursor head position in Y.Text (end of selection, same as anchor if no selection) */
+    head: number;
+}
+/**
+ * User identity information for presence display.
+ */
+interface AwarenessUser {
+    /** Display name of the user */
+    name: string;
+    /** Hex color for cursor/selection rendering (e.g. '#ff0000') */
+    color: string;
+    /** Optional avatar URL */
+    avatar?: string;
+}
+/**
+ * Per-client awareness state. Ephemeral -- not persisted, only shared with connected peers.
+ * Compatible with Yjs awareness protocol format for interop with existing editors.
+ */
+interface AwarenessState {
+    /** User identity information */
+    user: AwarenessUser;
+    /** Current cursor position, if any */
+    cursor?: AwarenessCursor;
+}
+/**
+ * Internal awareness message format used between AwarenessManager and transport layer.
+ */
+interface AwarenessMessage {
+    type: 'awareness';
+    /** Client ID of the sender */
+    clientId: number;
+    /** All known awareness states. null value means removal. */
+    states: Record<number, AwarenessState | null>;
+}
+/**
+ * Describes a change in awareness states.
+ * Emitted when remote clients update or remove their presence.
+ */
+interface AwarenessChange {
+    /** Client IDs whose states were added */
+    added: number[];
+    /** Client IDs whose states were updated */
+    updated: number[];
+    /** Client IDs whose states were removed */
+    removed: number[];
+}
+/**
+ * Cursor information for rendering in editors.
+ * This is the developer-facing type -- simplified from internal awareness state.
+ * Editor-agnostic: provides data that can be rendered by TipTap, ProseMirror, Quill, etc.
+ */
+interface CursorInfo {
+    /** Unique client ID */
+    clientId: number;
+    /** User display name */
+    userName: string;
+    /** Hex color for cursor rendering */
+    color: string;
+    /** Cursor anchor position (start of selection) */
+    anchor: number;
+    /** Cursor head position (end of selection) */
+    head: number;
+}
+
+/**
+ * Callback for awareness change events.
+ */
+type AwarenessChangeListener = (change: AwarenessChange) => void;
+/**
+ * Manages collaborative awareness state (cursor positions, user presence).
+ *
+ * Awareness is ephemeral -- states are never persisted, only shared with
+ * currently connected peers via the sync transport. This implements a
+ * lightweight protocol compatible with Yjs awareness semantics.
+ *
+ * Each AwarenessManager has a unique client ID and tracks both its own
+ * local state and all remote clients' states.
+ */
+declare class AwarenessManager {
+    /** Unique client ID for this instance */
+    readonly clientId: number;
+    private localState;
+    private readonly remoteStates;
+    private readonly listeners;
+    private readonly emitter;
+    private readonly timeoutMs;
+    private readonly lastUpdated;
+    private cleanupTimer;
+    private sendHandler;
+    private destroyed;
+    constructor(options?: {
+        clientId?: number;
+        emitter?: KoraEventEmitter;
+        timeoutMs?: number;
+    });
+    /**
+     * Set the local user's awareness state and broadcast to peers.
+     *
+     * @param state - The awareness state to share. Pass null to clear presence.
+     */
+    setLocalState(state: AwarenessState | null): void;
+    /**
+     * Get the local awareness state.
+     */
+    getLocalState(): AwarenessState | null;
+    /**
+     * Get all known awareness states (local + remote).
+     * Returns a new Map on each call.
+     */
+    getStates(): Map<number, AwarenessState>;
+    /**
+     * Handle an incoming awareness message from the transport.
+     * This processes remote state updates and notifies listeners.
+     */
+    handleRemoteMessage(message: AwarenessMessage): void;
+    /**
+     * Remove a specific remote client's awareness state.
+     * Called when the server notifies that a client has disconnected.
+     */
+    removeClient(clientId: number): void;
+    /**
+     * Register a handler for sending awareness messages through the transport.
+     * The sync engine calls this to wire outgoing awareness messages to the transport.
+     */
+    onSend(handler: (message: AwarenessMessage) => void): void;
+    /**
+     * Register a listener for awareness state changes.
+     * Returns an unsubscribe function.
+     */
+    on(_event: 'change', listener: AwarenessChangeListener): () => void;
+    /**
+     * Remove a specific change listener.
+     */
+    off(_event: 'change', listener: AwarenessChangeListener): void;
+    /**
+     * Start the cleanup timer that removes stale remote states.
+     * Called when the sync engine transitions to streaming state.
+     */
+    startCleanupTimer(): void;
+    /**
+     * Stop the cleanup timer.
+     */
+    stopCleanupTimer(): void;
+    /**
+     * Clean up all resources. After calling destroy(), the manager
+     * will no longer send or receive awareness updates.
+     * Broadcasts removal of local state before shutting down.
+     */
+    destroy(): void;
+    private cleanupStaleStates;
+    private notifyListeners;
+    private emitAwarenessEvent;
+}
+
 /**
  * A batch of operations taken from the queue for sending.
  */
@@ -317,6 +695,32 @@ interface SyncEngineOptions {
     emitter?: KoraEventEmitter;
     /** Queue storage for persistent outbound queue. Defaults to in-memory. */
     queueStorage?: QueueStorage;
+    /**
+     * Optional encryptor for end-to-end encryption.
+     * When provided, `data` and `previousData` fields of operations are encrypted
+     * before sending and decrypted after receiving. The server never sees plaintext data.
+     */
+    encryptor?: SyncEncryptor;
+    /** Optional configuration for the metrics collector. */
+    metricsConfig?: MetricsCollectorConfig;
+}
+/**
+ * Diagnostics snapshot for debugging and support.
+ */
+interface SyncDiagnostics {
+    state: SyncState;
+    status: SyncStatusInfo;
+    nodeId: string;
+    url: string;
+    schemaVersion: number;
+    lastSyncedAt: number | null;
+    lastSuccessfulPush: number | null;
+    lastSuccessfulPull: number | null;
+    conflicts: number;
+    pendingOperations: number;
+    hasInFlightBatch: boolean;
+    reconnecting: boolean;
+    timestamp: number;
 }
 /**
  * Core sync orchestrator. Manages the sync lifecycle:
@@ -334,13 +738,25 @@ declare class SyncEngine {
     private readonly emitter;
     private readonly outboundQueue;
     private readonly batchSize;
+    private readonly encryptor;
+    private readonly awarenessManager;
+    private readonly metricsCollector;
     private remoteVector;
     private lastSyncedAt;
+    private lastSuccessfulPush;
+    private lastSuccessfulPull;
+    private conflictCount;
     private currentBatch;
     private reconnecting;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
+    /**
+     * The effective scope for this sync session.
+     * Starts as the configured scopeMap. After handshake, may be replaced
+     * with the server-accepted scope (server is authoritative).
+     */
+    private activeScope;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
@@ -354,6 +770,9 @@ declare class SyncEngine {
     /**
      * Push a local operation to the outbound queue.
      * If streaming, flushes immediately.
+     *
+     * Operations outside the configured sync scope are silently skipped
+     * because they should remain local-only and not be sent to the server.
      */
     pushOperation(op: Operation): Promise<void>;
     /**
@@ -367,6 +786,21 @@ declare class SyncEngine {
      * Get the current developer-facing sync status.
      */
     getStatus(): SyncStatusInfo;
+    /**
+     * Record a merge conflict. Called by the merge-aware sync store
+     * to increment the conflict counter for status reporting.
+     */
+    recordConflict(): void;
+    /**
+     * Force an immediate reconnection attempt. If the engine is disconnected
+     * or in error state, restarts the sync. If already connected, no-op.
+     */
+    retryNow(): Promise<void>;
+    /**
+     * Export a diagnostics snapshot for debugging and support tickets.
+     * Contains connection state, timing info, and queue metrics.
+     */
+    exportDiagnostics(): SyncDiagnostics;
     /**
      * Get the current internal state (for testing).
      */
@@ -375,6 +809,29 @@ declare class SyncEngine {
      * Get the outbound queue (for testing).
      */
     getOutboundQueue(): OutboundQueue;
+    /**
+     * Update the sync scope map. Takes effect on the next connection attempt.
+     *
+     * When the scope changes (e.g., user switches organization), call this method
+     * then reconnect. The new scope will be sent in the handshake, and the server
+     * will send back data matching the new scope.
+     *
+     * Data that no longer matches the new scope is NOT deleted locally.
+     * It simply stops being synced.
+     *
+     * @param scopeMap - New per-collection scope filters, or undefined to remove scope
+     */
+    updateScope(scopeMap: SyncScopeMap | undefined): void;
+    /**
+     * Get the currently active scope map. Returns undefined if no scope is configured.
+     */
+    getActiveScope(): SyncScopeMap | undefined;
+    /**
+     * Get the awareness manager for collaborative presence.
+     * Use this to set local presence, observe remote collaborators,
+     * and track cursor positions in richtext fields.
+     */
+    getAwarenessManager(): AwarenessManager;
     private handleMessage;
     private handleHandshakeResponse;
     private sendDelta;
@@ -384,6 +841,7 @@ declare class SyncEngine {
     private handleError;
     private checkDeltaComplete;
     private flushQueue;
+    private handleAwarenessUpdate;
     private handleTransportClose;
     private handleTransportError;
     private transitionTo;
@@ -518,4 +976,57 @@ declare class ReconnectionManager {
     private wait;
 }
 
-export { type ApplyResult, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, SerializedOperation, SyncConfig, SyncEngine, type SyncEngineOptions, SyncMessage, SyncState, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, versionVectorToWire, wireToVersionVector };
+/**
+ * Thrown when key derivation fails.
+ */
+declare class KeyDerivationError extends SyncError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Generates a cryptographically random salt for PBKDF2 key derivation.
+ *
+ * @returns A random 32-byte Uint8Array
+ * @throws {KeyDerivationError} If crypto.getRandomValues is unavailable
+ */
+declare function generateSalt(): Uint8Array;
+/**
+ * Derives an AES-256-GCM encryption key from a passphrase using PBKDF2.
+ *
+ * Uses PBKDF2 with SHA-256 and 600,000 iterations (OWASP-recommended minimum)
+ * to derive a 256-bit key. The derived key is deterministic: the same passphrase
+ * and salt always produce the same key.
+ *
+ * @param passphrase - The user's passphrase (must be non-empty)
+ * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @returns The derived CryptoKey and the salt used
+ * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
+ *
+ * @example
+ * ```typescript
+ * // First time: derive key with a new salt
+ * const { key, salt } = await deriveKey('my-secure-passphrase')
+ *
+ * // Later: re-derive the same key using the stored salt
+ * const { key: sameKey } = await deriveKey('my-secure-passphrase', salt)
+ * ```
+ */
+declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
+    key: CryptoKey;
+    salt: Uint8Array;
+}>;
+/**
+ * Derives a versioned encryption key from a passphrase.
+ *
+ * Wraps {@link deriveKey} with a version number for key rotation support.
+ * When the passphrase changes, create a new versioned key with a higher
+ * version number.
+ *
+ * @param passphrase - The user's passphrase
+ * @param version - Key version number (must be a positive integer)
+ * @param salt - Optional salt bytes. If omitted, a random salt is generated.
+ * @returns A {@link VersionedKey} containing the key, version, and salt
+ * @throws {KeyDerivationError} If parameters are invalid or derivation fails
+ */
+declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
+
+export { type ApplyResult, type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DecryptionError, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncScopeMap, SyncState, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, deriveKey, deriveVersionedKey, filterOperationsByScope, generateSalt, isEncryptedPayload, operationMatchesScope, versionVectorToWire, wireToVersionVector };