@korajs/sync 0.6.0 → 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Obed Ehoneah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -101,6 +101,7 @@ var SYNC_STATUSES = [
   "syncing",
   "synced",
   "offline",
+  "clock-error",
   "error",
   "schema-mismatch"
 ];
@@ -347,7 +348,7 @@ function isYjsDocUpdateMessage(value) {
 
 // src/protocol/serializer.ts
 var import_core2 = require("@korajs/core");
-var import_minimal = __toESM(require("protobufjs/minimal"), 1);
+var import_minimal = __toESM(require("protobufjs/minimal.js"), 1);
 var { Reader, Writer } = import_minimal.default;
 function versionVectorToWire(vector) {
   const wire = {};
@@ -583,7 +584,8 @@ function toProtoEnvelope(message) {
         schemaVersion: message.schemaVersion,
         accepted: message.accepted,
         rejectReason: message.rejectReason,
-        selectedWireFormat: message.selectedWireFormat
+        selectedWireFormat: message.selectedWireFormat,
+        serverTime: message.serverTime
       };
     case "operation-batch":
       return {
@@ -643,7 +645,10 @@ function fromProtoEnvelope(envelope) {
         schemaVersion: envelope.schemaVersion ?? 0,
         accepted: envelope.accepted ?? false,
         rejectReason: envelope.rejectReason,
-        selectedWireFormat: envelope.selectedWireFormat === "json" || envelope.selectedWireFormat === "protobuf" ? envelope.selectedWireFormat : void 0
+        selectedWireFormat: envelope.selectedWireFormat === "json" || envelope.selectedWireFormat === "protobuf" ? envelope.selectedWireFormat : void 0,
+        // Preserve the server's wall-clock time so clock-skew detection and
+        // automatic timestamp rebase work over the protobuf wire, not just JSON.
+        ...envelope.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {}
       };
     case "operation-batch":
       return {
@@ -812,6 +817,7 @@ function encodeEnvelope(envelope) {
     writer.uint32(138).string(envelope.errorMessage);
   }
   if (envelope.retriable !== void 0) writer.uint32(144).bool(envelope.retriable);
+  if (envelope.serverTime !== void 0) writer.uint32(152).int64(envelope.serverTime);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -880,6 +886,9 @@ function decodeEnvelope(bytes) {
       case 18:
         envelope.retriable = reader.bool();
         break;
+      case 19:
+        envelope.serverTime = longToNumber(reader.int64());
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1381,7 +1390,7 @@ var ChaosTransport = class {
   random;
   messageHandler = null;
   reorderBuffer = [];
-  timers = [];
+  pending = [];
   constructor(inner, config) {
     this.inner = inner;
     this.dropRate = config?.dropRate ?? 0;
@@ -1396,10 +1405,14 @@ var ChaosTransport = class {
   }
   async disconnect() {
     this.flushReorderBuffer();
-    for (const timer of this.timers) {
+    const flushed = this.pending;
+    this.pending = [];
+    for (const { timer } of flushed) {
       clearTimeout(timer);
     }
-    this.timers = [];
+    for (const { message } of flushed) {
+      this.deliverIncoming(message);
+    }
     return this.inner.disconnect();
   }
   send(message) {
@@ -1436,9 +1449,10 @@ var ChaosTransport = class {
     if (this.maxLatency > 0) {
       const delay = Math.floor(this.random() * this.maxLatency);
       const timer = setTimeout(() => {
+        this.pending = this.pending.filter((p) => p.timer !== timer);
         this.deliverIncoming(message);
       }, delay);
-      this.timers.push(timer);
+      this.pending.push({ timer, message });
       return;
     }
     this.deliverIncoming(message);
@@ -2345,6 +2359,41 @@ var OutboundQueue = class {
   peek(count) {
     return this.queue.slice(0, count);
   }
+  /**
+   * All queued operations (not counting in-flight), in causal order.
+   */
+  getAll() {
+    return [...this.queue];
+  }
+  /**
+   * Atomically replace the entire queue with a new set of operations.
+   *
+   * Used after a timestamp rebase rewrote the queued operations under new
+   * content-addressed ids: the old entries must vanish from memory AND from
+   * persistent storage in one step, or a page refresh could resurrect
+   * stale-stamped ops the server would reject. Resets the seen set to exactly
+   * the new ids so the rewritten ops are not treated as duplicates.
+   */
+  async replaceAll(ops) {
+    const removeIds = this.queue.map((op) => op.id);
+    for (const batch of this.inFlight.values()) {
+      for (const op of batch) {
+        removeIds.push(op.id);
+      }
+    }
+    this.inFlight.clear();
+    this.queue = ops.length > 1 ? (0, import_internal.topologicalSort)([...ops]) : [...ops];
+    this.seen.clear();
+    for (const op of this.queue) {
+      this.seen.add(op.id);
+    }
+    if (removeIds.length > 0) {
+      await this.storage.dequeue(removeIds);
+    }
+    for (const op of this.queue) {
+      await this.storage.enqueue(op);
+    }
+  }
   /**
    * Whether initialize() has been called.
    */
@@ -2406,6 +2455,8 @@ var SyncEngine = class {
   currentBatch = null;
   reconnecting = false;
   schemaBlocked = false;
+  clockBlocked = false;
+  clockSkewMs = null;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2579,10 +2630,17 @@ var SyncEngine = class {
       lastSyncedAt: this.lastSyncedAt,
       lastSuccessfulPush: this.lastSuccessfulPush,
       lastSuccessfulPull: this.lastSuccessfulPull,
-      conflicts: this.conflictCount
+      conflicts: this.conflictCount,
+      clockSkewMs: this.clockSkewMs
     };
     switch (this.state) {
       case "disconnected":
+        if (this.clockBlocked) {
+          return { ...base, status: "clock-error" };
+        }
+        if (this.schemaBlocked) {
+          return { ...base, status: "schema-mismatch" };
+        }
         return { ...base, status: "offline" };
       case "connecting":
       case "handshaking":
@@ -2591,6 +2649,9 @@ var SyncEngine = class {
       case "streaming":
         return { ...base, status: pendingOperations > 0 ? "syncing" : "synced" };
       case "error":
+        if (this.clockBlocked) {
+          return { ...base, status: "clock-error" };
+        }
         return { ...base, status: this.schemaBlocked ? "schema-mismatch" : "error" };
     }
   }
@@ -2601,6 +2662,27 @@ var SyncEngine = class {
   isSchemaBlocked() {
     return this.schemaBlocked;
   }
+  /**
+   * True when sync is blocked because this device's clock is too far ahead.
+   * Local writes continue to work and queue; only sync is paused.
+   */
+  isClockBlocked() {
+    return this.clockBlocked;
+  }
+  /** serverTime - localTime measured at the last handshake, or null before first connect. */
+  getClockSkewMs() {
+    return this.clockSkewMs;
+  }
+  /**
+   * Clears the clock block after the user corrects the device clock.
+   * Moves the engine back to `disconnected` so `start()` can run again.
+   */
+  clearClockBlock() {
+    this.clockBlocked = false;
+    if (this.state === "error") {
+      this.transitionTo("disconnected");
+    }
+  }
   /**
    * Clears schema-mismatch block after upgrading the local schema / sync config.
    * Moves the engine back to `disconnected` so `start()` can run again.
@@ -2744,7 +2826,7 @@ var SyncEngine = class {
   async handleMessageAsync(message) {
     switch (message.type) {
       case "handshake-response":
-        this.handleHandshakeResponse(message);
+        await this.handleHandshakeResponse(message);
         break;
       case "operation-batch":
         await this.handleOperationBatch(message);
@@ -2767,8 +2849,41 @@ var SyncEngine = class {
     const reason = error instanceof Error ? error.message : "Message handling failed";
     this.handleTransportClose(reason);
   }
-  handleHandshakeResponse(msg) {
+  /**
+   * Compares server wall-clock time from the handshake with local time.
+   * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+   * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+   * Zero developer work required: the result flows into sync status and events.
+   */
+  evaluateClockSkew(serverTime) {
+    const skewMs = serverTime - Date.now();
+    this.clockSkewMs = skewMs;
+    const FAST_BLOCK_MS = 6e4;
+    const SLOW_WARN_MS = 10 * 6e4;
+    let severity = "info";
+    if (skewMs < -FAST_BLOCK_MS) {
+      severity = "fast-blocked";
+    } else if (skewMs > SLOW_WARN_MS) {
+      severity = "slow-warning";
+    }
+    this.emitter?.emit({ type: "sync:clock-skew", skewMs, severity, source: "handshake" });
+    if (severity === "fast-blocked") {
+      this.clockBlocked = true;
+    } else {
+      this.clockBlocked = false;
+    }
+  }
+  async handleHandshakeResponse(msg) {
     if (this.state !== "handshaking") return;
+    if (typeof msg.serverTime === "number") {
+      this.evaluateClockSkew(msg.serverTime);
+      if (this.clockBlocked) {
+        this.metricsCollector.updateStatus("error");
+        this.transitionTo("error");
+        void this.transport.disconnect();
+        return;
+      }
+    }
     if (!msg.accepted) {
       const reason = msg.rejectReason ?? "Handshake rejected";
       if (isSchemaMismatchReject(msg.rejectReason)) {
@@ -2815,8 +2930,51 @@ var SyncEngine = class {
     this.deltaSentOpIds = [];
     this.pendingDeltaBatchAcks.clear();
     this.initialSyncTotalBatches = 0;
+    if (typeof msg.serverTime === "number") {
+      await this.maybeRebaseQueuedOperations(msg.serverTime);
+    }
     this.sendDelta();
   }
+  /**
+   * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+   * enough in the future that the server would reject them, using the server's
+   * own handshake time as the trusted "now". This is the automatic recovery
+   * path after a user corrects a fast device clock: the queue drains
+   * immediately instead of waiting for real time to catch up.
+   */
+  async maybeRebaseQueuedOperations(serverTime) {
+    const rebase = this.store.rebaseUnsyncedOperations?.bind(this.store);
+    if (!rebase) return;
+    const queued = this.outboundQueue.getAll();
+    if (queued.length === 0) return;
+    let maxQueuedWallTime = Number.NEGATIVE_INFINITY;
+    for (const op of queued) {
+      if (op.timestamp.wallTime > maxQueuedWallTime) {
+        maxQueuedWallTime = op.timestamp.wallTime;
+      }
+    }
+    const SERVER_FUTURE_TOLERANCE_MS = 6e4;
+    if (maxQueuedWallTime <= serverTime + SERVER_FUTURE_TOLERANCE_MS) return;
+    try {
+      const result = await rebase(
+        queued.map((op) => op.id),
+        serverTime
+      );
+      await this.outboundQueue.replaceAll(result.operations);
+      this.emitter?.emit({
+        type: "sync:clock-rebase",
+        rebasedCount: result.rebasedCount,
+        maxSkewMs: maxQueuedWallTime - serverTime
+      });
+    } catch (error) {
+      this.emitter?.emit({
+        type: "store:persistence-error",
+        dbName: "kora-oplog",
+        message: error instanceof Error ? error.message : "Timestamp rebase failed",
+        code: "CLOCK_REBASE_FAILED"
+      });
+    }
+  }
   async sendDelta() {
     const localVector = this.store.getVersionVector();
     const allMissingOps = await this.collectDelta(localVector, this.remoteVector);
@@ -2996,6 +3154,17 @@ var SyncEngine = class {
     if (msg.code === "AUTH_FAILED") {
       this.emitter?.emit({ type: "sync:auth-failed", reason: msg.message });
     }
+    if (msg.code === "INVALID_TIMESTAMP") {
+      this.clockBlocked = true;
+      this.emitter?.emit({
+        type: "sync:clock-skew",
+        skewMs: this.clockSkewMs ?? Number.NaN,
+        severity: "fast-blocked",
+        source: "server-reject"
+      });
+      this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
+      return;
+    }
     this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
     this.transitionTo("disconnected");
   }
@@ -3476,7 +3645,7 @@ var KeyDerivationError = class extends import_core7.SyncError {
   }
 };
 var SALT_LENGTH = 32;
-var PBKDF2_ITERATIONS = 6e5;
+var DEFAULT_PBKDF2_ITERATIONS = 6e5;
 var DERIVED_KEY_LENGTH = 256;
 function assertCryptoAvailable() {
   if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
@@ -3493,13 +3662,19 @@ function generateSalt() {
   }
   return globalThis.crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
 }
-async function deriveKey(passphrase, salt) {
+async function deriveKey(passphrase, salt, iterations = DEFAULT_PBKDF2_ITERATIONS) {
   assertCryptoAvailable();
   if (passphrase.length === 0) {
     throw new KeyDerivationError(
       "Passphrase must not be empty. Provide a non-empty string for encryption key derivation."
     );
   }
+  if (!Number.isInteger(iterations) || iterations < 1) {
+    throw new KeyDerivationError(
+      `PBKDF2 iteration count must be a positive integer, received: ${iterations}`,
+      { iterations }
+    );
+  }
   const usedSalt = salt ?? generateSalt();
   try {
     const passphraseBytes = new TextEncoder().encode(passphrase);
@@ -3514,7 +3689,7 @@ async function deriveKey(passphrase, salt) {
       {
         name: "PBKDF2",
         salt: usedSalt,
-        iterations: PBKDF2_ITERATIONS,
+        iterations,
         hash: "SHA-256"
       },
       baseKey,
@@ -3534,13 +3709,13 @@ async function deriveKey(passphrase, salt) {
     );
   }
 }
-async function deriveVersionedKey(passphrase, version, salt) {
+async function deriveVersionedKey(passphrase, version, salt, iterations = DEFAULT_PBKDF2_ITERATIONS) {
   if (!Number.isInteger(version) || version < 1) {
     throw new KeyDerivationError(`Key version must be a positive integer, received: ${version}`, {
       version
     });
   }
-  const { key, salt: usedSalt } = await deriveKey(passphrase, salt);
+  const { key, salt: usedSalt } = await deriveKey(passphrase, salt, iterations);
   return { version, key, salt: usedSalt };
 }
 
@@ -3580,11 +3755,13 @@ var SyncEncryptor = class _SyncEncryptor {
    * @param config - Encryption configuration with passphrase
    * @param salt - Optional salt for deterministic key derivation (mainly for testing).
    *              If omitted, a random salt is generated.
+   * @param iterations - Optional PBKDF2 iteration count. Defaults to the
+   *              production-strength value. Lower it only in tests.
    * @returns A configured SyncEncryptor instance
    * @throws {EncryptionError} If configuration is invalid
    * @throws {KeyDerivationError} If key derivation fails
    */
-  static async create(config, salt) {
+  static async create(config, salt, iterations) {
     if (!config.enabled) {
       throw new EncryptionError(
         "Cannot create SyncEncryptor with encryption disabled. Set enabled: true in the encryption config."
@@ -3596,7 +3773,7 @@ var SyncEncryptor = class _SyncEncryptor {
         "Encryption key/passphrase must not be empty. Provide a non-empty string or key provider function."
       );
     }
-    const versionedKey = await deriveVersionedKey(passphrase, 1, salt);
+    const versionedKey = await deriveVersionedKey(passphrase, 1, salt, iterations);
     const keys = /* @__PURE__ */ new Map();
     keys.set(1, versionedKey);
     return new _SyncEncryptor(keys, 1);
@@ -3897,10 +4074,12 @@ var OFFLINE_SYNC_STATUS = Object.freeze({
   lastSyncedAt: null,
   lastSuccessfulPush: null,
   lastSuccessfulPull: null,
-  conflicts: 0
+  conflicts: 0,
+  clockSkewMs: null
 });
 var SYNC_STATUS_EVENT_TYPES = [
   "sync:connected",
+  "sync:clock-skew",
   "sync:disconnected",
   "sync:schema-mismatch",
   "sync:auth-failed",