zksync-sso 0.0.0-beta.1

package/src/client-auth-server/Signer.ts

@@ -0,0 +1,260 @@
+import { type Address, type Chain, type Hash, hexToNumber, http, type RpcSchema as RpcSchemaGeneric, type SendTransactionParameters, type Transport } from "viem";
+
+import { createZksyncSessionClient, type ZksyncSsoSessionClient } from "../client/index.js";
+import type { Communicator } from "../communicator/index.js";
+import { type SessionConfig } from "../utils/session.js";
+import { StorageItem } from "../utils/storage.js";
+import type { AppMetadata, RequestArguments } from "./interface.js";
+import type { AuthServerRpcSchema, ExtractParams, ExtractReturnType, Method, RPCRequestMessage, RPCResponseMessage, RpcSchema } from "./rpc.js";
+import type { SessionPreferences } from "./session.js";
+
+type Account = {
+  address: Address;
+  activeChainId: Chain["id"];
+  session?: {
+    sessionKey: Hash;
+    sessionConfig: SessionConfig;
+  };
+};
+
+interface SignerInterface {
+  accounts: Address[];
+  chain: Chain;
+  handshake(): Promise<Address[]>;
+  request<TMethod extends Method>(request: RequestArguments<TMethod>): Promise<ExtractReturnType<TMethod>>;
+  disconnect: () => Promise<void>;
+}
+
+type UpdateListener = {
+  onAccountsUpdate: (_: Address[]) => void;
+  onChainUpdate: (_: number) => void;
+};
+
+type SignerConstructorParams = {
+  metadata: () => AppMetadata;
+  communicator: Communicator;
+  updateListener: UpdateListener;
+  chains: readonly Chain[];
+  transports?: Record<number, Transport>;
+  session?: () => SessionPreferences | Promise<SessionPreferences>;
+};
+
+type ChainsInfo = ExtractReturnType<"eth_requestAccounts", AuthServerRpcSchema>["chainsInfo"];
+
+export class Signer implements SignerInterface {
+  private readonly getMetadata: () => AppMetadata;
+  private readonly communicator: Communicator;
+  private readonly updateListener: UpdateListener;
+  private readonly chains: readonly Chain[];
+  private readonly transports: Record<number, Transport> = {};
+  private readonly sessionParameters?: () => (SessionPreferences | Promise<SessionPreferences>);
+
+  private _account: StorageItem<Account | null>;
+  private _chainsInfo = new StorageItem<ChainsInfo>(StorageItem.scopedStorageKey("chainsInfo"), []);
+  private walletClient: ZksyncSsoSessionClient | undefined;
+
+  constructor({ metadata, communicator, updateListener, session, chains, transports }: SignerConstructorParams) {
+    if (!chains.length) throw new Error("At least one chain must be included in the config");
+
+    this.getMetadata = metadata;
+    this.communicator = communicator;
+    this.updateListener = updateListener;
+    this.sessionParameters = session;
+    this.chains = chains;
+    this.transports = transports || {};
+
+    this._account = new StorageItem<Account | null>(StorageItem.scopedStorageKey("account"), null, {
+      onChange: (newValue) => {
+        if (newValue) {
+          this.updateListener.onAccountsUpdate([newValue.address]);
+          this.updateListener.onChainUpdate(newValue.activeChainId);
+          this.createWalletClient();
+        } else {
+          this.updateListener.onAccountsUpdate([]);
+        }
+      },
+    });
+    try {
+      if (this.account) this.createWalletClient();
+    } catch (error) {
+      console.error("Failed to create wallet client", error);
+      console.error("Logging out to prevent crash loop");
+      this.clearState();
+    }
+  }
+
+  private get account(): Account | null {
+    const account = this._account.get();
+    if (!account) return null;
+    const chain = this.chains.find((e) => e.id === account.activeChainId);
+    return {
+      ...account,
+      activeChainId: chain?.id || this.chains[0]!.id,
+    };
+  }
+
+  private get session() { return this.account?.session; }
+  private get chainsInfo() { return this._chainsInfo.get(); }
+  private readonly clearState = () => {
+    this._account.remove();
+    this._chainsInfo.remove();
+  };
+
+  public get accounts() { return this.account ? [this.account.address] : []; }
+  public get chain() {
+    const chainId = this.account?.activeChainId || this.chains[0]!.id;
+    return this.chains.find((e) => e.id === chainId)!;
+  }
+
+  createWalletClient() {
+    const session = this.session;
+    const chain = this.chain;
+    const chainInfo = this.chainsInfo.find((e) => e.id === chain.id);
+    if (!this.account) throw new Error("Account is not set");
+    if (!chainInfo) throw new Error(`Chain info for ${chain} wasn't set during handshake`);
+    if (session) {
+      this.walletClient = createZksyncSessionClient({
+        address: this.account.address,
+        sessionKey: session.sessionKey,
+        sessionConfig: session.sessionConfig,
+        contracts: chainInfo.contracts,
+        chain,
+        transport: this.transports[chain.id] || http(),
+      });
+    } else {
+      this.walletClient = undefined;
+    }
+  }
+
+  async handshake(): Promise<Address[]> {
+    let sessionPreferences: SessionPreferences | undefined;
+    let metadata: AppMetadata = {
+      name: "Unknown DApp",
+      icon: null,
+    };
+    try {
+      metadata = this.getMetadata();
+    } catch (error) {
+      console.error("Failed to get website metadata. Proceeding with default one.", error);
+    }
+    if (this.sessionParameters) {
+      try {
+        sessionPreferences = await this.sessionParameters();
+      } catch (error) {
+        console.error("Failed to get session data. Proceeding connection with no session.", error);
+      }
+    }
+    const responseMessage = await this.sendRpcRequest<"eth_requestAccounts", AuthServerRpcSchema>({
+      method: "eth_requestAccounts",
+      params: {
+        metadata,
+        sessionPreferences,
+      },
+    });
+    const handshakeData = responseMessage.content.result!;
+
+    this._chainsInfo.set(handshakeData.chainsInfo);
+    this._account.set({
+      address: handshakeData.account.address,
+      activeChainId: handshakeData.account.activeChainId || this.chain.id,
+      session: handshakeData.account.session,
+    });
+    return this.accounts;
+  }
+
+  switchChain(chainId: number): boolean {
+    const chain = this.chains.find((chain) => chain.id === chainId);
+    const chainInfo = this.chainsInfo.find((e) => e.id === chainId);
+    if (!chainInfo) {
+      console.error(`Chain ${chainId} is not supported or chain info was not set during handshake`);
+      return false;
+    };
+    if (!chain) {
+      console.error(`Chain ${chainId} is missing in the configuration`);
+      return false;
+    };
+    if (chain.id === this.chain.id) return true;
+
+    this._account.set({
+      ...this.account!,
+      activeChainId: chain.id,
+    });
+    return true;
+  }
+
+  async request<TMethod extends Method>(request: RequestArguments<TMethod>): Promise<ExtractReturnType<TMethod>> {
+    const localResult = await this.tryLocalHandling(request);
+    if (localResult !== undefined) return localResult;
+
+    const response = await this.sendRpcRequest(request);
+    return response.content.result as ExtractReturnType<TMethod>;
+  }
+
+  async disconnect() {
+    this.clearState();
+  }
+
+  private async tryLocalHandling<TMethod extends Method>(request: RequestArguments<TMethod>): Promise<ExtractReturnType<TMethod> | undefined> {
+    switch (request.method) {
+      case "eth_estimateGas": {
+        if (!this.walletClient || !this.session) return undefined;
+        const params = request.params as ExtractParams<"eth_estimateGas">;
+        const res = await this.walletClient.request({ method: request.method, params: params });
+        return res as ExtractReturnType<TMethod>;
+      }
+      case "eth_sendTransaction": {
+        if (!this.walletClient || !this.session) return undefined;
+        const params = request.params as ExtractParams<"eth_sendTransaction">;
+        const transactionRequest = params[0];
+        const res = await this.walletClient.sendTransaction(transactionRequest as unknown as SendTransactionParameters);
+        return res as ExtractReturnType<TMethod>;
+      }
+      case "wallet_switchEthereumChain": {
+        const params = request.params as ExtractParams<"wallet_switchEthereumChain">;
+        const chainId = params[0].chainId;
+        const switched = this.switchChain(typeof chainId === "string" ? hexToNumber(chainId as Hash) : chainId);
+        return switched ? (null as ExtractReturnType<TMethod>) : undefined;
+      }
+      case "wallet_getCapabilities": {
+        const chainInfo = this.chainsInfo.find((e) => e.id === this.chain.id);
+        if (!chainInfo) throw new Error("Chain info is not set");
+        return { [this.chain.id]: chainInfo.capabilities } as ExtractReturnType<TMethod>;
+      }
+      case "eth_accounts": {
+        return this.accounts as ExtractReturnType<TMethod>;
+      }
+      default:
+        return undefined;
+    }
+  }
+
+  private async sendRpcRequest<
+    TMethod extends Method<TSchema>,
+    TSchema extends RpcSchemaGeneric = RpcSchema,
+  >(request: RequestArguments<TMethod, TSchema>): Promise<RPCResponseMessage<ExtractReturnType<TMethod, TSchema>>> {
+    // Open popup immediately to make sure popup won't be blocked by Safari
+    await this.communicator.ready();
+
+    const message = this.createRequestMessage<TMethod, TSchema>({
+      action: request,
+      chainId: this.chain.id,
+    });
+    const response: RPCResponseMessage<ExtractReturnType<TMethod, TSchema>>
+      = await this.communicator.postRequestAndWaitForResponse(message);
+
+    const content = response.content;
+    if ("error" in content) throw content.error;
+
+    return response;
+  }
+
+  private createRequestMessage<
+    TMethod extends Method<TSchema>,
+    TSchema extends RpcSchemaGeneric = RpcSchema,
+  >(content: RPCRequestMessage<TMethod, TSchema>["content"]): RPCRequestMessage<TMethod, TSchema> {
+    return {
+      id: crypto.randomUUID(),
+      content,
+    };
+  }
+}

