@pylonsync/sync 0.3.305 → 0.3.306

package/dist/index.d.ts

@@ -162,6 +162,16 @@ export declare class SyncEngine {
      * Read-only after start() observes the IDB load.
      */
     private _hadCachedReplica;
+    /**
+     * Which identity (resolved `userId`, or `null` when logged out) the
+     * currently-hydrated replica belongs to. Loaded from disk on cold start
+     * and re-tagged after every (re)sync. `undefined` means "unknown" — a
+     * pre-tag replica or a fresh engine; the guard must NOT treat that as a
+     * mismatch. Used to wipe the replica when a different user signs in on
+     * the same browser across a page reload — the leak `observeToken` can't
+     * see, because a fresh engine has no prior token to compare against.
+     */
+    private _replicaIdentity;
     /**
      * Sticky flag: a persisted row/cursor write degraded (IDB quota /
      * abort), so the on-disk replica is known to be behind the in-memory
@@ -455,6 +465,23 @@ export declare class SyncEngine {
     resetReplica(opts?: {
         wipeMutations?: boolean;
     }): Promise<void>;
+    /**
+     * Wipe the hydrated replica when it belongs to a different identity than
+     * the currently-resolved session — the shared-browser / account-switch
+     * leak that surfaces only across a page reload (a live token flip is
+     * already caught by `observeToken` in pull()). No-op when nothing was
+     * hydrated, when the persisted identity is unknown (a pre-tag replica —
+     * we tag it on this run instead of wiping, so the protection kicks in
+     * from the next reload), or when it already matches.
+     */
+    private guardReplicaIdentity;
+    /**
+     * Record the identity that owns the current replica (in memory + on disk)
+     * so a later cold start can detect an account switch. Fire-and-forget —
+     * the tag is a hint; a missed write just degrades to "tag unknown" which
+     * the guard treats conservatively (no wipe, re-tag next run).
+     */
+    private persistReplicaIdentity;
     /**
      * Drop the local replica and pull fresh. `wipeMutations` decides the
      * fate of the durable offline write queue:
@@ -606,7 +633,9 @@ export declare class SyncEngine {
     private reconcileInner;
     /** Fetch every row for an entity. Uses cursor pagination so big tables
      *  don't blow past server-side limits; loops until `has_more` is false
-     *  or a safety cap is hit. */
+     *  or a safety cap is hit. Returns `truncated: true` when the cap was hit
+     *  with rows STILL on the server — the fetched set is then INCOMPLETE and
+     *  the caller must not infer deletions from it (see applyEntityReconcile). */
     private fetchEntityRows;
     private applyEntityReconcile;
     private dropEntity;

package/dist/persistence.d.ts

@@ -76,6 +76,16 @@ export declare class IndexedDBPersistence {
     saveCursor(cursor: SyncCursor): Promise<boolean>;
     /** Load the sync cursor. */
     loadCursor(): Promise<SyncCursor | null>;
+    /** Record which identity (resolved `userId`, or `null` when logged out)
+     *  the persisted replica belongs to. Read back on the next cold start to
+     *  detect an account switch across a page reload — the one case the live
+     *  `observeToken` path can't see (a fresh engine has no prior token to
+     *  compare against). Stored in the cursor store so it rides the same DB. */
+    saveIdentity(userId: string | null): Promise<boolean>;
+    /** Load the persisted replica identity. Returns `undefined` when no tag
+     *  was ever written (a pre-tag replica — the caller must not treat that
+     *  as a mismatch), or `string | null` for a recorded identity. */
+    loadIdentity(): Promise<string | null | undefined>;
     /** Clear stored rows + cursor. Deliberately does NOT touch the
      *  durable mutation queue: `resetReplica` calls this on a 410 RESYNC
      *  (same user, needs a fresh snapshot) where pending offline writes

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.305",
+  "version": "0.3.306",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -280,6 +280,17 @@ export class SyncEngine {
    */
   private _hadCachedReplica = false;
 
+  /**
+   * Which identity (resolved `userId`, or `null` when logged out) the
+   * currently-hydrated replica belongs to. Loaded from disk on cold start
+   * and re-tagged after every (re)sync. `undefined` means "unknown" — a
+   * pre-tag replica or a fresh engine; the guard must NOT treat that as a
+   * mismatch. Used to wipe the replica when a different user signs in on
+   * the same browser across a page reload — the leak `observeToken` can't
+   * see, because a fresh engine has no prior token to compare against.
+   */
+  private _replicaIdentity: string | null | undefined = undefined;
+
   /**
    * Sticky flag: a persisted row/cursor write degraded (IDB quota /
    * abort), so the on-disk replica is known to be behind the in-memory
@@ -632,6 +643,10 @@ export class SyncEngine {
         // whose pull-from-cursor misses an offline server-side delete
         // depends on that reconcile pass to catch the ghost row.
         this._hadCachedReplica = hadCache;
+        // Which identity the hydrated rows belong to. Compared against the
+        // resolved session in `guardReplicaIdentity` before the first pull
+        // so a reload-time account switch drops the prior user's rows.
+        this._replicaIdentity = await this.persistence.loadIdentity();
         let hydrated = false;
         for (const [entity, rows] of Object.entries(cached)) {
           for (const row of rows) {
@@ -772,6 +787,15 @@ export class SyncEngine {
       await this.refreshResolvedSession();
     }
 
+    // Identity-tag guard. If the hydrated replica belongs to a DIFFERENT
+    // user than the one we just resolved — a shared browser / account
+    // switch across a page reload — wipe it before the pull below layers
+    // the new identity's deltas on top of the old user's rows. The live
+    // `observeToken` reset can't catch this: a fresh engine's
+    // `lastSeenToken` starts undefined, so its first observation reports
+    // no change and it would otherwise adopt the prior user's replica.
+    await this.guardReplicaIdentity();
+
     // Drain hydrated offline writes now that we ARE the leader. The
     // startup hydrate (in the persist block above) ran pre-election,
     // when a push() would have taken the follower branch and broadcast
@@ -802,6 +826,10 @@ export class SyncEngine {
       void this.persistence.saveCursor(this.cursor);
     }
 
+    // Tag the freshly-synced replica with the identity that owns it, so the
+    // next cold start can detect an account switch (see guardReplicaIdentity).
+    this.persistReplicaIdentity();
+
     // First-load reconciliation pass — closes the "phantom row" gap when
     // the local IndexedDB has rows the server doesn't (deletes made by
     // another surface while this tab was closed, or events that fell
@@ -1341,6 +1369,50 @@ export class SyncEngine {
     return this.opQueue.enqueue("reset", () => this.resetReplicaInner(opts));
   }
 
+  /**
+   * Wipe the hydrated replica when it belongs to a different identity than
+   * the currently-resolved session — the shared-browser / account-switch
+   * leak that surfaces only across a page reload (a live token flip is
+   * already caught by `observeToken` in pull()). No-op when nothing was
+   * hydrated, when the persisted identity is unknown (a pre-tag replica —
+   * we tag it on this run instead of wiping, so the protection kicks in
+   * from the next reload), or when it already matches.
+   */
+  private async guardReplicaIdentity(): Promise<void> {
+    if (!this._hadCachedReplica) return;
+    const prev = this._replicaIdentity;
+    if (prev === undefined) return;
+    const now = this.session.resolved().userId;
+    if (prev === now) return;
+    // Identity flipped across the reload. Drop the prior identity's rows.
+    // Keep pending offline writes ONLY for guest→user (the anonymous-merge
+    // login: the server reassigns the guest's rows to the new user, and the
+    // queued writes should re-push under the user). For any other flip
+    // (user A → user B, user → guest) discard them so one identity's
+    // unsynced writes never push under another.
+    const isGuestToUser =
+      typeof prev === "string" &&
+      prev.startsWith("guest_") &&
+      typeof now === "string" &&
+      !now.startsWith("guest_");
+    await this.resetReplica({ wipeMutations: !isGuestToUser });
+    this.persistReplicaIdentity();
+  }
+
+  /**
+   * Record the identity that owns the current replica (in memory + on disk)
+   * so a later cold start can detect an account switch. Fire-and-forget —
+   * the tag is a hint; a missed write just degrades to "tag unknown" which
+   * the guard treats conservatively (no wipe, re-tag next run).
+   */
+  private persistReplicaIdentity(): void {
+    const id = this.session.resolved().userId;
+    this._replicaIdentity = id;
+    if (this.persistence && !this.persistDegraded) {
+      void this.persistence.saveIdentity(id);
+    }
+  }
+
   /**
    * Drop the local replica and pull fresh. `wipeMutations` decides the
    * fate of the durable offline write queue:
@@ -1388,6 +1460,13 @@ export class SyncEngine {
       try {
         await this.persistence.clear();
         await this.persistence.saveCursor(this.cursor);
+        // clear() wiped the cursor store (identity tag included). The
+        // replica is about to be re-pulled for the CURRENT identity, so
+        // re-tag it to match — otherwise the on-disk tag reads "unknown"
+        // until the next cold-start pull re-records it.
+        const id = this.session.resolved().userId;
+        this._replicaIdentity = id;
+        await this.persistence.saveIdentity(id);
       } catch {
         /* best-effort */
       }
@@ -1865,8 +1944,11 @@ export class SyncEngine {
         const cursorBeforeFetch = this.cursor.last_seq;
         const sessionBeforeFetch = this.session.signature();
         let serverRows: Row[];
+        let fetchTruncated: boolean;
         try {
-          serverRows = await this.fetchEntityRows(entity);
+          const fetched = await this.fetchEntityRows(entity);
+          serverRows = fetched.rows;
+          fetchTruncated = fetched.truncated;
         } catch (err) {
           // Network errors are expected (offline, transient 5xx). Skip
           // this entity; the next reconcile trigger will retry.
@@ -1923,19 +2005,28 @@ export class SyncEngine {
           // the session-changed envelope drive the next reconcile.
           return;
         }
-        await this.applyEntityReconcile(entity, serverRows, tombstoneSeq);
+        await this.applyEntityReconcile(
+          entity,
+          serverRows,
+          tombstoneSeq,
+          fetchTruncated,
+        );
       }),
     );
   }
 
   /** Fetch every row for an entity. Uses cursor pagination so big tables
    *  don't blow past server-side limits; loops until `has_more` is false
-   *  or a safety cap is hit. */
-  private async fetchEntityRows(entity: string): Promise<Row[]> {
+   *  or a safety cap is hit. Returns `truncated: true` when the cap was hit
+   *  with rows STILL on the server — the fetched set is then INCOMPLETE and
+   *  the caller must not infer deletions from it (see applyEntityReconcile). */
+  private async fetchEntityRows(
+    entity: string,
+  ): Promise<{ rows: Row[]; truncated: boolean }> {
     const out: Row[] = [];
     let cursor: string | null = null;
-    // 200 pages × 100 per page = 20k rows. Anything larger should not be
-    // mirrored client-side anyway — see useInfiniteQuery for huge tables.
+    // 200 pages × 100 per page = 20k rows. A `sync:true` entity larger than
+    // this should switch to `sync: false` + search/by-id — see useInfiniteQuery.
     for (let page = 0; page < 200; page++) {
       const qs: string = cursor
         ? `?limit=100&after=${encodeURIComponent(cursor)}`
@@ -1946,16 +2037,22 @@ export class SyncEngine {
         has_more: boolean;
       } = await this.request("GET", `/api/entities/${entity}/cursor${qs}`);
       for (const row of resp.data) out.push(row);
-      if (!resp.has_more || !resp.next_cursor) break;
+      if (!resp.has_more || !resp.next_cursor) {
+        return { rows: out, truncated: false };
+      }
       cursor = resp.next_cursor;
     }
-    return out;
+    // Exhausted the page cap while the server still had more rows: the set
+    // is incomplete. Surface it so reconcile upserts-only instead of
+    // deleting every row past the cap.
+    return { rows: out, truncated: true };
   }
 
   private async applyEntityReconcile(
     entity: string,
     serverRows: Row[],
     tombstoneSeq: number,
+    truncated: boolean,
   ): Promise<void> {
     // Invariant: rows with in-flight or failed mutations are
     // off-limits to reconcile. Neither the upsert branch nor the
@@ -1981,12 +2078,28 @@ export class SyncEngine {
     // stale. The reconcile primitive tombstones at `tombstoneSeq` so
     // future legitimate re-creations (with strictly greater seqs)
     // still flow through.
+    //
+    // BUT only when the server set is COMPLETE. A truncated fetch (entity
+    // larger than the 20k reconcile page cap) returns just the first pages —
+    // a row absent from it may simply live on an un-fetched page, not be
+    // deleted. Inferring deletion here would silently tombstone every row
+    // past the cap (the rows flap: full resync re-adds them, next reconcile
+    // deletes them again). Upsert only; never remove from an incomplete set.
     const removalIds: string[] = [];
-    for (const local of this.store.list(entity)) {
-      const id = (local as { id?: unknown }).id;
-      if (typeof id !== "string") continue;
-      if (pendingKeys.has(`${entity}/${id}`)) continue;
-      if (!serverIds.has(id)) removalIds.push(id);
+    if (truncated) {
+      console.warn(
+        `[reconcile] "${entity}" exceeds the ${20_000}-row client-replication ` +
+          `cap; skipping stale-row cleanup to avoid deleting un-fetched rows. ` +
+          `Mark large server-queried entities \`sync: false\` and read them via ` +
+          `search + by-id instead of replicating the whole table.`,
+      );
+    } else {
+      for (const local of this.store.list(entity)) {
+        const id = (local as { id?: unknown }).id;
+        if (typeof id !== "string") continue;
+        if (pendingKeys.has(`${entity}/${id}`)) continue;
+        if (!serverIds.has(id)) removalIds.push(id);
+      }
     }
     if (upserts.length === 0 && removalIds.length === 0) return;
     // Route through the apply queue so a reconcile batch can't

package/src/persistence.ts

@@ -277,6 +277,34 @@ export class IndexedDBPersistence {
     });
   }
 
+  /** Record which identity (resolved `userId`, or `null` when logged out)
+   *  the persisted replica belongs to. Read back on the next cold start to
+   *  detect an account switch across a page reload — the one case the live
+   *  `observeToken` path can't see (a fresh engine has no prior token to
+   *  compare against). Stored in the cursor store so it rides the same DB. */
+  async saveIdentity(userId: string | null): Promise<boolean> {
+    if (!this.db) return false;
+    const tx = this.db.transaction(CURSOR_STORE, "readwrite");
+    tx.objectStore(CURSOR_STORE).put({ key: "identity", userId });
+    return this.commit(tx, "saveIdentity");
+  }
+
+  /** Load the persisted replica identity. Returns `undefined` when no tag
+   *  was ever written (a pre-tag replica — the caller must not treat that
+   *  as a mismatch), or `string | null` for a recorded identity. */
+  async loadIdentity(): Promise<string | null | undefined> {
+    if (!this.db) return undefined;
+    const tx = this.db.transaction(CURSOR_STORE, "readonly");
+    const store = tx.objectStore(CURSOR_STORE);
+    const request = store.get("identity");
+    return new Promise((resolve) => {
+      request.onsuccess = () => {
+        resolve(request.result ? (request.result.userId ?? null) : undefined);
+      };
+      request.onerror = () => resolve(undefined);
+    });
+  }
+
   /** Clear stored rows + cursor. Deliberately does NOT touch the
    *  durable mutation queue: `resetReplica` calls this on a 410 RESYNC
    *  (same user, needs a fresh snapshot) where pending offline writes

package/src/reconcile.test.ts

@@ -265,6 +265,51 @@ describe("SyncEngine.reconcile", () => {
     expect(engine.store.list("Recording").length).toBe(0);
   });
 
+  test("truncated fetch (entity past the 20k cap) upserts but never deletes", async () => {
+    // The server has more rows than the 200-page (20k) reconcile cap.
+    // fetchEntityRows stops at the cap with `has_more` STILL true, so its
+    // result is INCOMPLETE. Pre-fix, reconcile treated every local row
+    // absent from that partial set as deleted → it silently tombstoned
+    // every row past the cap (then flapped: a full resync re-added them and
+    // the next reconcile deleted them again). The fix: a truncated fetch
+    // upserts only, never removes.
+    let pages = 0;
+    restore = installFetch(async (url) => {
+      if (url.includes("/api/entities/Event/cursor")) {
+        pages += 1;
+        // Always claim more remains → the engine exhausts its page cap.
+        return {
+          status: 200,
+          body: {
+            data: [{ id: `srv_${pages}`, title: `page ${pages}` }],
+            next_cursor: `cursor_${pages}`,
+            has_more: true,
+          },
+        };
+      }
+      return { status: 404, body: {} };
+    });
+
+    const engine = makeEngine();
+    // Local rows that live PAST the cap — the truncated fetch never reaches
+    // them. They must survive reconcile.
+    seedStore(engine, "Event", [
+      { id: "beyond_1", title: "row past the cap" },
+      { id: "beyond_2", title: "row past the cap" },
+    ]);
+    expect(engine.store.list("Event").length).toBe(2);
+
+    await engine.reconcile(["Event"]);
+
+    // The fetch hit the 200-page safety cap — proof the set was truncated.
+    expect(pages).toBe(200);
+    // The un-fetched local rows are NOT deleted (the bug would drop them).
+    expect(engine.store.get("Event", "beyond_1")).not.toBeNull();
+    expect(engine.store.get("Event", "beyond_2")).not.toBeNull();
+    // Rows the fetch DID return are still upserted — reconcile keeps working.
+    expect(engine.store.get("Event", "srv_1")).not.toBeNull();
+  });
+
   test("a successful fetch resets the 403 streak (#343)", async () => {
     let status = 403;
     restore = installFetch(async () =>
@@ -399,6 +444,86 @@ describe("SyncEngine.reconcile session guard", () => {
   });
 });
 
+describe("SyncEngine replica identity guard", () => {
+  // A different user signing in on the same browser across a page RELOAD
+  // must not inherit the previous user's rows. The live `observeToken`
+  // reset can't catch this — a fresh engine has no prior token to compare
+  // against — so the engine tags the persisted replica with its owner and
+  // wipes on a cold-start mismatch. (Privacy leak + "my data vanished"
+  // class found in the ai-chat / ai-studio templates.)
+  function resolveAs(engine: SyncEngine, userId: string | null): void {
+    engine.session.observeSession({
+      userId,
+      tenantId: null,
+      isAdmin: false,
+      roles: [],
+    });
+  }
+
+  test("wipes the replica when a DIFFERENT user is resolved on reload", async () => {
+    const engine = makeEngine();
+    seedStore(engine, "Note", [{ id: "n1", title: "A's private note" }]);
+    (engine as unknown as { _hadCachedReplica: boolean })._hadCachedReplica = true;
+    (engine as unknown as { _replicaIdentity: string })._replicaIdentity = "user_A";
+    resolveAs(engine, "user_B");
+
+    await (engine as unknown as { guardReplicaIdentity(): Promise<void> }).guardReplicaIdentity();
+
+    expect(engine.store.list("Note").length).toBe(0);
+  });
+
+  test("keeps the replica when the SAME user is resolved", async () => {
+    const engine = makeEngine();
+    seedStore(engine, "Note", [{ id: "n1", title: "mine" }]);
+    (engine as unknown as { _hadCachedReplica: boolean })._hadCachedReplica = true;
+    (engine as unknown as { _replicaIdentity: string })._replicaIdentity = "user_A";
+    resolveAs(engine, "user_A");
+
+    await (engine as unknown as { guardReplicaIdentity(): Promise<void> }).guardReplicaIdentity();
+
+    expect(engine.store.list("Note").length).toBe(1);
+  });
+
+  test("keeps an UNTAGGED (pre-fix) replica — conservative, no mass re-download", async () => {
+    const engine = makeEngine();
+    seedStore(engine, "Note", [{ id: "n1", title: "legacy" }]);
+    (engine as unknown as { _hadCachedReplica: boolean })._hadCachedReplica = true;
+    // undefined = a replica written before this fix shipped; can't prove a
+    // mismatch, so don't wipe (the tag gets written this run for next time).
+    (engine as unknown as { _replicaIdentity: undefined })._replicaIdentity = undefined;
+    resolveAs(engine, "user_B");
+
+    await (engine as unknown as { guardReplicaIdentity(): Promise<void> }).guardReplicaIdentity();
+
+    expect(engine.store.list("Note").length).toBe(1);
+  });
+
+  test("guest→user preserves pending writes (merge); user→user discards them", async () => {
+    const cases: ReadonlyArray<readonly [string, string, boolean]> = [
+      ["guest_123", "user_B", false], // anonymous-merge login: keep writes
+      ["user_A", "user_B", true], // account switch: drop A's writes
+    ];
+    for (const [prev, now, expectWipeMutations] of cases) {
+      const engine = makeEngine();
+      seedStore(engine, "Note", [{ id: "n1" }]);
+      (engine as unknown as { _hadCachedReplica: boolean })._hadCachedReplica = true;
+      (engine as unknown as { _replicaIdentity: string })._replicaIdentity = prev;
+      resolveAs(engine, now);
+
+      let captured: { wipeMutations?: boolean } | undefined;
+      const orig = engine.resetReplica.bind(engine);
+      engine.resetReplica = ((opts: { wipeMutations?: boolean } = {}) => {
+        captured = opts;
+        return orig(opts);
+      }) as typeof engine.resetReplica;
+
+      await (engine as unknown as { guardReplicaIdentity(): Promise<void> }).guardReplicaIdentity();
+
+      expect(captured?.wipeMutations).toBe(expectWipeMutations);
+    }
+  });
+});
+
 describe("LocalStore.entityNames", () => {
   test("returns only entities with at least one row", () => {
     const engine = makeEngine();