jazz-tools 0.20.18 → 0.20.19

package/src/browser/provideBrowserLockSession/BrowserSessionProvider.test.ts

@@ -1,10 +1,11 @@
 // @vitest-environment happy-dom
 
 import { WasmCrypto } from "cojson/crypto/WasmCrypto";
-import { SessionID } from "cojson";
+import { RawAccountID, SessionID } from "cojson";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { BrowserSessionProvider } from "./BrowserSessionProvider.js";
 import { SessionIDStorage } from "./SessionIDStorage.js";
+import { BrowserSessionDurabilityMarker } from "./BrowserSessionDurabilityMarker.js";
 import { createJazzTestAccount } from "jazz-tools/testing";
 import type { CryptoProvider } from "jazz-tools";
 
@@ -403,4 +404,99 @@ describe("BrowserSessionProvider", () => {
       expect(result.sessionID).toBe(sessionID);
     });
   });
+
+  describe("session durability marker", () => {
+    test("acquireSession skips a dirty session and reclaims its slot", async () => {
+      const provider = new BrowserSessionProvider();
+      const accountID = account.$jazz.id;
+
+      // A previously stored session that crashed inside the durability window
+      const dirtySession = Crypto.newRandomSessionID(
+        accountID as unknown as RawAccountID,
+      ) as SessionID;
+      SessionIDStorage.storeSessionID(accountID, dirtySession, 0);
+      BrowserSessionDurabilityMarker.set(dirtySession);
+
+      const { sessionID, sessionDone } = await provider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      // A fresh session was minted instead of reusing the dirty one
+      expect(sessionID).not.toBe(dirtySession);
+      // The dirty session's slot was overwritten (list does not grow)
+      expect(SessionIDStorage.getSessionsList(accountID)).toEqual([sessionID]);
+      // The old marker was cleaned up
+      expect(BrowserSessionDurabilityMarker.isSet(dirtySession)).toBe(false);
+
+      sessionDone();
+    });
+
+    test("acquireSession still reuses a clean stored session", async () => {
+      const provider = new BrowserSessionProvider();
+      const accountID = account.$jazz.id;
+
+      const cleanSession = Crypto.newRandomSessionID(
+        accountID as unknown as RawAccountID,
+      ) as SessionID;
+      SessionIDStorage.storeSessionID(accountID, cleanSession, 0);
+
+      const { sessionID, sessionDone } = await provider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      expect(sessionID).toBe(cleanSession);
+      sessionDone();
+    });
+
+    test("marker set/clear/isSet round-trips through localStorage", () => {
+      const id = "co_zx_session_zy" as SessionID;
+      expect(BrowserSessionDurabilityMarker.isSet(id)).toBe(false);
+      BrowserSessionDurabilityMarker.set(id);
+      expect(BrowserSessionDurabilityMarker.isSet(id)).toBe(true);
+      BrowserSessionDurabilityMarker.clear(id);
+      expect(BrowserSessionDurabilityMarker.isSet(id)).toBe(false);
+    });
+
+    test("concurrent acquireSession reclaims dirty slot without orphaning sessions", async () => {
+      const provider = new BrowserSessionProvider();
+      const accountID = account.$jazz.id;
+
+      // A dirty session left behind at slot 0
+      const dirtySession = Crypto.newRandomSessionID(
+        accountID as unknown as RawAccountID,
+      ) as SessionID;
+      SessionIDStorage.storeSessionID(accountID, dirtySession, 0);
+      BrowserSessionDurabilityMarker.set(dirtySession);
+
+      // Two concurrent acquireSession calls for the same account
+      const [result1, result2] = await Promise.all([
+        provider.acquireSession(accountID, Crypto as CryptoProvider),
+        provider.acquireSession(accountID, Crypto as CryptoProvider),
+      ]);
+
+      const { sessionID: sid1, sessionDone: done1 } = result1;
+      const { sessionID: sid2, sessionDone: done2 } = result2;
+
+      // Both sessions differ from the dirty one
+      expect(sid1).not.toBe(dirtySession);
+      expect(sid2).not.toBe(dirtySession);
+
+      // The two new sessions are distinct
+      expect(sid1).not.toBe(sid2);
+
+      // The dirty marker is cleared
+      expect(BrowserSessionDurabilityMarker.isSet(dirtySession)).toBe(false);
+
+      // Session list has exactly 2 entries (slot 0 replaced + one appended)
+      const sessionsList = SessionIDStorage.getSessionsList(accountID);
+      expect(sessionsList).toHaveLength(2);
+      expect(sessionsList).toContain(sid1);
+      expect(sessionsList).toContain(sid2);
+
+      done1();
+      done2();
+    });
+  });
 });