package/src/client-auth-server/WalletProvider.ts

@@ -0,0 +1,114 @@
+import { EventEmitter } from "eventemitter3";
+import type { Address, Chain, Transport } from "viem";
+import { toHex } from "viem";
+
+import { PopupCommunicator } from "../communicator/PopupCommunicator.js";
+import { serializeError, standardErrors } from "../errors/index.js";
+import { getFavicon, getWebsiteName } from "../utils/helpers.js";
+import type {
+  AppMetadata,
+  ProviderInterface,
+  RequestArguments,
+} from "./interface.js";
+import { type ExtractReturnType, type Method } from "./rpc.js";
+import type { SessionPreferences } from "./session.js";
+import { Signer } from "./Signer.js";
+
+const DEFAULT_AUTH_SERVER_URL = "https://auth-test.zksync.dev/confirm";
+
+export type WalletProviderConstructorOptions = {
+  metadata: Partial<AppMetadata> | undefined;
+  chains: readonly Chain[];
+  transports?: Record<number, Transport>;
+  session?: SessionPreferences | (() => SessionPreferences | Promise<SessionPreferences>);
+  authServerUrl?: string;
+};
+
+export class WalletProvider extends EventEmitter implements ProviderInterface {
+  readonly isZksyncSso = true;
+  private signer: Signer;
+
+  constructor({ metadata, chains, transports, session, authServerUrl }: WalletProviderConstructorOptions) {
+    super();
+    const communicator = new PopupCommunicator(authServerUrl || DEFAULT_AUTH_SERVER_URL);
+    this.signer = new Signer({
+      metadata: () => ({
+        name: metadata?.name || getWebsiteName() || "Unknown DApp",
+        icon: metadata?.icon || getFavicon(),
+      }),
+      updateListener: this.updateListener,
+      communicator: communicator,
+      chains,
+      transports,
+      session: typeof session === "object" ? () => session : session,
+    });
+  }
+
+  protected get chain() {
+    return this.signer.chain;
+  }
+
+  public get connected() {
+    return this.signer.accounts.length > 0;
+  }
+
+  public async request<M extends Method>(request: RequestArguments<M>): Promise<ExtractReturnType<M>> {
+    try {
+      switch (request.method) {
+        case "eth_requestAccounts": {
+          return await this.handshake() as ExtractReturnType<M>;
+        }
+        case "personal_sign":
+        case "eth_accounts":
+        case "eth_estimateGas":
+        case "eth_signTransaction":
+        case "eth_sendTransaction":
+        case "eth_signTypedData_v4":
+        case "wallet_addEthereumChain":
+        case "wallet_switchEthereumChain":
+        case "wallet_watchAsset":
+        case "wallet_getCapabilities":
+        case "wallet_sendCalls":
+        case "wallet_showCallsStatus": {
+          if (!this.connected) {
+            throw standardErrors.provider.unauthorized(
+              "Must call 'eth_requestAccounts' before other methods",
+            );
+          }
+          return await this.signer.request(request) as ExtractReturnType<M>;
+        }
+        case "eth_chainId":
+        case "net_version": {
+          return toHex(this.chain.id) as ExtractReturnType<M>;
+        }
+      }
+      throw standardErrors.rpc.methodNotSupported(`Method ${request.method} is not supported.`);
+    } catch (error) {
+      return Promise.reject(serializeError(error, request.method));
+    }
+  }
+
+  public async handshake(): Promise<Address[]> {
+    if (this.connected) {
+      this.emit("connect", { chainId: this.chain.id });
+      return this.signer.accounts;
+    }
+    const accounts = await this.signer.handshake();
+    this.emit("connect", { chainId: this.chain.id });
+    return accounts;
+  }
+
+  async disconnect(): Promise<void> {
+    this.signer.disconnect();
+    this.emit("disconnect", standardErrors.provider.disconnected("User initiated disconnection"));
+  }
+
+  protected readonly updateListener = {
+    onAccountsUpdate: (accounts: Address[]) => {
+      this.emit("accountsChanged", accounts);
+    },
+    onChainUpdate: (chainId: number) => {
+      this.emit("chainChanged", chainId);
+    },
+  };
+}

