@account-kit/signer 4.0.0-alpha.0

package/src/client/types.ts

@@ -0,0 +1,121 @@
+import type { Address } from "@aa-sdk/core";
+import type { TSignedRequest, getWebAuthnAttestation } from "@turnkey/http";
+import type { Hex } from "viem";
+
+export type CredentialCreationOptionOverrides = {
+  publicKey?: Partial<CredentialCreationOptions["publicKey"]>;
+} & Pick<CredentialCreationOptions, "signal">;
+
+// [!region User]
+export type User = {
+  email?: string;
+  orgId: string;
+  userId: string;
+  address: Address;
+  credentialId?: string;
+};
+// [!endregion User]
+
+export type ExportWalletParams = {
+  iframeContainerId: string;
+  iframeElementId?: string;
+};
+
+export type CreateAccountParams =
+  | {
+      type: "email";
+      email: string;
+      expirationSeconds?: number;
+      redirectParams?: URLSearchParams;
+    }
+  | {
+      type: "passkey";
+      username: string;
+      creationOpts?: CredentialCreationOptionOverrides;
+    };
+
+export type EmailAuthParams = {
+  email: string;
+  expirationSeconds?: number;
+  targetPublicKey: string;
+  redirectParams?: URLSearchParams;
+};
+
+export type SignupResponse = {
+  orgId: string;
+  userId?: string;
+  address?: Address;
+};
+
+export type SignerRoutes = SignerEndpoints[number]["Route"];
+export type SignerBody<T extends SignerRoutes> = Extract<
+  SignerEndpoints[number],
+  { Route: T }
+>["Body"];
+export type SignerResponse<T extends SignerRoutes> = Extract<
+  SignerEndpoints[number],
+  { Route: T }
+>["Response"];
+
+export type SignerEndpoints = [
+  {
+    Route: "/v1/signup";
+    Body:
+      | (Omit<EmailAuthParams, "redirectParams"> & { redirectParams?: string })
+      | {
+          passkey: {
+            challenge: string;
+            attestation: Awaited<ReturnType<typeof getWebAuthnAttestation>>;
+          };
+        };
+    Response: SignupResponse;
+  },
+  {
+    Route: "/v1/whoami";
+    Body: {
+      stampedRequest: TSignedRequest;
+    };
+    Response: User;
+  },
+  {
+    Route: "/v1/auth";
+    Body: Omit<EmailAuthParams, "redirectParams"> & { redirectParams?: string };
+    Response: {
+      orgId: string;
+    };
+  },
+  {
+    Route: "/v1/lookup";
+    Body: {
+      email: string;
+    };
+    Response: {
+      orgId: string | null;
+    };
+  },
+  {
+    Route: "/v1/sign-payload";
+    Body: {
+      stampedRequest: TSignedRequest;
+    };
+    Response: {
+      signature: Hex;
+    };
+  }
+];
+
+export type AlchemySignerClientEvents = {
+  connected(user: User): void;
+  authenticating(): void;
+  connectedEmail(user: User, bundle: string): void;
+  connectedPasskey(user: User): void;
+  disconnected(): void;
+};
+
+export type AlchemySignerClientEvent = keyof AlchemySignerClientEvents;
+
+export type GetWebAuthnAttestationResult = {
+  attestation: Awaited<ReturnType<typeof getWebAuthnAttestation>>;
+  challenge: ArrayBuffer;
+  authenticatorUserId: ArrayBuffer;
+};

package/src/errors.ts

