@korajs/sync 0.3.1 → 0.4.0

package/dist/transport-B-BIguq9.d.ts

@@ -0,0 +1,385 @@
+import { KoraError, Operation, OperationType, HLCTimestamp, AtomicOp } from '@korajs/core';
+
+/**
+ * Encryption types for the Kora.js sync layer.
+ *
+ * These types define the configuration and wire format for end-to-end
+ * encryption of operation data during sync. Only `data` and `previousData`
+ * fields are encrypted — metadata stays in cleartext for routing and ordering.
+ */
+/**
+ * Supported encryption algorithms. Currently only AES-256-GCM is supported,
+ * but the type is extensible for future algorithms.
+ */
+type SyncEncryptionAlgorithm = 'aes-256-gcm';
+/**
+ * Configuration for sync-layer encryption.
+ *
+ * When enabled, the sync engine encrypts `data` and `previousData` fields
+ * of every operation before sending over the wire. The server never sees
+ * plaintext user data.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp({
+ *   schema,
+ *   sync: {
+ *     url: 'wss://my-server.com/kora',
+ *     encryption: {
+ *       enabled: true,
+ *       key: 'my-secure-passphrase'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+interface SyncEncryptionConfig {
+    /** Whether encryption is enabled. When false, all other fields are ignored. */
+    enabled: boolean;
+    /**
+     * Passphrase or async key provider function.
+     *
+     * - If a string, used as a passphrase for PBKDF2 key derivation.
+     * - If a function, called to retrieve the passphrase (e.g., from a vault or user prompt).
+     */
+    key: string | (() => Promise<string>);
+    /**
+     * Encryption algorithm. Defaults to 'aes-256-gcm'.
+     * Currently only AES-256-GCM is supported.
+     */
+    algorithm?: SyncEncryptionAlgorithm;
+}
+/**
+ * Encrypted payload structure embedded in operation `data` and `previousData`
+ * fields when encryption is enabled.
+ *
+ * This structure replaces the original field values on the wire. The server
+ * stores and relays these opaque payloads without being able to read the
+ * plaintext contents.
+ */
+interface EncryptedPayload {
+    /** Encryption key version. Supports key rotation: older operations may use older key versions. */
+    v: number;
+    /** Base64-encoded initialization vector (12 bytes for AES-GCM). Unique per operation field. */
+    iv: string;
+    /** Base64-encoded ciphertext (AES-256-GCM output including authentication tag). */
+    ct: string;
+    /** Encryption algorithm identifier. */
+    alg: SyncEncryptionAlgorithm;
+}
+/**
+ * A versioned encryption key with its associated salt for key derivation.
+ *
+ * Key versions enable rotation: when the passphrase changes, a new key version
+ * is created. Operations encrypted with older key versions include their version
+ * number in the {@link EncryptedPayload}, allowing the decryptor to select the
+ * correct key.
+ */
+interface VersionedKey {
+    /** Key version number (monotonically increasing, starting at 1). */
+    version: number;
+    /** The derived CryptoKey for AES-256-GCM operations. */
+    key: CryptoKey;
+    /** The salt used during PBKDF2 key derivation. Required to re-derive the same key. */
+    salt: Uint8Array;
+}
+
+/**
+ * Internal sync engine states. Used for state machine transitions.
+ */
+declare const SYNC_STATES: readonly ["disconnected", "connecting", "handshaking", "syncing", "streaming", "error"];
+type SyncState = (typeof SYNC_STATES)[number];
+/**
+ * Developer-facing sync status. Simplified view of the internal state.
+ */
+declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error"];
+type SyncStatus = (typeof SYNC_STATUSES)[number];
+/**
+ * Sync status information exposed to developers.
+ */
+interface SyncStatusInfo {
+    /** Current developer-facing status */
+    status: SyncStatus;
+    /** Number of operations waiting to be sent */
+    pendingOperations: number;
+    /** Timestamp of last successful sync (null if never synced) */
+    lastSyncedAt: number | null;
+    /** Timestamp of last successful push to the server (null if never pushed) */
+    lastSuccessfulPush: number | null;
+    /** Timestamp of last successful pull from the server (null if never pulled) */
+    lastSuccessfulPull: number | null;
+    /** Number of merge conflicts encountered during this session */
+    conflicts: number;
+}
+/**
+ * Per-collection sync scope map. Maps collection names to field-value filters.
+ * Empty filter `{}` means no restriction (all records visible).
+ * Missing collection means hidden (no records visible for that collection).
+ */
+type SyncScopeMap = Record<string, Record<string, unknown>>;
+/**
+ * Sync configuration provided by the developer.
+ */
+interface SyncConfig {
+    /** WebSocket or HTTP URL for the sync server */
+    url: string;
+    /** Transport type to use. Defaults to 'websocket'. */
+    transport?: 'websocket' | 'http';
+    /** Auth provider function. Called before each connection attempt. */
+    auth?: () => Promise<{
+        token: string;
+    }>;
+    /** Sync scopes per collection. Limits which records sync to this client. */
+    scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
+    /**
+     * Pre-computed per-collection sync scope map. Sent to the server in the handshake.
+     * Built automatically by createApp from schema scope declarations + flat scope values.
+     */
+    scopeMap?: SyncScopeMap;
+    /** Number of operations per batch. Defaults to 100. */
+    batchSize?: number;
+    /** Initial reconnection delay in ms. Defaults to 1000. */
+    reconnectInterval?: number;
+    /** Maximum reconnection delay in ms. Defaults to 30000. */
+    maxReconnectInterval?: number;
+    /** Schema version of this client. */
+    schemaVersion?: number;
+    /**
+     * End-to-end encryption configuration.
+     * When enabled, `data` and `previousData` fields are encrypted before sending
+     * over the wire. The server never sees plaintext user data.
+     */
+    encryption?: SyncEncryptionConfig;
+}
+/**
+ * Context passed to sync scope functions.
+ */
+interface SyncScopeContext {
+    userId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Interface for persisting the outbound operation queue.
+ * Operations must survive page refreshes and be sent when connection is re-established.
+ */
+interface QueueStorage {
+    /** Load all queued operations from persistent storage */
+    load(): Promise<Operation[]>;
+    /** Persist an operation to the queue */
+    enqueue(op: Operation): Promise<void>;
+    /** Remove acknowledged operations by their IDs */
+    dequeue(ids: string[]): Promise<void>;
+    /** Return number of operations in storage */
+    count(): Promise<number>;
+}
+/**
+ * Thrown when an operation violates sync scope constraints.
+ * This can happen when:
+ * - A client tries to push an operation outside its configured scope
+ * - The server rejects an operation because it falls outside the client's scope
+ */
+declare class ScopeViolationError extends KoraError {
+    readonly operationId: string;
+    readonly collection: string;
+    readonly scope: Record<string, unknown>;
+    constructor(operationId: string, collection: string, scope: Record<string, unknown>, message?: string);
+}
+/**
+ * Thrown when a sync scope configuration is invalid.
+ */
+declare class InvalidScopeError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+type WireFormat = 'json' | 'protobuf';
+/**
+ * Wire-format operation. Plain object (no Map) for JSON serialization.
+ * Maps 1:1 with Operation, but uses Record instead of Map for version vectors.
+ */
+interface SerializedOperation {
+    id: string;
+    nodeId: string;
+    type: OperationType;
+    collection: string;
+    recordId: string;
+    data: Record<string, unknown> | null;
+    previousData: Record<string, unknown> | null;
+    timestamp: HLCTimestamp;
+    sequenceNumber: number;
+    causalDeps: string[];
+    schemaVersion: number;
+    /** Atomic operation intents, present only when atomic ops were used. */
+    atomicOps?: Record<string, AtomicOp>;
+    /** Groups this operation with others in an atomic transaction. */
+    transactionId?: string;
+    /** Human-readable name for the mutation group. For DevTools display. */
+    mutationName?: string;
+}
+/**
+ * Handshake message sent by client to initiate sync.
+ */
+interface HandshakeMessage {
+    type: 'handshake';
+    messageId: string;
+    nodeId: string;
+    /** Version vector as plain object (nodeId -> sequence number) */
+    versionVector: Record<string, number>;
+    schemaVersion: number;
+    authToken?: string;
+    supportedWireFormats?: WireFormat[];
+    /** Per-collection sync scope filters. Limits which records are synced to this client. */
+    syncScope?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Server response to a handshake.
+ */
+interface HandshakeResponseMessage {
+    type: 'handshake-response';
+    messageId: string;
+    nodeId: string;
+    versionVector: Record<string, number>;
+    schemaVersion: number;
+    accepted: boolean;
+    rejectReason?: string;
+    selectedWireFormat?: WireFormat;
+    /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
+    acceptedScope?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Batch of operations sent during delta exchange or streaming.
+ */
+interface OperationBatchMessage {
+    type: 'operation-batch';
+    messageId: string;
+    operations: SerializedOperation[];
+    /** True if this is the last batch in the delta exchange phase */
+    isFinal: boolean;
+    /** Index of this batch (0-based) for ordering */
+    batchIndex: number;
+}
+/**
+ * Acknowledgment of a received message.
+ */
+interface AcknowledgmentMessage {
+    type: 'acknowledgment';
+    messageId: string;
+    acknowledgedMessageId: string;
+    lastSequenceNumber: number;
+}
+/**
+ * Error message from the server or client.
+ */
+interface ErrorMessage {
+    type: 'error';
+    messageId: string;
+    code: string;
+    message: string;
+    retriable: boolean;
+}
+/**
+ * Awareness state for a single client (cursor position, user info).
+ * Wire-format representation for JSON transport.
+ * Ephemeral -- not persisted, only shared with connected peers.
+ */
+interface AwarenessStateWire {
+    user: {
+        name: string;
+        color: string;
+        avatar?: string;
+    };
+    cursor?: {
+        collection: string;
+        recordId: string;
+        field: string;
+        anchor: number;
+        head: number;
+    };
+}
+/**
+ * Awareness update message. Carries ephemeral presence data (cursors, user info).
+ * Processed separately from operation sync -- never persisted.
+ */
+interface AwarenessUpdateMessage {
+    type: 'awareness-update';
+    messageId: string;
+    /** Client ID of the sender */
+    clientId: number;
+    /** Map of clientId -> state (null means removal) */
+    states: Record<string, AwarenessStateWire | null>;
+}
+/**
+ * Union of all sync protocol messages.
+ */
+type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage;
+/**
+ * Check if an unknown value is a valid SyncMessage.
+ */
+declare function isSyncMessage(value: unknown): value is SyncMessage;
+/**
+ * Check if a value is a HandshakeMessage.
+ */
+declare function isHandshakeMessage(value: unknown): value is HandshakeMessage;
+/**
+ * Check if a value is a HandshakeResponseMessage.
+ */
+declare function isHandshakeResponseMessage(value: unknown): value is HandshakeResponseMessage;
+/**
+ * Check if a value is an OperationBatchMessage.
+ */
+declare function isOperationBatchMessage(value: unknown): value is OperationBatchMessage;
+/**
+ * Check if a value is an AcknowledgmentMessage.
+ */
+declare function isAcknowledgmentMessage(value: unknown): value is AcknowledgmentMessage;
+/**
+ * Check if a value is an ErrorMessage.
+ */
+declare function isErrorMessage(value: unknown): value is ErrorMessage;
+/**
+ * Check if a value is an AwarenessUpdateMessage.
+ */
+declare function isAwarenessUpdateMessage(value: unknown): value is AwarenessUpdateMessage;
+
+/**
+ * Options for transport connection.
+ */
+interface TransportOptions {
+    /** Authentication token sent during connection */
+    authToken?: string;
+    /** Additional headers (for HTTP-based transports) */
+    headers?: Record<string, string>;
+}
+/**
+ * Transport-level error handler.
+ */
+type TransportErrorHandler = (error: Error) => void;
+/**
+ * Transport-level close handler.
+ */
+type TransportCloseHandler = (reason: string) => void;
+/**
+ * Transport-level message handler.
+ */
+type TransportMessageHandler = (message: SyncMessage) => void;
+/**
+ * Abstract transport interface for sync communication.
+ * Implementations can use WebSocket, HTTP, Bluetooth, or any other transport.
+ */
+interface SyncTransport {
+    /** Connect to the sync server at the given URL */
+    connect(url: string, options?: TransportOptions): Promise<void>;
+    /** Disconnect from the server */
+    disconnect(): Promise<void>;
+    /** Send a sync message */
+    send(message: SyncMessage): void;
+    /** Register a handler for incoming messages */
+    onMessage(handler: TransportMessageHandler): void;
+    /** Register a handler for connection close events */
+    onClose(handler: TransportCloseHandler): void;
+    /** Register a handler for transport errors */
+    onError(handler: TransportErrorHandler): void;
+    /** Returns true if the transport is currently connected */
+    isConnected(): boolean;
+}
+
+export { type AcknowledgmentMessage as A, isSyncMessage as B, type EncryptedPayload as E, type HandshakeMessage as H, InvalidScopeError as I, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type AwarenessStateWire as k, type AwarenessUpdateMessage as l, type ErrorMessage as m, type HandshakeResponseMessage as n, SYNC_STATES as o, SYNC_STATUSES as p, ScopeViolationError as q, type SyncEncryptionAlgorithm as r, type SyncScopeContext as s, type SyncStatus as t, isAcknowledgmentMessage as u, isAwarenessUpdateMessage as v, isErrorMessage as w, isHandshakeMessage as x, isHandshakeResponseMessage as y, isOperationBatchMessage as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/sync",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Sync protocol and transports for Kora.js with delta sync, causal ordering, and automatic reconnection",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -33,8 +33,8 @@
   ],
   "dependencies": {
     "protobufjs": "^8.0.1",
-    "@korajs/core": "0.3.1",
-    "@korajs/merge": "0.3.1"
+    "@korajs/core": "0.4.0",
+    "@korajs/merge": "0.4.0"
   },
   "devDependencies": {
     "@fast-check/vitest": "0.2.0",

package/dist/transport-B5EFsr5F.d.cts

@@ -1,215 +0,0 @@
-import { Operation, OperationType, HLCTimestamp } from '@korajs/core';
-
-/**
- * Internal sync engine states. Used for state machine transitions.
- */
-declare const SYNC_STATES: readonly ["disconnected", "connecting", "handshaking", "syncing", "streaming", "error"];
-type SyncState = (typeof SYNC_STATES)[number];
-/**
- * Developer-facing sync status. Simplified view of the internal state.
- */
-declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error"];
-type SyncStatus = (typeof SYNC_STATUSES)[number];
-/**
- * Sync status information exposed to developers.
- */
-interface SyncStatusInfo {
-    /** Current developer-facing status */
-    status: SyncStatus;
-    /** Number of operations waiting to be sent */
-    pendingOperations: number;
-    /** Timestamp of last successful sync (null if never synced) */
-    lastSyncedAt: number | null;
-}
-/**
- * Sync configuration provided by the developer.
- */
-interface SyncConfig {
-    /** WebSocket or HTTP URL for the sync server */
-    url: string;
-    /** Transport type to use. Defaults to 'websocket'. */
-    transport?: 'websocket' | 'http';
-    /** Auth provider function. Called before each connection attempt. */
-    auth?: () => Promise<{
-        token: string;
-    }>;
-    /** Sync scopes per collection. Limits which records sync to this client. */
-    scopes?: Record<string, (ctx: SyncScopeContext) => Record<string, unknown>>;
-    /** Number of operations per batch. Defaults to 100. */
-    batchSize?: number;
-    /** Initial reconnection delay in ms. Defaults to 1000. */
-    reconnectInterval?: number;
-    /** Maximum reconnection delay in ms. Defaults to 30000. */
-    maxReconnectInterval?: number;
-    /** Schema version of this client. */
-    schemaVersion?: number;
-}
-/**
- * Context passed to sync scope functions.
- */
-interface SyncScopeContext {
-    userId?: string;
-    [key: string]: unknown;
-}
-/**
- * Interface for persisting the outbound operation queue.
- * Operations must survive page refreshes and be sent when connection is re-established.
- */
-interface QueueStorage {
-    /** Load all queued operations from persistent storage */
-    load(): Promise<Operation[]>;
-    /** Persist an operation to the queue */
-    enqueue(op: Operation): Promise<void>;
-    /** Remove acknowledged operations by their IDs */
-    dequeue(ids: string[]): Promise<void>;
-    /** Return number of operations in storage */
-    count(): Promise<number>;
-}
-
-type WireFormat = 'json' | 'protobuf';
-/**
- * Wire-format operation. Plain object (no Map) for JSON serialization.
- * Maps 1:1 with Operation, but uses Record instead of Map for version vectors.
- */
-interface SerializedOperation {
-    id: string;
-    nodeId: string;
-    type: OperationType;
-    collection: string;
-    recordId: string;
-    data: Record<string, unknown> | null;
-    previousData: Record<string, unknown> | null;
-    timestamp: HLCTimestamp;
-    sequenceNumber: number;
-    causalDeps: string[];
-    schemaVersion: number;
-}
-/**
- * Handshake message sent by client to initiate sync.
- */
-interface HandshakeMessage {
-    type: 'handshake';
-    messageId: string;
-    nodeId: string;
-    /** Version vector as plain object (nodeId -> sequence number) */
-    versionVector: Record<string, number>;
-    schemaVersion: number;
-    authToken?: string;
-    supportedWireFormats?: WireFormat[];
-}
-/**
- * Server response to a handshake.
- */
-interface HandshakeResponseMessage {
-    type: 'handshake-response';
-    messageId: string;
-    nodeId: string;
-    versionVector: Record<string, number>;
-    schemaVersion: number;
-    accepted: boolean;
-    rejectReason?: string;
-    selectedWireFormat?: WireFormat;
-}
-/**
- * Batch of operations sent during delta exchange or streaming.
- */
-interface OperationBatchMessage {
-    type: 'operation-batch';
-    messageId: string;
-    operations: SerializedOperation[];
-    /** True if this is the last batch in the delta exchange phase */
-    isFinal: boolean;
-    /** Index of this batch (0-based) for ordering */
-    batchIndex: number;
-}
-/**
- * Acknowledgment of a received message.
- */
-interface AcknowledgmentMessage {
-    type: 'acknowledgment';
-    messageId: string;
-    acknowledgedMessageId: string;
-    lastSequenceNumber: number;
-}
-/**
- * Error message from the server or client.
- */
-interface ErrorMessage {
-    type: 'error';
-    messageId: string;
-    code: string;
-    message: string;
-    retriable: boolean;
-}
-/**
- * Union of all sync protocol messages.
- */
-type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage;
-/**
- * Check if an unknown value is a valid SyncMessage.
- */
-declare function isSyncMessage(value: unknown): value is SyncMessage;
-/**
- * Check if a value is a HandshakeMessage.
- */
-declare function isHandshakeMessage(value: unknown): value is HandshakeMessage;
-/**
- * Check if a value is a HandshakeResponseMessage.
- */
-declare function isHandshakeResponseMessage(value: unknown): value is HandshakeResponseMessage;
-/**
- * Check if a value is an OperationBatchMessage.
- */
-declare function isOperationBatchMessage(value: unknown): value is OperationBatchMessage;
-/**
- * Check if a value is an AcknowledgmentMessage.
- */
-declare function isAcknowledgmentMessage(value: unknown): value is AcknowledgmentMessage;
-/**
- * Check if a value is an ErrorMessage.
- */
-declare function isErrorMessage(value: unknown): value is ErrorMessage;
-
-/**
- * Options for transport connection.
- */
-interface TransportOptions {
-    /** Authentication token sent during connection */
-    authToken?: string;
-    /** Additional headers (for HTTP-based transports) */
-    headers?: Record<string, string>;
-}
-/**
- * Transport-level error handler.
- */
-type TransportErrorHandler = (error: Error) => void;
-/**
- * Transport-level close handler.
- */
-type TransportCloseHandler = (reason: string) => void;
-/**
- * Transport-level message handler.
- */
-type TransportMessageHandler = (message: SyncMessage) => void;
-/**
- * Abstract transport interface for sync communication.
- * Implementations can use WebSocket, HTTP, Bluetooth, or any other transport.
- */
-interface SyncTransport {
-    /** Connect to the sync server at the given URL */
-    connect(url: string, options?: TransportOptions): Promise<void>;
-    /** Disconnect from the server */
-    disconnect(): Promise<void>;
-    /** Send a sync message */
-    send(message: SyncMessage): void;
-    /** Register a handler for incoming messages */
-    onMessage(handler: TransportMessageHandler): void;
-    /** Register a handler for connection close events */
-    onClose(handler: TransportCloseHandler): void;
-    /** Register a handler for transport errors */
-    onError(handler: TransportErrorHandler): void;
-    /** Returns true if the transport is currently connected */
-    isConnected(): boolean;
-}
-
-export { type AcknowledgmentMessage as A, type ErrorMessage as E, type HandshakeMessage as H, type OperationBatchMessage as O, type QueueStorage as Q, type SyncMessage as S, type TransportOptions as T, type WireFormat as W, type SerializedOperation as a, type SyncTransport as b, type TransportMessageHandler as c, type TransportCloseHandler as d, type TransportErrorHandler as e, type SyncConfig as f, type SyncStatusInfo as g, type SyncState as h, type HandshakeResponseMessage as i, SYNC_STATES as j, SYNC_STATUSES as k, type SyncScopeContext as l, type SyncStatus as m, isAcknowledgmentMessage as n, isErrorMessage as o, isHandshakeMessage as p, isHandshakeResponseMessage as q, isOperationBatchMessage as r, isSyncMessage as s };