zksync-sso 0.0.0-beta.1

package/src/communicator/PopupCommunicator.ts

@@ -0,0 +1,111 @@
+import { standardErrors } from "../errors/index.js";
+import type { Communicator, Message } from "./index.js";
+
+export interface PopupConfigMessage extends Message {
+  event: "PopupLoaded" | "PopupUnload";
+}
+
+export class PopupCommunicator implements Communicator {
+  private readonly url: URL;
+  private popup: Window | null = null;
+  private listeners = new Map<(_: MessageEvent) => void, { reject: (_: Error) => void }>();
+
+  constructor(url: string) {
+    this.url = new URL(url);
+  }
+
+  postMessage = async (message: Message) => {
+    const popup = await this.waitForPopupLoaded();
+    popup.postMessage(message, this.url.origin);
+  };
+
+  postRequestAndWaitForResponse = async <M extends Message>(
+    request: Message & { id: NonNullable<Message["id"]> },
+  ): Promise<M> => {
+    const responsePromise = this.onMessage<M>(({ requestId }) => requestId === request.id);
+    this.postMessage(request);
+    return await responsePromise;
+  };
+
+  onMessage = async <M extends Message>(predicate: (_: Partial<M>) => boolean): Promise<M> => {
+    return new Promise((resolve, reject) => {
+      const listener = (event: MessageEvent<M>) => {
+        if (event.origin !== this.url.origin) return; // origin validation
+
+        const message = event.data;
+        if (predicate(message)) {
+          resolve(message);
+          window.removeEventListener("message", listener);
+          this.listeners.delete(listener);
+        }
+      };
+
+      window.addEventListener("message", listener);
+      this.listeners.set(listener, { reject });
+    });
+  };
+
+  private disconnect = () => {
+    // Note: Auth Server popup handles closing itself. this is a fallback.
+    try {
+      if (this.popup && !this.popup.closed) {
+        this.popup.close();
+      }
+    } catch (error) {
+      console.warn("Failed to close popup", error);
+    }
+    this.popup = null;
+
+    this.listeners.forEach(({ reject }, listener) => {
+      reject(standardErrors.provider.userRejectedRequest("Request rejected"));
+      window.removeEventListener("message", listener);
+    });
+    this.listeners.clear();
+  };
+
+  openPopup = () => {
+    const width = 420;
+    const height = 600;
+
+    const url = new URL(this.url.toString());
+    url.searchParams.set("origin", window.location.origin);
+
+    const left = (window.innerWidth - width) / 2 + window.screenX;
+    const top = (window.innerHeight - height) / 2 + window.screenY;
+
+    const popup = window.open(
+      url,
+      "ZKsync SSO",
+      `width=${width}, height=${height}, left=${left}, top=${top}`,
+    );
+    if (!popup) {
+      throw standardErrors.rpc.internal("Pop up window failed to open");
+    }
+    popup.focus();
+    return popup;
+  };
+
+  waitForPopupLoaded = async (): Promise<Window> => {
+    if (this.popup && !this.popup.closed) {
+      // Focus the popup if it's already open
+      this.popup.focus();
+      return this.popup;
+    }
+
+    this.popup = this.openPopup();
+
+    this.onMessage<PopupConfigMessage>(({ event }) => event === "PopupUnload")
+      .then(this.disconnect)
+      .catch(() => {});
+
+    return this.onMessage<PopupConfigMessage>(({ event }) => event === "PopupLoaded")
+      .then(() => {
+        if (!this.popup) throw standardErrors.rpc.internal();
+        return this.popup;
+      });
+  };
+
+  ready = async () => {
+    await this.waitForPopupLoaded();
+  };
+}

package/src/communicator/index.ts

@@ -0,0 +1,2 @@
+export type { Communicator, Message } from "./interface.js";
+export { PopupCommunicator, type PopupConfigMessage } from "./PopupCommunicator.js";

package/src/communicator/interface.ts

@@ -0,0 +1,15 @@
+import type { UUID } from "crypto";
+
+type MessageID = UUID;
+
+export interface Message {
+  id: MessageID;
+  requestId?: MessageID; // For responses
+}
+
+export interface Communicator {
+  postMessage: (_: Message) => void;
+  postRequestAndWaitForResponse: <M extends Message>(_: Message & { id: string }) => Promise<M>;
+  onMessage: <M extends Message>(_: (_: Partial<M>) => boolean) => Promise<M>;
+  ready: () => Promise<void>;
+}