@@ -0,0 +1,15 @@
+import { BaseError } from "@aa-sdk/core";
+
+export class NotAuthenticatedError extends BaseError {
+  constructor() {
+    super(
+      [
+        "Signer not authenticated",
+        "Please authenticate to use this signer",
+      ].join("\n"),
+      {
+        docsPath: "/signers/alchemy-signer/introduction.html",
+      }
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export type * from "./signer.js";
+export { AlchemyWebSigner } from "./signer.js";
+
+export type * from "./types.js";
+export { AlchemySignerStatus } from "./types.js";
+
+export { BaseSignerClient } from "./client/base.js";
+export { AlchemySignerWebClient } from "./client/index.js";
+export type * from "./client/types.js";
+export { DEFAULT_SESSION_MS } from "./session/manager.js";

package/src/session/manager.ts

@@ -0,0 +1,249 @@
+import EventEmitter from "eventemitter3";
+import { z } from "zod";
+import {
+  createJSONStorage,
+  persist,
+  subscribeWithSelector,
+} from "zustand/middleware";
+import { createStore, type Mutate, type StoreApi } from "zustand/vanilla";
+import type { BaseSignerClient } from "../client/base";
+import type { User } from "../client/types";
+import type { Session, SessionManagerEvents } from "./types";
+
+export const DEFAULT_SESSION_MS = 15 * 60 * 1000; // 15 minutes
+
+export const SessionManagerParamsSchema = z.object({
+  sessionKey: z.string().default("alchemy-signer-session"),
+  storage: z
+    .enum(["localStorage", "sessionStorage"])
+    .default("localStorage")
+    .or(z.custom<Storage>()),
+  expirationTimeMs: z
+    .number()
+    .default(DEFAULT_SESSION_MS)
+    .describe(
+      "The time in milliseconds that a session should last before expiring [default: 15 minutes]"
+    ),
+  client: z.custom<BaseSignerClient>(),
+});
+
+export type SessionManagerParams = z.input<typeof SessionManagerParamsSchema>;
+
+type SessionState = {
+  session: Session | null;
+};
+
+type Store = Mutate<
+  StoreApi<SessionState>,
+  [["zustand/subscribeWithSelector", never], ["zustand/persist", SessionState]]
+>;
+
+export class SessionManager {
+  private sessionKey: string;
+  private client: BaseSignerClient;
+  private eventEmitter: EventEmitter<SessionManagerEvents>;
+  readonly expirationTimeMs: number;
+  private store: Store;
+
+  constructor(params: SessionManagerParams) {
+    const {
+      sessionKey,
+      storage: storageType,
+      expirationTimeMs,
+      client,
+    } = SessionManagerParamsSchema.parse(params);
+    this.sessionKey = sessionKey;
+    const storage =
+      typeof storageType === "string"
+        ? storageType === "localStorage"
+          ? localStorage
+          : sessionStorage
+        : storageType;
+    this.expirationTimeMs = expirationTimeMs;
+    this.client = client;
+    this.eventEmitter = new EventEmitter<SessionManagerEvents>();
+
+    this.store = createStore(
+      subscribeWithSelector(
+        persist(this.getInitialState, {
+          name: this.sessionKey,
+          storage: createJSONStorage<SessionState>(() => storage),
+        })
+      )
+    );
+
+    this.registerEventListeners();
+  }
+
+  public getSessionUser = async (): Promise<User | null> => {
+    const existingSession = this.getSession();
+    if (existingSession == null) {
+      return null;
+    }
+
+    switch (existingSession.type) {
+      case "email": {
+        const result = await this.client
+          .completeEmailAuth({
+            bundle: existingSession.bundle,
+            orgId: existingSession.user.orgId,
+          })
+          .catch((e) => {
+            console.warn("Failed to load user from session", e);
+            return null;
+          });
+
+        if (!result) {
+          this.clearSession();
+          return null;
+        }
+
+        return result;
+      }
+      case "passkey": {
+        // we don't need to do much here if we already have a user
+        // this will setup the client with the user context, but
+        // requests still have to be signed by the user on first request
+        // so this is fine
+        return this.client.lookupUserWithPasskey(existingSession.user);
+      }
+      default:
+        throw new Error("Unknown session type");
+    }
+  };
+
+  public clearSession = () => {
+    this.store.setState({ session: null });
+  };
+
+  public setTemporarySession = (session: { orgId: string }) => {
+    // temporary session must be placed in localStorage so that it can be accessed across tabs
+    localStorage.setItem(
+      `${this.sessionKey}:temporary`,
+      JSON.stringify(session)
+    );
+  };
+
+  public getTemporarySession = (): { orgId: string } | null => {
+    // temporary session must be placed in localStorage so that it can be accessed across tabs
+    const sessionStr = localStorage.getItem(`${this.sessionKey}:temporary`);
+
+    if (!sessionStr) {
+      return null;
+    }
+
+    return JSON.parse(sessionStr);
+  };
+
+  on = <E extends keyof SessionManagerEvents>(
+    event: E,
+    listener: SessionManagerEvents[E]
+  ) => {
+    this.eventEmitter.on(event, listener as any);
+
+    return () => this.eventEmitter.removeListener(event, listener as any);
+  };
+
+  private getSession = (): Session | null => {
+    const session = this.store.getState().session;
+
+    if (!session) {
+      return null;
+    }
+
+    /**
+     * TODO: this isn't really good enough
+     * A user's session could be about to expire and we would still return it
+     *
+     * Instead we should check if a session is about to expire and refresh it
+     * We should revisit this later
+     */
+    if (session.expirationDateMs < Date.now()) {
+      this.store.setState({ session: null });
+      return null;
+    }
+
+    return session;
+  };
+
+  private setSession = (
+    session:
+      | Omit<Extract<Session, { type: "email" }>, "expirationDateMs">
+      | Omit<Extract<Session, { type: "passkey" }>, "expirationDateMs">
+  ) => {
+    this.store.setState({
+      session: {
+        ...session,
+        expirationDateMs: Date.now() + this.expirationTimeMs,
+      },
+    });
+  };
+
+  public initialize() {
+    this.getSessionUser()
+      .then((user) => {
+        // once we complete auth we can update the state of the session to connected or disconnected
+        if (user) this.eventEmitter.emit("connected", this.getSession()!);
+        else this.eventEmitter.emit("disconnected");
+      })
+      .finally(() => {
+        this.eventEmitter.emit("initialized");
+      });
+  }
+
+  private getInitialState(): SessionState {
+    return {
+      session: null,
+    };
+  }
+
+  private registerEventListeners = () => {
+    this.store.subscribe(
+      ({ session }) => session,
+      (session, prevSession) => {
+        if (session != null && prevSession == null) {
+          this.eventEmitter.emit("connected", session);
+        } else if (session == null && prevSession != null) {
+          this.eventEmitter.emit("disconnected");
+        }
+      }
+    );
+
+    this.client.on("disconnected", () => this.clearSession());
+
+    this.client.on("connectedEmail", (user, bundle) => {
+      const existingSession = this.getSession();
+      if (
+        existingSession != null &&
+        existingSession.type === "email" &&
+        existingSession.user.userId === user.userId &&
+        // if the bundle is different, then we've refreshed the session
+        // so we need to reset the session
+        existingSession.bundle === bundle
+      ) {
+        return;
+      }
+
+      this.setSession({ type: "email", user, bundle });
+    });
+
+    this.client.on("connectedPasskey", (user) => {
+      const existingSession = this.getSession();
+      if (
+        existingSession != null &&
+        existingSession.type === "passkey" &&
+        existingSession.user.userId === user.userId
+      ) {
+        return;
+      }
+
+      this.setSession({ type: "passkey", user });
+    });
+
+    // sync local state if persisted state has changed from another tab
+    window.addEventListener("focus", () => {
+      this.store.persist.rehydrate();
+      this.initialize();
+    });
+  };
+}

package/src/session/types.ts

@@ -0,0 +1,16 @@
+import type { User } from "../client/types";
+
+export type Session =
+  | {
+      type: "email";
+      bundle: string;
+      expirationDateMs: number;
+      user: User;
+    }
+  | { type: "passkey"; user: User; expirationDateMs: number };
+
+export type SessionManagerEvents = {
+  connected(session: Session): void;
+  disconnected(): void;
+  initialized(): void;
+};

package/src/signer.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { BaseAlchemySigner } from "./base.js";
+import {
+  AlchemySignerClientParamsSchema,
+  AlchemySignerWebClient,
+} from "./client/index.js";
+import type { CredentialCreationOptionOverrides } from "./client/types.js";
+import { SessionManagerParamsSchema } from "./session/manager.js";
+
+export type AuthParams =
+  | { type: "email"; email: string; redirectParams?: URLSearchParams }
+  | { type: "email"; bundle: string; orgId?: string }
+  | {
+      type: "passkey";
+      createNew: false;
+    }
+  | {
+      type: "passkey";
+      createNew: true;
+      username: string;
+      creationOpts?: CredentialCreationOptionOverrides;
+    };
+
+export const AlchemySignerParamsSchema = z
+  .object({
+    client: z
+      .custom<AlchemySignerWebClient>()
+      .or(AlchemySignerClientParamsSchema),
+  })
+  .extend({
+    sessionConfig: SessionManagerParamsSchema.omit({ client: true }).optional(),
+  });
+
+export type AlchemySignerParams = z.input<typeof AlchemySignerParamsSchema>;
+
+/**
+ * A SmartAccountSigner that can be used with any SmartContractAccount
+ */
+export class AlchemyWebSigner extends BaseAlchemySigner<AlchemySignerWebClient> {
+  constructor(params_: AlchemySignerParams) {
+    const { sessionConfig, ...params } =
+      AlchemySignerParamsSchema.parse(params_);
+
+    let client: AlchemySignerWebClient;
+    if ("connection" in params.client) {
+      client = new AlchemySignerWebClient(params.client);
+    } else {
+      client = params.client;
+    }
+    super({
+      client,
+      sessionConfig,
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,17 @@
+import type { User } from "./client/types";
+
+export type AlchemySignerEvents = {
+  connected(user: User): void;
+  disconnected(): void;
+  statusChanged(status: AlchemySignerStatus): void;
+};
+
+export type AlchemySignerEvent = keyof AlchemySignerEvents;
+
+export enum AlchemySignerStatus {
+  INITIALIZING = "INITIALIZING",
+  CONNECTED = "CONNECTED",
+  DISCONNECTED = "DISCONNECTED",
+  AUTHENTICATING = "AUTHENTICATING",
+  AWAITING_EMAIL_AUTH = "AWAITING_EMAIL_AUTH",
+}

package/src/utils/base64UrlEncode.ts

@@ -0,0 +1,7 @@
+export const base64UrlEncode = (challenge: ArrayBuffer): string => {
+  return Buffer.from(challenge)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+};

package/src/utils/generateRandomBuffer.ts

@@ -0,0 +1,5 @@
+export const generateRandomBuffer = (): ArrayBuffer => {
+  const arr = new Uint8Array(32);
+  crypto.getRandomValues(arr);
+  return arr.buffer;
+};

package/src/version.ts

@@ -0,0 +1,3 @@
+// This file is autogenerated by inject-version.ts. Any changes will be
+// overwritten on commit!
+export const VERSION = "4.0.0-alpha.0";