package/src/client-auth-server/index.ts

@@ -0,0 +1,3 @@
+export * from "./interface.js";
+export * from "./rpc.js";
+export * from "./session.js";

package/src/client-auth-server/interface.ts

@@ -0,0 +1,39 @@
+import { EventEmitter } from "eventemitter3";
+import type { RpcSchema as RpcSchemaGeneric } from "viem";
+
+import type { ExtractParams, ExtractReturnType, Method, RpcSchema } from "./rpc.js";
+
+export interface RequestArguments<M extends Method<TSchema>, TSchema extends RpcSchemaGeneric = RpcSchema> {
+  readonly method: M;
+  readonly params?: ExtractParams<M, TSchema>;
+}
+
+export interface ProviderRpcError extends Error {
+  message: string;
+  code: number;
+  data?: unknown;
+}
+
+interface ProviderMessage {
+  type: string;
+  data: unknown;
+}
+
+interface ProviderConnectInfo {
+  readonly chainId: string;
+}
+
+export interface ProviderInterface extends EventEmitter {
+  request<M extends Method>(args: RequestArguments<M>): Promise<ExtractReturnType<M>>;
+  disconnect(): Promise<void>;
+  on(event: "connect", listener: (info: ProviderConnectInfo) => void): this;
+  on(event: "disconnect", listener: (error: ProviderRpcError) => void): this;
+  on(event: "chainChanged", listener: (chainId: string) => void): this;
+  on(event: "accountsChanged", listener: (accounts: string[]) => void): this;
+  on(event: "message", listener: (message: ProviderMessage) => void): this;
+}
+
+export interface AppMetadata {
+  name: string;
+  icon: string | null;
+}