package/src/browser/provideBrowserLockSession/BrowserSessionProvider.ts

@@ -1,8 +1,11 @@
 import { AgentID, CryptoProvider, RawAccountID, SessionID } from "cojson";
 import { ID, Account, SessionProvider } from "jazz-tools";
 import { SessionIDStorage } from "./SessionIDStorage";
+import { BrowserSessionDurabilityMarker } from "./BrowserSessionDurabilityMarker";
 
 export class BrowserSessionProvider implements SessionProvider {
+  readonly durabilityMarker = BrowserSessionDurabilityMarker;
+
   async acquireSession(
     accountID: ID<Account> | AgentID,
     crypto: CryptoProvider,
@@ -11,8 +14,16 @@ export class BrowserSessionProvider implements SessionProvider {
 
     // Get the list of sessions for the account, to try to acquire an existing session
     const sessionsList = SessionIDStorage.getSessionsList(accountID);
+    let dirtySlot: { index: number; sessionID: SessionID } | undefined;
 
     for (const [index, sessionID] of sessionsList.entries()) {
+      // If the session crashed while it had sent-but-unpersisted transactions,
+      // reusing it could fork the session's hash chain on the server.
+      if (BrowserSessionDurabilityMarker.isSet(sessionID)) {
+        dirtySlot ??= { index, sessionID };
+        continue;
+      }
+
       const sessionAcquired = await tryToAcquireSession(
         sessionID,
         sessionPromise,
@@ -31,8 +42,14 @@ export class BrowserSessionProvider implements SessionProvider {
       accountID as RawAccountID | AgentID,
     );
 
-    // Acquire exclusively the session to store the new session ID for reuse in future sessions
-    await lockAndStoreSession(accountID, newSessionID, sessionPromise);
+    // Acquire exclusively the session to store the new session ID for reuse in future sessions.
+    // If a dirty slot was found, reclaim it so the list doesn't grow across crashes.
+    await lockAndStoreSession(
+      accountID,
+      newSessionID,
+      sessionPromise,
+      dirtySlot,
+    );
 
     console.log("Created new session", newSessionID); // This log is used in the e2e tests to verify the correctness of the feature
 
@@ -61,6 +78,7 @@ async function lockAndStoreSession(
   accountID: ID<Account> | AgentID,
   sessionID: SessionID,
   sessionPromise: Promise<void>,
+  replaceSlot?: { index: number; sessionID: SessionID },
 ) {
   const sessionAcquired = await tryToAcquireSession(sessionID, sessionPromise);
 
@@ -70,7 +88,7 @@ async function lockAndStoreSession(
   }
 
   // We don't need to wait for this to finish, we only need to acquire the lock on the new session
-  storeSessionID(accountID, sessionID);
+  storeSessionID(accountID, sessionID, replaceSlot);
 }
 
 function tryToAcquireSession(
@@ -100,6 +118,7 @@ function tryToAcquireSession(
 function storeSessionID(
   accountID: ID<Account> | AgentID,
   sessionID: SessionID,
+  replaceSlot?: { index: number; sessionID: SessionID },
 ) {
   return navigator.locks.request(
     `store_session_${accountID}`,
@@ -110,11 +129,21 @@ function storeSessionID(
       }
 
       const sessionsList = SessionIDStorage.getSessionsList(accountID);
-      SessionIDStorage.storeSessionID(
-        accountID,
-        sessionID,
-        sessionsList.length,
-      );
+
+      // Reclaim the abandoned dirty session's slot so the list doesn't grow
+      // across crashes — unless a concurrent tab already took it, in which
+      // case append. The stale marker is dropped only after the slot is
+      // written, so a crash in between leaves the session safely marked.
+      const index =
+        replaceSlot && sessionsList[replaceSlot.index] === replaceSlot.sessionID
+          ? replaceSlot.index
+          : sessionsList.length;
+
+      SessionIDStorage.storeSessionID(accountID, sessionID, index);
+
+      if (replaceSlot) {
+        BrowserSessionDurabilityMarker.clear(replaceSlot.sessionID);
+      }
     },
   );
 }

package/src/browser/provideBrowserLockSession/index.ts

@@ -1,5 +1,6 @@
 import { MockSessionProvider } from "jazz-tools";
 import { BrowserSessionProvider } from "./BrowserSessionProvider";
+export { BrowserSessionDurabilityMarker } from "./BrowserSessionDurabilityMarker";
 
 export function getBrowserLockSessionProvider() {
   if (typeof navigator === "undefined" || !navigator.locks?.request) {

package/src/expo/storage/expo-sqlite-adapter.ts

@@ -7,6 +7,15 @@ export class ExpoSQLiteAdapter implements SQLiteDatabaseDriverAsync {
   private db: SQLiteDatabase | null = null;
   private initializing: Promise<SQLiteDatabase> | null = null;
   private dbName: string;
+  /**
+   * Serializes transactions at the connection level. The adapter is shared
+   * across providers/contexts (see `getInstance`), each with its own storage
+   * client and transaction queue, and `withTransactionAsync` is not exclusive:
+   * without serialization here, a second BEGIN on the same connection fails
+   * with "cannot start a transaction within a transaction" and its ROLLBACK
+   * aborts the other caller's active transaction.
+   */
+  private txQueue: Promise<unknown> = Promise.resolve();
 
   static withDB(db: SQLiteDatabase): ExpoSQLiteAdapter {
     const adapter = new ExpoSQLiteAdapter();
@@ -89,14 +98,22 @@ export class ExpoSQLiteAdapter implements SQLiteDatabaseDriverAsync {
     await this.db.runAsync(sql, params?.map((p) => p as SQLiteBindValue) ?? []);
   }
 
-  public async transaction(callback: (tx: ExpoSQLiteAdapter) => unknown) {
-    if (!this.db) {
-      throw new Error("Database not initialized");
-    }
+  public transaction(callback: (tx: ExpoSQLiteAdapter) => unknown) {
+    const run = () => {
+      const db = this.db;
+
+      if (!db) {
+        throw new Error("Database not initialized");
+      }
+
+      return db.withTransactionAsync(async () => {
+        await callback(ExpoSQLiteAdapter.withDB(db));
+      });
+    };
 
-    await this.db.withTransactionAsync(async () => {
-      await callback(ExpoSQLiteAdapter.withDB(this.db!));
-    });
+    const next = this.txQueue.then(run, run);
+    this.txQueue = next;
+    return next;
   }
 
   /**

package/src/expo/tests/expo-sqlite-adapter.test.ts

@@ -9,6 +9,48 @@ vi.mock("expo-sqlite", () => ({
 
 import { ExpoSQLiteAdapter } from "../storage/expo-sqlite-adapter.js";
 
+/**
+ * Reproduces expo-sqlite's `withTransactionAsync` semantics: transactions are
+ * not exclusive, a nested BEGIN throws, and a failed BEGIN still triggers a
+ * ROLLBACK that aborts whichever transaction is currently active.
+ */
+function createFakeTransactionalDb() {
+  let inTransaction = false;
+
+  const execAsync = vi.fn(async (sql: string) => {
+    if (sql === "BEGIN") {
+      if (inTransaction) {
+        throw new Error("cannot start a transaction within a transaction");
+      }
+      inTransaction = true;
+    } else if (sql === "COMMIT") {
+      if (!inTransaction) {
+        throw new Error("cannot commit - no transaction is active");
+      }
+      inTransaction = false;
+    } else if (sql === "ROLLBACK") {
+      if (!inTransaction) {
+        throw new Error("cannot rollback - no transaction is active");
+      }
+      inTransaction = false;
+    }
+  });
+
+  return {
+    execAsync,
+    async withTransactionAsync(task: () => Promise<void>) {
+      try {
+        await execAsync("BEGIN");
+        await task();
+        await execAsync("COMMIT");
+      } catch (e) {
+        await execAsync("ROLLBACK");
+        throw e;
+      }
+    },
+  };
+}
+
 describe("ExpoSQLiteAdapter", () => {
   describe("getInstance", () => {
     it("returns the same instance for the same database name", async () => {
@@ -38,4 +80,56 @@ describe("ExpoSQLiteAdapter", () => {
       expect(adapter1.db?.execAsync).toHaveBeenCalledTimes(1);
     });
   });
+
+  describe("transaction", () => {
+    it("serializes concurrent transactions on the same connection", async () => {
+      const db = createFakeTransactionalDb();
+      const adapter = ExpoSQLiteAdapter.withDB(
+        db as unknown as Parameters<typeof ExpoSQLiteAdapter.withDB>[0],
+      );
+
+      const order: string[] = [];
+
+      // Without serialization, the interleaved BEGINs throw
+      // "cannot start a transaction within a transaction" and the resulting
+      // ROLLBACK aborts the other transaction.
+      await Promise.all(
+        Array.from({ length: 5 }, (_, i) =>
+          adapter.transaction(async () => {
+            order.push(`start-${i}`);
+            // Yield so a concurrent transaction would interleave here
+            await new Promise((resolve) => setTimeout(resolve, (5 - i) * 2));
+            order.push(`end-${i}`);
+          }),
+        ),
+      );
+
+      for (let i = 0; i < 5; i++) {
+        expect(order[i * 2]).toBe(`start-${i}`);
+        expect(order[i * 2 + 1]).toBe(`end-${i}`);
+      }
+    });
+
+    it("keeps processing transactions after one fails", async () => {
+      const db = createFakeTransactionalDb();
+      const adapter = ExpoSQLiteAdapter.withDB(
+        db as unknown as Parameters<typeof ExpoSQLiteAdapter.withDB>[0],
+      );
+
+      const failing = adapter.transaction(async () => {
+        throw new Error("boom");
+      });
+      const succeeding = adapter.transaction(async () => {});
+
+      await expect(failing).rejects.toThrow("boom");
+      await expect(succeeding).resolves.not.toThrow();
+
+      // The failed transaction rolled back exactly once, without touching
+      // the following transaction.
+      const rollbacks = db.execAsync.mock.calls.filter(
+        ([sql]) => sql === "ROLLBACK",
+      );
+      expect(rollbacks).toHaveLength(1);
+    });
+  });
 });

package/src/react-native-core/ReactNativeSessionDurabilityMarker.ts

@@ -0,0 +1,40 @@
+import type { SessionID } from "cojson";
+import type { SessionDurabilityMarker } from "jazz-tools";
+// KvStoreContext must come from "jazz-tools" (not the sibling
+// ./storage/kv-store-context.js module): the repo currently has two identical
+// KvStoreContext classes with separate singleton state, and the session
+// provider that reads this marker uses the "jazz-tools" one
+import {
+  KvStoreContext,
+  sessionDurabilityMarkerKey as markerKey,
+} from "jazz-tools";
+
+/**
+ * KvStore-backed durability marker. KvStore writes are async, so `set` can
+ * only be *initiated* before the network send — a best-effort guarantee
+ * (accepted limitation).
+ */
+export const ReactNativeSessionDurabilityMarker: SessionDurabilityMarker = {
+  set(sessionID: SessionID) {
+    KvStoreContext.getInstance()
+      .getStorage()
+      .set(markerKey(sessionID), "1")
+      .catch((err) =>
+        console.warn("Failed to set session durability marker", err),
+      );
+  },
+  clear(sessionID: SessionID) {
+    KvStoreContext.getInstance()
+      .getStorage()
+      .delete(markerKey(sessionID))
+      .catch((err) =>
+        console.warn("Failed to clear session durability marker", err),
+      );
+  },
+  async isSet(sessionID: SessionID) {
+    const value = await KvStoreContext.getInstance()
+      .getStorage()
+      .get(markerKey(sessionID));
+    return value !== null;
+  },
+};

package/src/react-native-core/ReactNativeSessionProvider.ts

@@ -5,22 +5,45 @@ import {
   SessionProvider,
 } from "jazz-tools";
 import { AgentID, RawAccountID } from "cojson";
+import { ReactNativeSessionDurabilityMarker } from "./ReactNativeSessionDurabilityMarker.js";
 
 const lockedSessions = new Set<SessionID>();
 
 export class ReactNativeSessionProvider implements SessionProvider {
+  readonly durabilityMarker = ReactNativeSessionDurabilityMarker;
+
   async acquireSession(
     accountID: string,
     crypto: CryptoProvider,
   ): Promise<{ sessionID: SessionID; sessionDone: () => void }> {
     const kvStore = KvStoreContext.getInstance().getStorage();
-    const existingSession = await kvStore.get(accountID as string);
+    let existingSession = await kvStore.get(accountID as string);
+
+    let abandonedDirtySession: SessionID | undefined;
+
+    if (
+      existingSession &&
+      (await ReactNativeSessionDurabilityMarker.isSet(
+        existingSession as SessionID,
+      ))
+    ) {
+      // The previous run crashed while it had transactions sent to a sync
+      // server but not yet persisted locally: reusing this session could fork
+      // its hash chain. Abandon it and fall through to minting a fresh one.
+      // The marker is cleared only AFTER the new session overwrites the kv
+      // entry, so a crash in between still leaves the session marked dirty.
+      abandonedDirtySession = existingSession as SessionID;
+      existingSession = null;
+    }
 
     if (!existingSession) {
       const newSessionID = crypto.newRandomSessionID(
         accountID as RawAccountID | AgentID,
       );
       await kvStore.set(accountID, newSessionID);
+      if (abandonedDirtySession) {
+        ReactNativeSessionDurabilityMarker.clear(abandonedDirtySession);
+      }
       lockedSessions.add(newSessionID);
 
       console.log("Created new session", newSessionID);

package/src/react-native-core/index.ts

@@ -19,3 +19,4 @@ export {
   ReactNativeContextManager,
   type JazzContextManagerProps,
 } from "./ReactNativeContextManager.js";
+export { ReactNativeSessionDurabilityMarker } from "./ReactNativeSessionDurabilityMarker.js";

package/src/react-native-core/tests/ReactNativeSessionProvider.test.ts

@@ -4,6 +4,7 @@ import { beforeEach, describe, expect, test } from "vitest";
 import { InMemoryKVStore } from "jazz-tools";
 import { KvStoreContext, type KvStore } from "jazz-tools";
 import { ReactNativeSessionProvider } from "../ReactNativeSessionProvider.js";
+import { ReactNativeSessionDurabilityMarker } from "../ReactNativeSessionDurabilityMarker.js";
 import { createJazzTestAccount } from "jazz-tools/testing";
 import type { CryptoProvider } from "jazz-tools";
 
@@ -293,4 +294,45 @@ describe("ReactNativeSessionProvider", () => {
       result.sessionDone();
     });
   });
+
+  describe("session durability marker", () => {
+    test("acquireSession mints a new session when the stored one is dirty", async () => {
+      const accountID = account.$jazz.id;
+
+      // Store a session, then mark it dirty (as a crash inside the window would leave it)
+      const dirtySession = Crypto.newRandomSessionID(
+        accountID as unknown as RawAccountID,
+      );
+      await kvStore.set(accountID, dirtySession);
+      ReactNativeSessionDurabilityMarker.set(dirtySession);
+      await new Promise((r) => setTimeout(r, 0));
+
+      const result = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      expect(result.sessionID).not.toBe(dirtySession);
+      // The kv entry was overwritten with the new session
+      expect(await kvStore.get(accountID)).toBe(result.sessionID);
+      // The stale marker was removed
+      expect(await ReactNativeSessionDurabilityMarker.isSet(dirtySession)).toBe(
+        false,
+      );
+
+      result.sessionDone();
+    });
+
+    test("marker set/clear/isSet round-trips through the KvStore", async () => {
+      const id = "co_zx_session_zy" as SessionID;
+      expect(await ReactNativeSessionDurabilityMarker.isSet(id)).toBe(false);
+      ReactNativeSessionDurabilityMarker.set(id);
+      // set() is fire-and-forget; flush microtasks before asserting
+      await Promise.resolve();
+      expect(await ReactNativeSessionDurabilityMarker.isSet(id)).toBe(true);
+      ReactNativeSessionDurabilityMarker.clear(id);
+      await Promise.resolve();
+      expect(await ReactNativeSessionDurabilityMarker.isSet(id)).toBe(false);
+    });
+  });
 });

package/src/tools/exports.ts

@@ -105,6 +105,9 @@ export {
   createJazzContext,
   SessionProvider,
   MockSessionProvider,
+  type SessionDurabilityMarker,
+  makeDurabilityMarkerListener,
+  sessionDurabilityMarkerKey,
   type AuthResult,
   type Credentials,
   type JazzContextWithAccount,

package/src/tools/implementation/createContext.ts

@@ -23,6 +23,10 @@ import {
 import { AuthCredentials, NewAccountProps } from "../types.js";
 import { activeAccountContext } from "./activeAccountContext.js";
 import { AnonymousJazzAgent } from "./anonymousJazzAgent.js";
+import {
+  type SessionDurabilityMarker,
+  makeDurabilityMarkerListener,
+} from "./sessionDurabilityMarker.js";
 
 export type Credentials = {
   accountID: ID<Account>;
@@ -38,9 +42,17 @@ export interface SessionProvider {
     accountID: ID<Account>,
     sessionID: SessionID,
   ) => Promise<{ sessionDone: () => void }>;
+  /**
+   * When present, the context marks sessions as unsafe-to-reuse while they
+   * have transactions sent to a sync server but not yet persisted locally,
+   * and the provider must skip marked sessions in acquireSession.
+   */
+  durabilityMarker?: SessionDurabilityMarker;
 }
 
 export class MockSessionProvider implements SessionProvider {
+  durabilityMarker?: SessionDurabilityMarker;
+
   async acquireSession(
     accountID: ID<Account>,
     crypto: CryptoProvider,
@@ -136,6 +148,18 @@ export async function createJazzContextFromExistingCredentials<
     crypto,
   );
 
+  // Defense in depth: acquireSession implementations must never return a
+  // session that is still marked unsafe to reuse (see SessionProvider docs)
+  if (
+    sessionProvider.durabilityMarker &&
+    (await sessionProvider.durabilityMarker.isSet(sessionID))
+  ) {
+    console.warn(
+      "Session provider returned a session still marked unsafe to reuse; a crash may fork it",
+      sessionID,
+    );
+  }
+
   const CurrentAccountSchema =
     PropsAccountSchema ?? (RegisteredSchemas["Account"] as unknown as S);
 
@@ -152,6 +176,9 @@ export async function createJazzContextFromExistingCredentials<
     storage,
     enableFullStorageReconciliation: !!storage,
     experimental_clockSyncFromServerPings,
+    onLocalStoreDurabilityChange: makeDurabilityMarkerListener(
+      sessionProvider.durabilityMarker,
+    ),
     migration: async (rawAccount, _node, creationProps) => {
       const account = AccountClass.fromRaw(rawAccount) as InstanceOfSchema<S>;
       if (asActiveAccount) {
@@ -224,6 +251,9 @@ export async function createJazzContextForNewAccount<
     storage,
     enableFullStorageReconciliation: !!storage,
     experimental_clockSyncFromServerPings,
+    onLocalStoreDurabilityChange: makeDurabilityMarkerListener(
+      sessionProvider.durabilityMarker,
+    ),
     migration: async (rawAccount, _node, creationProps) => {
       const account = AccountClass.fromRaw(rawAccount) as InstanceOfSchema<S>;
       activeAccountContext.set(account);