package/src/connector/index.ts

@@ -0,0 +1,171 @@
+import {
+  ChainNotConfiguredError,
+  type Connector,
+  createConnector,
+} from "@wagmi/core";
+import {
+  getAddress,
+  SwitchChainError,
+  toHex,
+  UserRejectedRequestError,
+} from "viem";
+
+import { type AppMetadata, type ProviderInterface, type SessionPreferences, WalletProvider } from "../index.js";
+
+export type ZksyncSsoConnectorOptions = {
+  metadata?: Partial<AppMetadata>;
+  session?: SessionPreferences | (() => SessionPreferences | Promise<SessionPreferences>);
+  authServerUrl?: string;
+};
+
+export const zksyncSsoConnector = (parameters: ZksyncSsoConnectorOptions) => {
+  type Provider = ProviderInterface;
+
+  let walletProvider: WalletProvider | undefined;
+
+  let accountsChanged: Connector["onAccountsChanged"] | undefined;
+  let chainChanged: Connector["onChainChanged"] | undefined;
+  let disconnect: Connector["onDisconnect"] | undefined;
+
+  const destroyWallet = () => {
+    if (walletProvider) {
+      if (accountsChanged) {
+        walletProvider.removeListener("accountsChanged", accountsChanged);
+        accountsChanged = undefined;
+      }
+      if (chainChanged) {
+        walletProvider.removeListener("chainChanged", chainChanged);
+        chainChanged = undefined;
+      }
+      if (disconnect) {
+        walletProvider.removeListener("disconnect", disconnect);
+        disconnect = undefined;
+      }
+    }
+    walletProvider = undefined;
+  };
+
+  return createConnector<Provider>((config) => ({
+    icon: "https://zksync.io/favicon.ico",
+    id: "zksync-sso",
+    name: "ZKsync",
+    // supportsSimulation: true,
+    type: "zksync-sso",
+    async connect({ chainId } = {}) {
+      try {
+        const provider = await this.getProvider();
+        const accounts = (
+          (await provider.request({
+            method: "eth_requestAccounts",
+          })) as string[]
+        ).map((x) => getAddress(x));
+
+        if (!accountsChanged) {
+          accountsChanged = this.onAccountsChanged.bind(this);
+          provider.on("accountsChanged", accountsChanged);
+        }
+        if (!chainChanged) {
+          chainChanged = this.onChainChanged.bind(this);
+          provider.on("chainChanged", chainChanged);
+        }
+        if (!disconnect) {
+          disconnect = this.onDisconnect.bind(this);
+          provider.on("disconnect", disconnect);
+        }
+
+        // Switch to chain if provided
+        let walletChainId = await this.getChainId();
+        if (chainId && walletChainId !== chainId) {
+          const chain = await this.switchChain!({ chainId }).catch((error) => {
+            if (error.code === UserRejectedRequestError.code) throw error;
+            return { id: walletChainId };
+          });
+          walletChainId = chain?.id ?? walletChainId;
+        }
+
+        return { accounts, chainId: walletChainId };
+      } catch (error) {
+        console.error(`Error connecting to ${this.name}`, error);
+        if (
+          /(user closed modal|accounts received is empty|user denied account|request rejected)/i.test(
+            (error as Error).message,
+          )
+        )
+          throw new UserRejectedRequestError(error as Error);
+        throw error;
+      }
+    },
+    async disconnect() {
+      const provider = await this.getProvider();
+      provider.disconnect();
+      destroyWallet();
+    },
+    async getAccounts() {
+      const provider = await this.getProvider();
+      return (
+        await provider.request({
+          method: "eth_accounts",
+        })
+      ).map((x) => getAddress(x));
+    },
+    async getChainId() {
+      const provider = await this.getProvider();
+      const chainId = await provider.request({
+        method: "eth_chainId",
+      });
+      if (!chainId) return config.chains[0].id;
+      return Number(chainId);
+    },
+    async getProvider() {
+      if (!walletProvider) {
+        walletProvider = new WalletProvider({
+          metadata: {
+            name: parameters.metadata?.name,
+            icon: parameters.metadata?.icon,
+          },
+          authServerUrl: parameters.authServerUrl,
+          session: parameters.session,
+          transports: config.transports,
+          chains: config.chains,
+        });
+      }
+      return walletProvider;
+    },
+    async isAuthorized() {
+      try {
+        const accounts = await this.getAccounts();
+        return !!accounts.length;
+      } catch {
+        return false;
+      }
+    },
+    async switchChain({ chainId }) {
+      const chain = config.chains.find((chain) => chain.id === chainId);
+      if (!chain) throw new SwitchChainError(new ChainNotConfiguredError());
+
+      try {
+        const provider = await this.getProvider();
+        await provider.request({
+          method: "wallet_switchEthereumChain",
+          params: [{ chainId: toHex(chainId) }],
+        });
+        return chain;
+      } catch (error) {
+        throw new SwitchChainError(error as Error);
+      }
+    },
+    onAccountsChanged(accounts) {
+      if (accounts.length === 0) this.onDisconnect();
+      else config.emitter.emit("change", {
+        accounts: accounts.map((x) => getAddress(x)),
+      });
+    },
+    onChainChanged(chain) {
+      config.emitter.emit("change", { chainId: Number(chain) });
+    },
+    async onDisconnect(_error) {
+      console.error("onDisconnect", _error);
+      config.emitter.emit("disconnect");
+    },
+  }));
+};