package/src/client-auth-server/rpc.ts

@@ -0,0 +1,69 @@
+import type { Address, Chain, Hash, PublicRpcSchema, RpcSchema as RpcSchemaGeneric, WalletRpcSchema } from "viem";
+
+import type { SessionRequiredContracts } from "../client/index.js";
+import type { Message } from "../communicator/index.js";
+import type { SerializedEthereumRpcError } from "../errors/index.js";
+import type { SessionConfig } from "../utils/session.js";
+import type { AppMetadata, RequestArguments } from "./interface.js";
+import type { SessionPreferences } from "./session.js";
+
+export type AuthServerRpcSchema = [
+  {
+    Method: "eth_requestAccounts";
+    Parameters: {
+      metadata: AppMetadata;
+      sessionPreferences?: SessionPreferences;
+    };
+    ReturnType: {
+      account: {
+        address: Address;
+        activeChainId: Chain["id"];
+        session?: {
+          sessionKey: Hash;
+          sessionConfig: SessionConfig;
+        };
+      };
+      chainsInfo: {
+        id: Chain["id"];
+        capabilities: Record<string, unknown>;
+        contracts: SessionRequiredContracts;
+      }[];
+    };
+  },
+];
+export type RpcSchema = WalletRpcSchema | PublicRpcSchema | AuthServerRpcSchema;
+export type Method<TSchema extends RpcSchemaGeneric = RpcSchema> = TSchema[number]["Method"];
+export type ExtractParams<
+  TMethod extends Method<TSchema>,
+  TSchema extends RpcSchemaGeneric = RpcSchema,
+> = TSchema extends Array<infer T>
+  ? T extends { Method: TMethod; Parameters: infer R }
+    ? R
+    : never
+  : never;
+export type ExtractReturnType<
+  TMethod extends Method<TSchema>,
+  TSchema extends RpcSchemaGeneric = RpcSchema,
+> = TSchema extends Array<infer T>
+  ? T extends { Method: TMethod; ReturnType: infer R }
+    ? R
+    : never
+  : never;
+
+export interface RPCRequestMessage<
+  TMethod extends Method<TSchema>,
+  TSchema extends RpcSchemaGeneric = RpcSchema,
+> extends Message {
+  content: {
+    action: RequestArguments<TMethod, TSchema>;
+    chainId: number;
+  };
+}
+
+export interface RPCResponseMessage<T = unknown> extends Message {
+  requestId: NonNullable<Message["requestId"]>;
+  content: {
+    result?: T; // For successful responses
+    error?: SerializedEthereumRpcError; // For error responses
+  };
+}

