jazz-tools 0.19.15 → 0.19.17

package/src/tools/auth/clerk/tests/JazzClerkAuth.test.ts

@@ -6,7 +6,7 @@ import { Account, ID, InMemoryKVStore, KvStoreContext } from "jazz-tools";
 import { createJazzTestAccount } from "jazz-tools/testing";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { JazzClerkAuth } from "../index";
-import type { MinimalClerkClient } from "../types";
+import type { ClerkEventSchema, ClerkUser, MinimalClerkClient } from "../types";
 
 KvStoreContext.getInstance().initialize(new InMemoryKVStore());
 const authSecretStorage = new AuthSecretStorage();
@@ -27,23 +27,16 @@ describe("JazzClerkAuth", () => {
 
   describe("onClerkUserChange", () => {
     it("should do nothing if no clerk user", async () => {
-      const mockClerk = {
-        user: null,
-      } as MinimalClerkClient;
-
-      await auth.onClerkUserChange(mockClerk);
+      await auth.onClerkUserChange(null);
       expect(mockAuthenticate).not.toHaveBeenCalled();
     });
 
     it("should throw if not authenticated locally", async () => {
-      const mockClerk = {
-        user: {
-          unsafeMetadata: {},
-        },
-        signOut: vi.fn(),
-      } as unknown as MinimalClerkClient;
+      const user = {
+        unsafeMetadata: {},
+      } as ClerkUser;
 
-      await expect(auth.onClerkUserChange(mockClerk)).rejects.toThrow();
+      await expect(auth.onClerkUserChange(user)).rejects.toThrow();
       expect(mockAuthenticate).not.toHaveBeenCalled();
     });
 
@@ -61,11 +54,10 @@ describe("JazzClerkAuth", () => {
           fullName: "Guido",
           unsafeMetadata: {},
           update: vi.fn(),
-        },
-        signOut: vi.fn(),
-      } as unknown as MinimalClerkClient;
+        } as ClerkUser,
+      };
 
-      await auth.onClerkUserChange(mockClerk);
+      await auth.onClerkUserChange(mockClerk.user);
 
       expect(mockClerk.user?.update).toHaveBeenCalledWith({
         unsafeMetadata: {
@@ -106,11 +98,11 @@ describe("JazzClerkAuth", () => {
             jazzAccountSecret: "secret123",
             jazzAccountSeed: [1, 2, 3],
           },
-        },
-        signOut: vi.fn(),
-      } as unknown as MinimalClerkClient;
+          update: vi.fn(),
+        } as ClerkUser,
+      };
 
-      await auth.onClerkUserChange(mockClerk);
+      await auth.onClerkUserChange(mockClerk.user);
 
       expect(mockAuthenticate).toHaveBeenCalledWith({
         accountID: "test123",
@@ -137,13 +129,12 @@ describe("JazzClerkAuth", () => {
             jazzAccountSecret: "secret123",
             jazzAccountSeed: [1, 2, 3],
           },
-        },
-        signOut: vi.fn(),
-      } as unknown as MinimalClerkClient;
-
-      await auth.onClerkUserChange(mockClerk);
+          update: vi.fn(),
+        } as ClerkUser,
+      };
 
-      await auth.onClerkUserChange({ user: null });
+      await auth.onClerkUserChange(mockClerk.user);
+      await auth.onClerkUserChange(null);
 
       expect(authSecretStorage.isAuthenticated).toBe(false);
       expect(mockLogOut).toHaveBeenCalled();
@@ -151,10 +142,8 @@ describe("JazzClerkAuth", () => {
   });
 
   describe("registerListener", () => {
-    function setupMockClerk(user: MinimalClerkClient["user"]) {
-      const listners = new Set<
-        (clerkClient: Pick<MinimalClerkClient, "user">) => void
-      >();
+    function setupMockClerk(user: ClerkUser | null) {
+      const listners = new Set<(clerkClient: ClerkEventSchema) => void>();
 
       return {
         client: {
@@ -166,9 +155,9 @@ describe("JazzClerkAuth", () => {
             };
           }),
         } as unknown as MinimalClerkClient,
-        triggerUserChange: (user: unknown) => {
+        triggerUserChange: (user: ClerkUser | null | undefined) => {
           for (const listener of listners) {
-            listener({ user } as Pick<MinimalClerkClient, "user">);
+            listener({ user });
           }
         },
       };
@@ -211,6 +200,7 @@ describe("JazzClerkAuth", () => {
           jazzAccountSecret: "secret123",
           jazzAccountSeed: [1, 2, 3],
         },
+        update: vi.fn(),
       });
 
       expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(2);
@@ -251,6 +241,7 @@ describe("JazzClerkAuth", () => {
           jazzAccountSecret: "secret123",
           jazzAccountSeed: [1, 2, 3],
         },
+        update: vi.fn(),
       });
 
       triggerUserChange({
@@ -259,6 +250,7 @@ describe("JazzClerkAuth", () => {
           jazzAccountSecret: "secret123",
           jazzAccountSeed: [1, 2, 3],
         },
+        update: vi.fn(),
       });
 
       expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
@@ -282,6 +274,86 @@ describe("JazzClerkAuth", () => {
 
       expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
     });
+
+    it("should complete signup flow when new Clerk user is detected", async () => {
+      // 1. Setup local credentials (simulating anonymous user)
+      await authSecretStorage.set({
+        accountID: "test-account-id" as ID<Account>,
+        secretSeed: new Uint8Array([1, 2, 3]),
+        accountSecret: "test-secret" as AgentSecret,
+        provider: "anonymous",
+      });
+
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(
+        mockAuthenticate,
+        mockLogOut,
+        authSecretStorage,
+      );
+
+      // 2. Register listener with null user (no one logged in yet)
+      auth.registerListener(client);
+
+      // Initial trigger with no user
+      triggerUserChange(null);
+
+      // 3. Trigger event with new Clerk user (no Jazz credentials yet)
+      const mockUserUpdate = vi.fn((data) => {
+        triggerUserChange({
+          ...data,
+          update: mockUserUpdate,
+        });
+      });
+
+      const signInSpy = vi.spyOn(auth, "signIn");
+      const logInSpy = vi.spyOn(auth, "logIn");
+
+      const newClerkUser = {
+        fullName: "Test User",
+        firstName: "Test",
+        lastName: "User",
+        username: "testuser",
+        id: "clerk-user-123",
+        primaryEmailAddress: { emailAddress: "test@example.com" },
+        unsafeMetadata: {}, // No Jazz credentials yet
+        update: mockUserUpdate,
+      };
+
+      triggerUserChange(newClerkUser);
+
+      // Wait for async operations to complete
+      await vi.waitFor(() => {
+        expect(mockUserUpdate).toHaveBeenCalled();
+      });
+
+      // 4. Verify credentials synced to Clerk
+      expect(mockUserUpdate).toHaveBeenCalledWith({
+        unsafeMetadata: {
+          jazzAccountID: "test-account-id",
+          jazzAccountSecret: "test-secret",
+          jazzAccountSeed: [1, 2, 3],
+        },
+      });
+
+      // Verify profile name was updated from Clerk username
+      const me = await Account.getMe().$jazz.ensureLoaded({
+        resolve: { profile: true },
+      });
+      expect(me.profile.name).toBe("Test User");
+
+      // Verify authSecretStorage is updated with provider "clerk"
+      const storedCredentials = await authSecretStorage.get();
+      expect(storedCredentials).toEqual({
+        accountID: "test-account-id",
+        accountSecret: "test-secret",
+        secretSeed: new Uint8Array([1, 2, 3]),
+        provider: "clerk",
+      });
+
+      expect(signInSpy).toHaveBeenCalled();
+      expect(logInSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe("initializeAuth", () => {

package/src/tools/auth/clerk/tests/getClerkUsername.test.ts

@@ -1,81 +1,61 @@
 import { describe, expect, it } from "vitest";
 import { getClerkUsername } from "../getClerkUsername.js";
-import type { MinimalClerkClient } from "../types.js";
+import type { ClerkUser } from "../types.js";
 
 describe("getClerkUsername", () => {
-  it("should return null if no user", () => {
-    const mockClerk = {
-      user: null,
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe(null);
-  });
-
   it("should return fullName if available", () => {
-    const mockClerk = {
-      user: {
+    expect(
+      getClerkUsername({
         fullName: "John Doe",
         firstName: "John",
         lastName: "Doe",
         username: "johndoe",
-      },
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe("John Doe");
+      } as ClerkUser),
+    ).toBe("John Doe");
   });
 
   it("should return firstName + lastName if available and no fullName", () => {
-    const mockClerk = {
-      user: {
+    expect(
+      getClerkUsername({
         firstName: "John",
         lastName: "Doe",
         username: "johndoe",
-      },
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe("John Doe");
+      } as ClerkUser),
+    ).toBe("John Doe");
   });
 
   it("should return firstName if available and no lastName or fullName", () => {
-    const mockClerk = {
-      user: {
+    expect(
+      getClerkUsername({
         firstName: "John",
         username: "johndoe",
-      },
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe("John");
+      } as ClerkUser),
+    ).toBe("John");
   });
 
   it("should return username if available and no names", () => {
-    const mockClerk = {
-      user: {
+    expect(
+      getClerkUsername({
         username: "johndoe",
-      },
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe("johndoe");
+      } as ClerkUser),
+    ).toBe("johndoe");
   });
 
   it("should return email username if available and no other identifiers", () => {
-    const mockClerk = {
-      user: {
+    expect(
+      getClerkUsername({
         primaryEmailAddress: {
           emailAddress: "john.doe@example.com",
         },
-      },
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe("john.doe");
+      } as ClerkUser),
+    ).toBe("john.doe");
   });
 
   it("should return user id as last resort", () => {
-    const mockClerk = {
-      user: {
+    expect(
+      getClerkUsername({
         id: "user_123",
-      },
-    } as MinimalClerkClient;
-
-    expect(getClerkUsername(mockClerk)).toBe("user_123");
+      } as ClerkUser),
+    ).toBe("user_123");
   });
 });

package/src/tools/auth/clerk/tests/isClerkAuthStateEqual.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import { ClerkUser, isClerkAuthStateEqual } from "../types";
+
+describe("isClerkAuthStateEqual", () => {
+  const validCredentials = {
+    jazzAccountID: "account-123",
+    jazzAccountSecret: "secret-123",
+    jazzAccountSeed: [1, 2, 3],
+  };
+
+  const differentCredentials = {
+    jazzAccountID: "account-456",
+    jazzAccountSecret: "secret-456",
+    jazzAccountSeed: [4, 5, 6],
+  };
+
+  describe("both users null/undefined", () => {
+    it.each([
+      { previous: null, next: null, description: "both null" },
+      { previous: undefined, next: undefined, description: "both undefined" },
+      { previous: null, next: undefined, description: "null and undefined" },
+      { previous: undefined, next: null, description: "undefined and null" },
+    ])("returns true when $description", ({ previous, next }) => {
+      expect(isClerkAuthStateEqual(previous, next)).toBe(true);
+    });
+  });
+
+  describe("one user null, other exists", () => {
+    it.each([
+      {
+        previous: null,
+        next: { unsafeMetadata: validCredentials },
+        description: "previous null, next exists",
+      },
+      {
+        previous: { unsafeMetadata: validCredentials },
+        next: null,
+        description: "previous exists, next null",
+      },
+      {
+        previous: undefined,
+        next: { unsafeMetadata: validCredentials },
+        description: "previous undefined, next exists",
+      },
+      {
+        previous: { unsafeMetadata: validCredentials },
+        next: undefined,
+        description: "previous exists, next undefined",
+      },
+    ])("returns false when $description", ({ previous, next }) => {
+      expect(isClerkAuthStateEqual(previous, next)).toBe(false);
+    });
+  });
+
+  describe("same jazzAccountID", () => {
+    it("returns true when both users have the same jazzAccountID", () => {
+      const previous = { unsafeMetadata: validCredentials };
+      const next = {
+        unsafeMetadata: {
+          ...validCredentials,
+          jazzAccountSecret: "different-secret",
+        },
+      };
+      expect(isClerkAuthStateEqual(previous, next)).toBe(true);
+    });
+  });
+
+  describe("different jazzAccountID", () => {
+    it("returns false when users have different jazzAccountID", () => {
+      const previous = { unsafeMetadata: validCredentials };
+      const next = { unsafeMetadata: differentCredentials };
+      expect(isClerkAuthStateEqual(previous, next)).toBe(false);
+    });
+  });
+
+  describe("neither user has valid credentials", () => {
+    it.each([
+      {
+        previous: { unsafeMetadata: {} },
+        next: { unsafeMetadata: {} },
+        description: "both have empty metadata",
+      },
+      {
+        previous: { unsafeMetadata: { someOtherField: "value" } },
+        next: { unsafeMetadata: { anotherField: "value" } },
+        description: "both have non-credential metadata",
+      },
+      {
+        previous: { unsafeMetadata: { jazzAccountID: "123" } },
+        next: { unsafeMetadata: { jazzAccountSecret: "456" } },
+        description: "both have incomplete credentials",
+      },
+    ])("returns true when $description", ({ previous, next }) => {
+      expect(
+        isClerkAuthStateEqual(previous as ClerkUser, next as ClerkUser),
+      ).toBe(true);
+    });
+  });
+
+  describe("one has credentials, other doesn't", () => {
+    it.each([
+      {
+        previous: { unsafeMetadata: validCredentials },
+        next: { unsafeMetadata: {} },
+        description: "previous has credentials, next empty",
+      },
+      {
+        previous: { unsafeMetadata: {} },
+        next: { unsafeMetadata: validCredentials },
+        description: "previous empty, next has credentials",
+      },
+      {
+        previous: { unsafeMetadata: validCredentials },
+        next: { unsafeMetadata: { jazzAccountID: "123" } },
+        description: "previous has credentials, next has incomplete",
+      },
+      {
+        previous: { unsafeMetadata: { jazzAccountSecret: "456" } },
+        next: { unsafeMetadata: validCredentials },
+        description: "previous has incomplete, next has credentials",
+      },
+    ])("returns false when $description", ({ previous, next }) => {
+      expect(
+        isClerkAuthStateEqual(previous as ClerkUser, next as ClerkUser),
+      ).toBe(false);
+    });
+  });
+});

package/src/tools/auth/clerk/tests/{types.test.ts → isClerkCredentials.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isClerkCredentials } from "../types";
+import { ClerkUser, isClerkCredentials } from "../types";
 
 describe("isClerkCredentials", () => {
   it.each([
@@ -44,6 +44,8 @@ describe("isClerkCredentials", () => {
       description: "missing jazzAccountSecret",
     },
   ])("fails for invalid credentials: $description", ({ metadata }) => {
-    expect(isClerkCredentials(metadata)).toBe(false);
+    expect(isClerkCredentials(metadata as ClerkUser["unsafeMetadata"])).toBe(
+      false,
+    );
   });
 });

package/src/tools/auth/clerk/types.ts

@@ -1,32 +1,57 @@
-import { AgentSecret } from "cojson";
-import { Account, ID } from "jazz-tools";
+import { type AgentSecret } from "cojson";
+import { z } from "zod/v4";
+
+const ClerkJazzCredentialsSchema = z.object({
+  jazzAccountID: z.string(),
+  jazzAccountSecret: z.string(),
+  jazzAccountSeed: z.array(z.number()).optional(),
+});
+
+const ClerkUserSchema = z.object({
+  fullName: z.string().nullish(),
+  username: z.string().nullish(),
+  firstName: z.string().nullish(),
+  lastName: z.string().nullish(),
+  id: z.string().optional(),
+  primaryEmailAddress: z
+    .object({
+      emailAddress: z.string().nullable(),
+    })
+    .nullish(),
+  unsafeMetadata: z.union([z.object({}), ClerkJazzCredentialsSchema]),
+  update: z.function({
+    input: [
+      z.object({
+        unsafeMetadata: ClerkJazzCredentialsSchema,
+      }),
+    ],
+    output: z.promise(z.unknown()),
+  }),
+});
+
+export const ClerkEventSchema = z.object({
+  user: ClerkUserSchema.nullish(),
+});
+export type ClerkEventSchema = z.infer<typeof ClerkEventSchema>;
+
+export type ClerkUser = z.infer<typeof ClerkUserSchema>;
+
+// Need to provide a permissive type externally to accept
+type PermissiveClerkUser = Omit<ClerkUser, "unsafeMetadata" | "update"> & {
+  unsafeMetadata: Record<string, unknown>;
+  update: (args: {
+    unsafeMetadata: Record<string, unknown>;
+  }) => Promise<unknown>;
+};
 
 export type MinimalClerkClient = {
-  user:
-    | {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        unsafeMetadata: Record<string, any>;
-        fullName: string | null;
-        username: string | null;
-        firstName: string | null;
-        lastName: string | null;
-        id: string;
-        primaryEmailAddress: {
-          emailAddress: string | null;
-        } | null;
-        update: (args: {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          unsafeMetadata: Record<string, any>;
-        }) => Promise<unknown>;
-      }
-    | null
-    | undefined;
+  user: PermissiveClerkUser | null | undefined;
   signOut: () => Promise<void>;
   addListener: (listener: (data: unknown) => void) => void;
 };
 
 export type ClerkCredentials = {
-  jazzAccountID: ID<Account>;
+  jazzAccountID: string;
   jazzAccountSecret: AgentSecret;
   jazzAccountSeed?: number[];
 };
@@ -36,21 +61,34 @@ export type ClerkCredentials = {
  * **Note**: It does not validate the credentials, only checks if the necessary fields are present in the metadata object.
  */
 export function isClerkCredentials(
-  data: NonNullable<MinimalClerkClient["user"]>["unsafeMetadata"] | undefined,
+  data: Record<string, unknown> | undefined,
 ): data is ClerkCredentials {
   return !!data && "jazzAccountID" in data && "jazzAccountSecret" in data;
 }
 
+type ClerkUserWithUnsafeMetadata =
+  | Pick<ClerkUser, "unsafeMetadata">
+  | null
+  | undefined;
+
 export function isClerkAuthStateEqual(
-  previousUser: MinimalClerkClient["user"] | null | undefined,
-  newUser: MinimalClerkClient["user"] | null | undefined,
+  previousUser: ClerkUserWithUnsafeMetadata,
+  newUser: ClerkUserWithUnsafeMetadata,
 ) {
   if (Boolean(previousUser) !== Boolean(newUser)) {
     return false;
   }
 
-  const previousCredentials = isClerkCredentials(previousUser?.unsafeMetadata);
-  const newCredentials = isClerkCredentials(newUser?.unsafeMetadata);
+  const previousCredentials = isClerkCredentials(previousUser?.unsafeMetadata)
+    ? previousUser?.unsafeMetadata
+    : null;
+  const newCredentials = isClerkCredentials(newUser?.unsafeMetadata)
+    ? newUser?.unsafeMetadata
+    : null;
+
+  if (!previousCredentials || !newCredentials) {
+    return previousCredentials === newCredentials;
+  }
 
-  return previousCredentials === newCredentials;
+  return previousCredentials.jazzAccountID === newCredentials.jazzAccountID;
 }

package/src/tools/implementation/ContextManager.ts

@@ -188,24 +188,45 @@ export class JazzContextManager<
     return this.subscriptionCache;
   }
 
+  /**
+   * Flag to indicate if a logout operation is currently in progress.
+   * Used to prevent concurrent logout attempts or double-logout issues.
+   * Set to true when logout starts, reset to false once all logout logic runs.
+   */
+  loggingOut = false;
+
+  /**
+   * Handles the logout process.
+   * Uses the loggingOut flag to ensure only one logout can happen at a time.
+   */
   logOut = async () => {
-    if (!this.context || !this.props) {
+    if (!this.context || !this.props || this.loggingOut) {
       return;
     }
 
+    // Mark as logging out to prevent reentry
+    this.loggingOut = true;
+
     this.authenticatingAccountID = null;
 
     // Clear cache on logout to prevent subscription leaks across authentication boundaries
     this.subscriptionCache.clear();
 
-    await this.props.onLogOut?.();
+    try {
+      await this.props.onLogOut?.();
 
-    if (this.props.logOutReplacement) {
-      await this.props.logOutReplacement();
-    } else {
-      await this.context.logOut();
-      return this.createContext(this.props);
+      if (this.props.logOutReplacement) {
+        await this.props.logOutReplacement();
+      } else {
+        await this.context.logOut();
+        await this.createContext(this.props);
+      }
+    } catch (error) {
+      console.error("Error during logout", error);
     }
+
+    // Reset flag after standard logout finishes
+    this.loggingOut = false;
   };
 
   done = () => {

package/src/tools/tests/ContextManager.test.ts

@@ -604,6 +604,22 @@ describe("ContextManager", () => {
       expect(onAnonymousAccountDiscarded).toHaveBeenCalledTimes(1);
     });
 
+    test("prevents concurrent logout attempts", async () => {
+      const onLogOut = vi.fn();
+      await manager.createContext({ onLogOut });
+
+      // Start multiple concurrent logout attempts
+      const promises = [];
+      for (let i = 0; i < 5; i++) {
+        promises.push(manager.logOut());
+      }
+
+      await Promise.all(promises);
+
+      // onLogOut should only be called once despite multiple logOut calls
+      expect(onLogOut).toHaveBeenCalledTimes(1);
+    });
+
     test("allows authentication after logout", async () => {
       const account = await createJazzTestAccount();
       const onAnonymousAccountDiscarded = vi.fn();

package/dist/tools/auth/clerk/tests/types.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.test.d.ts.map

package/dist/tools/auth/clerk/tests/types.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.test.d.ts","sourceRoot":"","sources":["../../../../../src/tools/auth/clerk/tests/types.test.ts"],"names":[],"mappings":""}