package/src/errors/constants.ts

@@ -0,0 +1,119 @@
+interface ErrorCodes {
+  readonly rpc: {
+    readonly invalidInput: -32000;
+    readonly resourceNotFound: -32001;
+    readonly resourceUnavailable: -32002;
+    readonly transactionRejected: -32003;
+    readonly methodNotSupported: -32004;
+    readonly limitExceeded: -32005;
+    readonly parse: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+  };
+  readonly provider: {
+    readonly userRejectedRequest: 4001;
+    readonly unauthorized: 4100;
+    readonly unsupportedMethod: 4200;
+    readonly disconnected: 4900;
+    readonly chainDisconnected: 4901;
+    readonly unsupportedChain: 4902;
+  };
+}
+
+export const standardErrorCodes: ErrorCodes = {
+  rpc: {
+    invalidInput: -32000,
+    resourceNotFound: -32001,
+    resourceUnavailable: -32002,
+    transactionRejected: -32003,
+    methodNotSupported: -32004,
+    limitExceeded: -32005,
+    parse: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internal: -32603,
+  },
+  provider: {
+    userRejectedRequest: 4001,
+    unauthorized: 4100,
+    unsupportedMethod: 4200,
+    disconnected: 4900,
+    chainDisconnected: 4901,
+    unsupportedChain: 4902,
+  },
+};
+
+export const errorValues = {
+  "-32700": {
+    standard: "JSON RPC 2.0",
+    message:
+      "Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.",
+  },
+  "-32600": {
+    standard: "JSON RPC 2.0",
+    message: "The JSON sent is not a valid Request object.",
+  },
+  "-32601": {
+    standard: "JSON RPC 2.0",
+    message: "The method does not exist / is not available.",
+  },
+  "-32602": {
+    standard: "JSON RPC 2.0",
+    message: "Invalid method parameter(s).",
+  },
+  "-32603": {
+    standard: "JSON RPC 2.0",
+    message: "Internal JSON-RPC error.",
+  },
+  "-32000": {
+    standard: "EIP-1474",
+    message: "Invalid input.",
+  },
+  "-32001": {
+    standard: "EIP-1474",
+    message: "Resource not found.",
+  },
+  "-32002": {
+    standard: "EIP-1474",
+    message: "Resource unavailable.",
+  },
+  "-32003": {
+    standard: "EIP-1474",
+    message: "Transaction rejected.",
+  },
+  "-32004": {
+    standard: "EIP-1474",
+    message: "Method not supported.",
+  },
+  "-32005": {
+    standard: "EIP-1474",
+    message: "Request limit exceeded.",
+  },
+  4001: {
+    standard: "EIP-1193",
+    message: "User rejected the request.",
+  },
+  4100: {
+    standard: "EIP-1193",
+    message: "The requested account and/or method has not been authorized by the user.",
+  },
+  4200: {
+    standard: "EIP-1193",
+    message: "The requested method is not supported by this Ethereum provider.",
+  },
+  4900: {
+    standard: "EIP-1193",
+    message: "The provider is disconnected from all chains.",
+  },
+  4901: {
+    standard: "EIP-1193",
+    message: "The provider is disconnected from the specified chain.",
+  },
+  4902: {
+    standard: "EIP-3085",
+    message: "Unrecognized chain ID.",
+  },
+};