package/src/client-auth-server/session.ts

@@ -0,0 +1,139 @@
+import { type AbiFunction, type Address, type Hash, toFunctionSelector, toHex } from "viem";
+
+import { ConstraintCondition, type Limit, LimitType, LimitUnlimited, LimitZero, type SessionConfig } from "../utils/session.js";
+
+type PartialLimit = bigint | {
+  limit: bigint;
+  period?: bigint;
+} | {
+  limitType: "lifetime" | LimitType.Lifetime;
+  limit: bigint;
+} | {
+  limitType: "unlimited" | LimitType.Unlimited;
+} | {
+  limitType: "allowance" | LimitType.Allowance;
+  limit: bigint;
+  period: bigint;
+};
+
+type PartialCallPolicy = {
+  address: Address;
+  function?: string | AbiFunction;
+  selector?: Hash; // if function is not provided
+  maxValuePerUse?: bigint;
+  valueLimit?: PartialLimit;
+  constraints?: {
+    index: number;
+    condition?: ConstraintCondition | keyof typeof ConstraintCondition;
+    refValue?: Hash;
+    limit?: PartialLimit;
+  }[];
+};
+
+type PartialTransferPolicy = {
+  to: Address;
+  maxValuePerUse?: bigint;
+  valueLimit?: PartialLimit;
+};
+
+export interface SessionPreferences {
+  expiresAt?: bigint | Date;
+  feeLimit?: PartialLimit;
+  contractCalls?: PartialCallPolicy[];
+  transfers?: PartialTransferPolicy[];
+};
+
+const formatLimitPreferences = (limit: PartialLimit): Limit => {
+  /* Just bigint was passed */
+  if (typeof limit === "bigint") {
+    return {
+      limitType: LimitType.Lifetime,
+      limit,
+      period: 0n,
+    };
+  }
+
+  /* LimitType was specified */
+  if ("limitType" in limit) {
+    if (limit.limitType === "lifetime" || limit.limitType === LimitType.Lifetime) {
+      return {
+        limitType: LimitType.Lifetime,
+        limit: limit.limit,
+        period: 0n,
+      };
+    } else if (limit.limitType === "unlimited" || limit.limitType === LimitType.Unlimited) {
+      return {
+        limitType: LimitType.Unlimited,
+        limit: 0n,
+        period: 0n,
+      };
+    } else if (limit.limitType === "allowance" || limit.limitType === LimitType.Allowance) {
+      return {
+        limitType: LimitType.Allowance,
+        limit: limit.limit,
+        period: limit.period,
+      };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    throw new Error(`Invalid limit type: ${(limit as any).limitType}`);
+  }
+
+  /* LimitType not selected */
+  if (!limit.period) {
+    return {
+      limitType: LimitType.Lifetime,
+      limit: limit.limit,
+      period: 0n,
+    };
+  }
+  return {
+    limitType: LimitType.Allowance,
+    limit: limit.limit,
+    period: limit.period,
+  };
+};
+
+const formatDatePreferences = (date: bigint | Date): bigint => {
+  if (date instanceof Date) {
+    return BigInt(Math.floor(date.getTime() / 1000));
+  }
+  return date;
+};
+
+export function formatSessionPreferences(
+  preferences: SessionPreferences,
+  defaults: {
+    expiresAt: bigint;
+    feeLimit: Limit;
+  },
+): Omit<SessionConfig, "signer"> {
+  return {
+    expiresAt: preferences.expiresAt ? formatDatePreferences(preferences.expiresAt) : defaults.expiresAt,
+    feeLimit: preferences.feeLimit ? formatLimitPreferences(preferences.feeLimit) : defaults.feeLimit,
+    callPolicies: preferences.contractCalls?.map((policy) => {
+      const valueLimit = policy.valueLimit ? formatLimitPreferences(policy.valueLimit) : LimitZero;
+      const selector = policy.function ? toFunctionSelector(policy.function) : policy.selector;
+      if (!selector) throw new Error("Missing function or selector in contract call policy");
+      return {
+        target: policy.address,
+        maxValuePerUse: policy.maxValuePerUse ?? valueLimit.limit,
+        valueLimit,
+        selector: selector,
+        constraints: policy.constraints?.map((constraint) => ({
+          index: BigInt(constraint.index),
+          condition: typeof constraint.condition == "string" ? ConstraintCondition[constraint.condition] : (constraint.condition ?? 0),
+          refValue: constraint.refValue ?? toHex("", { size: 32 }),
+          limit: constraint.limit ? formatLimitPreferences(constraint.limit) : LimitUnlimited,
+        })) ?? [],
+      };
+    }) ?? [],
+    transferPolicies: preferences.transfers?.map((policy) => {
+      const valueLimit = policy.valueLimit ? formatLimitPreferences(policy.valueLimit) : LimitZero;
+      return {
+        target: policy.to,
+        maxValuePerUse: policy.maxValuePerUse ?? valueLimit.limit,
+        valueLimit,
+      };
+    }) ?? [],
+  };
+}