jazz-tools 0.14.27 → 0.15.0

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

@@ -0,0 +1,174 @@
+import {
+  Account,
+  AuthCredentials,
+  AuthSecretStorage,
+  AuthenticateAccountFunction,
+} from "jazz-tools";
+import { getClerkUsername } from "./getClerkUsername.js";
+import {
+  ClerkCredentials,
+  MinimalClerkClient,
+  isClerkAuthStateEqual,
+  isClerkCredentials,
+} from "./types.js";
+
+export type { MinimalClerkClient };
+export { isClerkCredentials };
+
+export class JazzClerkAuth {
+  constructor(
+    private authenticate: AuthenticateAccountFunction,
+    private authSecretStorage: AuthSecretStorage,
+  ) {}
+
+  /**
+   * Loads the Jazz auth data from the Clerk user and sets it in the auth secret storage.
+   */
+  static loadClerkAuthData(
+    credentials: ClerkCredentials,
+    storage: AuthSecretStorage,
+  ) {
+    return storage.set({
+      accountID: credentials.jazzAccountID,
+      accountSecret: credentials.jazzAccountSecret,
+      secretSeed: credentials.jazzAccountSeed
+        ? Uint8Array.from(credentials.jazzAccountSeed)
+        : undefined,
+      provider: "clerk",
+    });
+  }
+
+  static async initializeAuth(clerk: MinimalClerkClient) {
+    const secretStorage = new AuthSecretStorage();
+
+    if (!isClerkCredentials(clerk.user?.unsafeMetadata)) {
+      return;
+    }
+
+    await JazzClerkAuth.loadClerkAuthData(
+      clerk.user.unsafeMetadata,
+      secretStorage,
+    );
+  }
+
+  private isFirstCall = true;
+
+  registerListener(clerkClient: MinimalClerkClient) {
+    let previousUser: MinimalClerkClient["user"] | null =
+      clerkClient.user ?? null;
+
+    // Need to use addListener because the clerk user object is not updated when the user logs in
+    return clerkClient.addListener((event) => {
+      const user = (event as Pick<MinimalClerkClient, "user">).user ?? null;
+
+      if (!isClerkAuthStateEqual(previousUser, user) || this.isFirstCall) {
+        this.onClerkUserChange({ user });
+        previousUser = user;
+        this.isFirstCall = false;
+      }
+    });
+  }
+
+  onClerkUserChange = async (clerkClient: Pick<MinimalClerkClient, "user">) => {
+    const isAuthenticated = this.authSecretStorage.isAuthenticated;
+
+    // LogOut is driven by Clerk. The framework adapters will need to pass `logOutReplacement` to the `JazzProvider`
+    // to make the logOut work correctly.
+    if (!clerkClient.user) {
+      if (isAuthenticated) {
+        this.authSecretStorage.clear();
+      }
+      return;
+    }
+
+    if (isAuthenticated) return;
+
+    const clerkCredentials = clerkClient.user
+      .unsafeMetadata as ClerkCredentials;
+
+    if (!clerkCredentials.jazzAccountID) {
+      await this.signIn(clerkClient);
+    } else {
+      await this.logIn(clerkClient);
+    }
+  };
+
+  logIn = async (clerkClient: Pick<MinimalClerkClient, "user">) => {
+    if (!clerkClient.user) {
+      throw new Error("Not signed in on Clerk");
+    }
+
+    const clerkCredentials = clerkClient.user.unsafeMetadata;
+    if (!isClerkCredentials(clerkCredentials)) {
+      throw new Error("No credentials found on Clerk");
+    }
+
+    const credentials = {
+      accountID: clerkCredentials.jazzAccountID,
+      accountSecret: clerkCredentials.jazzAccountSecret,
+      secretSeed: clerkCredentials.jazzAccountSeed
+        ? Uint8Array.from(clerkCredentials.jazzAccountSeed)
+        : undefined,
+      provider: "clerk",
+    } satisfies AuthCredentials;
+
+    await this.authenticate(credentials);
+
+    await JazzClerkAuth.loadClerkAuthData(
+      {
+        jazzAccountID: credentials.accountID,
+        jazzAccountSecret: credentials.accountSecret,
+        jazzAccountSeed: clerkCredentials.jazzAccountSeed,
+      },
+      this.authSecretStorage,
+    );
+  };
+
+  signIn = async (clerkClient: Pick<MinimalClerkClient, "user">) => {
+    const credentials = await this.authSecretStorage.get();
+
+    if (!credentials) {
+      throw new Error("No credentials found");
+    }
+
+    const jazzAccountSeed = credentials.secretSeed
+      ? Array.from(credentials.secretSeed)
+      : undefined;
+
+    await clerkClient.user?.update({
+      unsafeMetadata: {
+        jazzAccountID: credentials.accountID,
+        jazzAccountSecret: credentials.accountSecret,
+        jazzAccountSeed,
+      } satisfies ClerkCredentials,
+    });
+
+    const currentAccount = await Account.getMe().ensureLoaded({
+      resolve: {
+        profile: true,
+      },
+    });
+
+    const username = getClerkUsername(clerkClient);
+
+    if (username) {
+      currentAccount.profile.name = username;
+    }
+
+    await JazzClerkAuth.loadClerkAuthData(
+      {
+        jazzAccountID: credentials.accountID,
+        jazzAccountSecret: credentials.accountSecret,
+        jazzAccountSeed,
+      },
+      this.authSecretStorage,
+    );
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace BrowserClerkAuth {
+  export interface Driver {
+    onError: (error: string | Error) => void;
+  }
+}

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

@@ -0,0 +1,284 @@
+// @vitest-environment happy-dom
+
+import { AgentSecret } from "cojson";
+import { AuthSecretStorage } from "jazz-tools";
+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";
+
+KvStoreContext.getInstance().initialize(new InMemoryKVStore());
+const authSecretStorage = new AuthSecretStorage();
+
+describe("JazzClerkAuth", () => {
+  const mockAuthenticate = vi.fn();
+  let auth: JazzClerkAuth;
+
+  beforeEach(async () => {
+    await authSecretStorage.clear();
+    mockAuthenticate.mockReset();
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+    auth = new JazzClerkAuth(mockAuthenticate, authSecretStorage);
+  });
+
+  describe("onClerkUserChange", () => {
+    it("should do nothing if no clerk user", async () => {
+      const mockClerk = {
+        user: null,
+      } as MinimalClerkClient;
+
+      await auth.onClerkUserChange(mockClerk);
+      expect(mockAuthenticate).not.toHaveBeenCalled();
+    });
+
+    it("should throw if not authenticated locally", async () => {
+      const mockClerk = {
+        user: {
+          unsafeMetadata: {},
+        },
+        signOut: vi.fn(),
+      } as unknown as MinimalClerkClient;
+
+      await expect(auth.onClerkUserChange(mockClerk)).rejects.toThrow();
+      expect(mockAuthenticate).not.toHaveBeenCalled();
+    });
+
+    it("should call signIn for new users", async () => {
+      // Set up local auth
+      await authSecretStorage.set({
+        accountID: "test123" as ID<Account>,
+        secretSeed: new Uint8Array([1, 2, 3]),
+        accountSecret: "secret123" as AgentSecret,
+        provider: "anonymous",
+      });
+
+      const mockClerk = {
+        user: {
+          fullName: "Guido",
+          unsafeMetadata: {},
+          update: vi.fn(),
+        },
+        signOut: vi.fn(),
+      } as unknown as MinimalClerkClient;
+
+      await auth.onClerkUserChange(mockClerk);
+
+      expect(mockClerk.user?.update).toHaveBeenCalledWith({
+        unsafeMetadata: {
+          jazzAccountID: "test123",
+          jazzAccountSecret: "secret123",
+          jazzAccountSeed: [1, 2, 3],
+        },
+      });
+      expect(await authSecretStorage.get()).toEqual({
+        accountID: "test123",
+        accountSecret: "secret123",
+        secretSeed: new Uint8Array([1, 2, 3]),
+        provider: "clerk",
+      });
+
+      const me = await Account.getMe().ensureLoaded({
+        resolve: {
+          profile: true,
+        },
+      });
+      expect(me.profile.name).toBe("Guido");
+    });
+
+    it("should call logIn for existing users", async () => {
+      // Set up local auth
+      await authSecretStorage.set({
+        accountID: "xxxx" as ID<Account>,
+        secretSeed: new Uint8Array([2, 2, 2]),
+        accountSecret: "xxxx" as AgentSecret,
+        provider: "anonymous",
+      });
+
+      const mockClerk = {
+        user: {
+          fullName: "Guido",
+          unsafeMetadata: {
+            jazzAccountID: "test123",
+            jazzAccountSecret: "secret123",
+            jazzAccountSeed: [1, 2, 3],
+          },
+        },
+        signOut: vi.fn(),
+      } as unknown as MinimalClerkClient;
+
+      await auth.onClerkUserChange(mockClerk);
+
+      expect(mockAuthenticate).toHaveBeenCalledWith({
+        accountID: "test123",
+        accountSecret: "secret123",
+        secretSeed: new Uint8Array([1, 2, 3]),
+        provider: "clerk",
+      });
+    });
+  });
+
+  describe("registerListener", () => {
+    function setupMockClerk(user: MinimalClerkClient["user"]) {
+      const listners = new Set<
+        (clerkClient: Pick<MinimalClerkClient, "user">) => void
+      >();
+
+      return {
+        client: {
+          user,
+          addListener: vi.fn((callback) => {
+            listners.add(callback);
+            return () => {
+              listners.delete(callback);
+            };
+          }),
+        } as unknown as MinimalClerkClient,
+        triggerUserChange: (user: unknown) => {
+          for (const listener of listners) {
+            listener({ user } as Pick<MinimalClerkClient, "user">);
+          }
+        },
+      };
+    }
+
+    it("should call onClerkUserChange on the first trigger", async () => {
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(mockAuthenticate, authSecretStorage);
+      const onClerkUserChangeSpy = vi.spyOn(auth, "onClerkUserChange");
+
+      auth.registerListener(client);
+
+      triggerUserChange(null);
+
+      expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call onClerkUserChange when user changes", async () => {
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(mockAuthenticate, authSecretStorage);
+      const onClerkUserChangeSpy = vi.spyOn(auth, "onClerkUserChange");
+
+      auth.registerListener(client);
+
+      triggerUserChange(null);
+
+      triggerUserChange({
+        unsafeMetadata: {
+          jazzAccountID: "test123",
+          jazzAccountSecret: "secret123",
+          jazzAccountSeed: [1, 2, 3],
+        },
+      });
+
+      expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it("should call onClerkUserChange when user passes from null to non-null", async () => {
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(mockAuthenticate, authSecretStorage);
+      const onClerkUserChangeSpy = vi.spyOn(auth, "onClerkUserChange");
+
+      auth.registerListener(client);
+
+      triggerUserChange(null);
+
+      expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not call onClerkUserChange when user is the same", async () => {
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(mockAuthenticate, authSecretStorage);
+      const onClerkUserChangeSpy = vi.spyOn(auth, "onClerkUserChange");
+
+      auth.registerListener(client);
+
+      triggerUserChange({
+        unsafeMetadata: {
+          jazzAccountID: "test123",
+          jazzAccountSecret: "secret123",
+          jazzAccountSeed: [1, 2, 3],
+        },
+      });
+
+      triggerUserChange({
+        unsafeMetadata: {
+          jazzAccountID: "test123",
+          jazzAccountSecret: "secret123",
+          jazzAccountSeed: [1, 2, 3],
+        },
+      });
+
+      expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not call onClerkUserChange when user switches from undefined to null", async () => {
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(mockAuthenticate, authSecretStorage);
+      const onClerkUserChangeSpy = vi.spyOn(auth, "onClerkUserChange");
+
+      auth.registerListener(client);
+
+      triggerUserChange(null);
+      triggerUserChange(undefined);
+      triggerUserChange(null);
+
+      expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("initializeAuth", () => {
+    it("should load auth data when credentials exist", async () => {
+      const mockClerk = {
+        user: {
+          unsafeMetadata: {
+            jazzAccountID: "test123",
+            jazzAccountSecret: "secret123",
+            jazzAccountSeed: [1, 2, 3],
+          },
+        },
+      } as unknown as MinimalClerkClient;
+
+      await JazzClerkAuth.initializeAuth(mockClerk);
+
+      const storedAuth = await authSecretStorage.get();
+      expect(storedAuth).toEqual({
+        accountID: "test123",
+        accountSecret: "secret123",
+        secretSeed: new Uint8Array([1, 2, 3]),
+        provider: "clerk",
+      });
+    });
+
+    it("should do nothing when no credentials exist", async () => {
+      const mockClerk = {
+        user: {
+          unsafeMetadata: {},
+        },
+      } as unknown as MinimalClerkClient;
+
+      await JazzClerkAuth.initializeAuth(mockClerk);
+
+      const storedAuth = await authSecretStorage.get();
+      expect(storedAuth).toBeNull();
+    });
+
+    it("should do nothing when no user exists", async () => {
+      const mockClerk = {
+        user: null,
+      } as unknown as MinimalClerkClient;
+
+      await JazzClerkAuth.initializeAuth(mockClerk);
+
+      const storedAuth = await authSecretStorage.get();
+      expect(storedAuth).toBeNull();
+    });
+  });
+});

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

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

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { isClerkCredentials } from "../types";
+
+describe("isClerkCredentials", () => {
+  it.each([
+    {
+      metadata: {
+        jazzAccountID: "123",
+        jazzAccountSecret: "456",
+        jazzAccountSeed: [1, 2, 3],
+      },
+      description: "full credentials",
+    },
+    {
+      metadata: {
+        jazzAccountID: "123",
+        jazzAccountSecret: "456",
+      },
+      description: "missing jazzAccountSeed",
+    },
+  ])("succeeds for valid credentials: $description", ({ metadata }) => {
+    expect(isClerkCredentials(metadata)).toBe(true);
+  });
+
+  it.each([
+    {
+      metadata: {},
+      description: "empty object",
+    },
+    {
+      metadata: undefined,
+      description: "undefined",
+    },
+    {
+      metadata: {
+        jazzAccountSecret: "456",
+      },
+      description: "missing jazzAccountID",
+    },
+    {
+      metadata: {
+        jazzAccountID: "123",
+      },
+      description: "missing jazzAccountSecret",
+    },
+  ])("fails for invalid credentials: $description", ({ metadata }) => {
+    expect(isClerkCredentials(metadata)).toBe(false);
+  });
+});

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

@@ -0,0 +1,56 @@
+import { AgentSecret } from "cojson";
+import { Account, ID } from "jazz-tools";
+
+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;
+  signOut: () => Promise<void>;
+  addListener: (listener: (data: unknown) => void) => void;
+};
+
+export type ClerkCredentials = {
+  jazzAccountID: ID<Account>;
+  jazzAccountSecret: AgentSecret;
+  jazzAccountSeed?: number[];
+};
+
+/**
+ * Checks if the Clerk user metadata contains the necessary credentials for Jazz auth.
+ * **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 is ClerkCredentials {
+  return !!data && "jazzAccountID" in data && "jazzAccountSecret" in data;
+}
+
+export function isClerkAuthStateEqual(
+  previousUser: MinimalClerkClient["user"] | null | undefined,
+  newUser: MinimalClerkClient["user"] | null | undefined,
+) {
+  if (Boolean(previousUser) !== Boolean(newUser)) {
+    return false;
+  }
+
+  const previousCredentials = isClerkCredentials(previousUser?.unsafeMetadata);
+  const newCredentials = isClerkCredentials(newUser?.unsafeMetadata);
+
+  return previousCredentials === newCredentials;
+}