package/src/errors/errors.ts

@@ -0,0 +1,168 @@
+import { standardErrorCodes } from "./constants.js";
+import { getMessageFromCode } from "./utils.js";
+
+export const standardErrors = {
+  rpc: {
+    parse: <T>(arg?: EthErrorsArg<T>) => getEthJsonRpcError(standardErrorCodes.rpc.parse, arg),
+
+    invalidRequest: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.invalidRequest, arg),
+
+    invalidParams: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.invalidParams, arg),
+
+    methodNotFound: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.methodNotFound, arg),
+
+    internal: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.internal, arg),
+
+    server: <T>(opts: ServerErrorOptions<T>) => {
+      if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+        throw new Error("Ethereum RPC Server errors must provide single object argument.");
+      }
+      const { code } = opts;
+      if (!Number.isInteger(code) || code > -32005 || code < -32099) {
+        throw new Error("\"code\" must be an integer such that: -32099 <= code <= -32005");
+      }
+      return getEthJsonRpcError(code, opts);
+    },
+
+    invalidInput: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.invalidInput, arg),
+
+    resourceNotFound: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.resourceNotFound, arg),
+
+    resourceUnavailable: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.resourceUnavailable, arg),
+
+    transactionRejected: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.transactionRejected, arg),
+
+    methodNotSupported: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.methodNotSupported, arg),
+
+    limitExceeded: <T>(arg?: EthErrorsArg<T>) =>
+      getEthJsonRpcError(standardErrorCodes.rpc.limitExceeded, arg),
+  },
+
+  provider: {
+    userRejectedRequest: <T>(arg?: EthErrorsArg<T>) => {
+      return getEthProviderError(standardErrorCodes.provider.userRejectedRequest, arg);
+    },
+
+    unauthorized: <T>(arg?: EthErrorsArg<T>) => {
+      return getEthProviderError(standardErrorCodes.provider.unauthorized, arg);
+    },
+
+    unsupportedMethod: <T>(arg?: EthErrorsArg<T>) => {
+      return getEthProviderError(standardErrorCodes.provider.unsupportedMethod, arg);
+    },
+
+    disconnected: <T>(arg?: EthErrorsArg<T>) => {
+      return getEthProviderError(standardErrorCodes.provider.disconnected, arg);
+    },
+
+    chainDisconnected: <T>(arg?: EthErrorsArg<T>) => {
+      return getEthProviderError(standardErrorCodes.provider.chainDisconnected, arg);
+    },
+
+    unsupportedChain: <T>(arg?: EthErrorsArg<T>) => {
+      return getEthProviderError(standardErrorCodes.provider.unsupportedChain, arg);
+    },
+
+    custom: <T>(opts: CustomErrorArg<T>) => {
+      if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+        throw new Error("Ethereum Provider custom errors must provide single object argument.");
+      }
+
+      const { code, message, data } = opts;
+
+      if (!message || typeof message !== "string") {
+        throw new Error("\"message\" must be a nonempty string");
+      }
+      return new EthereumProviderError(code, message, data);
+    },
+  },
+};
+
+// Internal
+
+function getEthJsonRpcError<T>(code: number, arg?: EthErrorsArg<T>): EthereumRpcError<T> {
+  const [message, data] = parseOpts(arg);
+  return new EthereumRpcError(code, message || getMessageFromCode(code), data);
+}
+
+function getEthProviderError<T>(code: number, arg?: EthErrorsArg<T>): EthereumProviderError<T> {
+  const [message, data] = parseOpts(arg);
+  return new EthereumProviderError(code, message || getMessageFromCode(code), data);
+}
+
+function parseOpts<T>(arg?: EthErrorsArg<T>): [string?, T?] {
+  if (arg) {
+    if (typeof arg === "string") {
+      return [arg];
+    } else if (typeof arg === "object" && !Array.isArray(arg)) {
+      const { message, data } = arg;
+
+      if (message && typeof message !== "string") {
+        throw new Error("Must specify string message.");
+      }
+      return [message || undefined, data];
+    }
+  }
+  return [];
+}
+
+interface EthereumErrorOptions<T> {
+  message?: string;
+  data?: T;
+}
+
+interface ServerErrorOptions<T> extends EthereumErrorOptions<T> {
+  code: number;
+}
+
+type CustomErrorArg<T> = ServerErrorOptions<T>;
+
+type EthErrorsArg<T> = EthereumErrorOptions<T> | string;
+
+class EthereumRpcError<T> extends Error {
+  code: number;
+
+  data?: T;
+
+  constructor(code: number, message: string, data?: T) {
+    if (!Number.isInteger(code)) {
+      throw new Error("\"code\" must be an integer.");
+    }
+    if (!message || typeof message !== "string") {
+      throw new Error("\"message\" must be a nonempty string.");
+    }
+
+    super(message);
+    this.code = code;
+    if (data !== undefined) {
+      this.data = data;
+    }
+  }
+}
+
+class EthereumProviderError<T> extends EthereumRpcError<T> {
+  /**
+   * Create an Ethereum Provider JSON-RPC error.
+   * `code` must be an integer in the 1000 <= 4999 range.
+   */
+  constructor(code: number, message: string, data?: T) {
+    if (!isValidEthProviderCode(code)) {
+      throw new Error("\"code\" must be an integer such that: 1000 <= code <= 4999");
+    }
+
+    super(code, message, data);
+  }
+}
+
+function isValidEthProviderCode(code: number): boolean {
+  return Number.isInteger(code) && code >= 1000 && code <= 4999;
+}

package/src/errors/index.ts

@@ -0,0 +1,4 @@
+export { standardErrorCodes } from "./constants.js";
+export { standardErrors } from "./errors.js";
+export { serializeError } from "./serialize.js";
+export type { SerializedEthereumRpcError } from "./utils.js";

package/src/errors/serialize.ts

@@ -0,0 +1,91 @@
+import { LIB_VERSION } from "../version.js";
+import { standardErrorCodes } from "./constants.js";
+import { serialize, type SerializedEthereumRpcError } from "./utils.js";
+
+type ErrorResponse = {
+  method: unknown;
+  errorCode?: number;
+  errorMessage: string;
+};
+
+/**
+ * Serializes an error to a format that is compatible with the Ethereum JSON RPC error format.
+ */
+export function serializeError(
+  error: unknown,
+  requestOrMethod?: JSONRPCRequest | JSONRPCRequest[] | string,
+): SerializedError {
+  const serialized = serialize(getErrorObject(error), {
+    shouldIncludeStack: true,
+  });
+
+  const docUrl = new URL("https://docs.zksync.io/zksync-account-sdk/docs/errors");
+  docUrl.searchParams.set("version", LIB_VERSION);
+  docUrl.searchParams.set("code", serialized.code.toString());
+  const method = getMethod(serialized.data, requestOrMethod);
+  if (method) {
+    docUrl.searchParams.set("method", method);
+  }
+  docUrl.searchParams.set("message", serialized.message);
+
+  return {
+    ...serialized,
+    docUrl: docUrl.href,
+  };
+}
+
+function isErrorResponse(response: unknown): response is ErrorResponse {
+  return (response as ErrorResponse).errorMessage !== undefined;
+}
+
+/**
+ * Converts an error to a serializable object.
+ */
+function getErrorObject(error: unknown) {
+  if (typeof error === "string") {
+    return {
+      message: error,
+      code: standardErrorCodes.rpc.internal,
+    };
+  } else if (isErrorResponse(error)) {
+    return {
+      ...error,
+      message: error.errorMessage,
+      code: error.errorCode,
+      data: { method: error.method },
+    };
+  }
+  return error;
+}
+
+/**
+ * Gets the method name from the serialized data or the request.
+ */
+function getMethod(
+  serializedData: unknown,
+  request?: JSONRPCRequest | JSONRPCRequest[] | string,
+): string | undefined {
+  const methodInData = (serializedData as { method: string })?.method;
+  if (methodInData) {
+    return methodInData;
+  }
+
+  if (request === undefined) {
+    return undefined;
+  } else if (typeof request === "string") {
+    return request;
+  } else if (!Array.isArray(request)) {
+    return request.method;
+  } else if (request.length > 0) {
+    return request[0]!.method;
+  }
+  return undefined;
+}
+
+interface SerializedError extends SerializedEthereumRpcError {
+  docUrl: string;
+}
+
+interface JSONRPCRequest {
+  method: string;
+}