@account-kit/signer 4.63.1 → 4.64.0

package/src/client/server.ts

@@ -0,0 +1,149 @@
+import type { ConnectionConfig } from "@aa-sdk/core";
+import { ApiKeyStamper } from "@turnkey/api-key-stamper";
+import type { CreateAccountParams, SignupResponse, User } from "./types";
+import { BaseSignerClient } from "./base.js";
+import { NotAuthenticatedError, UnsupportedFeatureError } from "../errors.js";
+import { TurnkeyClient } from "@turnkey/http";
+import type { AuthParams } from "../signer";
+import { p256 } from "@noble/curves/p256";
+import { bytesToHex } from "@noble/curves/utils";
+
+export interface ServerSignerClientParams {
+  connection: ConnectionConfig;
+}
+
+const unimplementedFunction = (feature: string) => {
+  return () => {
+    throw new UnsupportedFeatureError(feature);
+  };
+};
+
+const createDummyStamper = () => {
+  return {
+    stamp: () => {
+      throw new NotAuthenticatedError();
+    },
+  };
+};
+
+/**
+ * ServerSignerClient is a client for signing messages using an access key.
+ * It extends the BaseSignerClient and uses the ApiKeyStamper for signing.
+ * Primarily intended to be used server-side.
+ */
+export class ServerSignerClient extends BaseSignerClient<undefined> {
+  /**
+   * Creates an instance of ServerSignerClient.
+   *
+   * @param {ServerSignerClientParams} params The parameters for the client, including the access key and connection configuration
+   * @param {ConnectionConfig} params.connection The connection configuration for the client
+   * @param {string} params.accessKey The access key to be used for authentication
+   * @param {string | undefined} params.accountId An optional ID to identify the account. Only required when using a single access key for multiple signers.
+   */
+  constructor({ connection }: ServerSignerClientParams) {
+    // we will re-recreate the turnkey client (including the stamper) when we authenticate
+    const stamper = createDummyStamper();
+
+    super({ connection, stamper });
+  }
+
+  /**
+   * Unsets the user for the client
+   */
+  public override disconnect = async (): Promise<void> => {
+    this.user = undefined;
+  };
+
+  /**
+   * Creates a new user with the given parameters.
+   *
+   * @param {CreateAccountParams} params The parameters for creating the account
+   * @returns {Promise<SignupResponse>} A promise that resolves to the signup response
+   */
+  public override createAccount = async (
+    params: CreateAccountParams,
+  ): Promise<SignupResponse> => {
+    if (params.type !== "accessKey") {
+      throw new Error(
+        "ServerSignerClient only supports account creation via access key",
+      );
+    }
+
+    return this.request("/v1/signup", {
+      accessKey: {
+        publicKey: params.publicKey,
+        accountId: params.accountId,
+      },
+    });
+  };
+
+  /**
+   * Authenticates the user with an access key.
+   *
+   * @param {Extract<AuthParams, { type: "accessKey" }>} params The parameters for the authentication
+   * @returns {Promise<User>} A promise that resolves to the user
+   */
+  public authenticateWithAccessKey = async ({
+    accessKey,
+    accountId,
+  }: Extract<AuthParams, { type: "accessKey" }>): Promise<User> => {
+    const publicKey = bytesToHex(p256.getPublicKey(accessKey));
+
+    const user = await this.lookupUserByAccessKey({
+      publicKey,
+      accountId,
+    });
+
+    const orgId =
+      user?.orgId ??
+      (
+        await this.createAccount({
+          type: "accessKey",
+          publicKey,
+          accountId,
+        })
+      )?.orgId;
+
+    return this.completeAuthWithApiKey(
+      { publicKey, privateKey: accessKey },
+      orgId,
+    );
+  };
+
+  private completeAuthWithApiKey = async (
+    apiKey: { publicKey: string; privateKey: string },
+    subOrgId: string,
+  ) => {
+    this.turnkeyClient = new TurnkeyClient(
+      { baseUrl: "https://api.turnkey.com" },
+      new ApiKeyStamper({
+        apiPrivateKey: apiKey.privateKey,
+        apiPublicKey: apiKey.publicKey,
+      }),
+    );
+
+    const user = await this.whoami(subOrgId);
+    this.user = user;
+    return user;
+  };
+
+  /**
+   * Unimplemented functions for server signer.
+   * Required to extend the BaseSignerClient class.
+   */
+  public initSmsAuth = unimplementedFunction("Sms auth");
+  public submitJwt = unimplementedFunction("Jwt");
+  protected initSessionStamper = unimplementedFunction("Sessions");
+  protected initWebauthnStamper = unimplementedFunction("Webauthn");
+  override initEmailAuth = unimplementedFunction("Email auth");
+  public override submitOtpCode = unimplementedFunction("Otp code submission");
+  override completeAuthWithBundle = unimplementedFunction("Auth with bundle");
+  override oauthWithRedirect = unimplementedFunction("OAuth redirect");
+  override oauthWithPopup = unimplementedFunction("OAuth popup");
+  override exportWallet = unimplementedFunction("Wallet export");
+  override targetPublicKey = unimplementedFunction("Target public key");
+  override getWebAuthnAttestation = unimplementedFunction(
+    "WebAuthn attestation",
+  );
+  override getOauthConfig = unimplementedFunction("OAuth config");
+}

package/src/client/types.ts

@@ -64,6 +64,11 @@ export type CreateAccountParams =
       type: "passkey";
       username: string;
       creationOpts?: CredentialCreationOptionOverrides;
+    }
+  | {
+      type: "accessKey";
+      publicKey: string;
+      accountId?: string;
     };
 
 export type EmailType = "magicLink" | "otp";
@@ -83,6 +88,13 @@ export type SmsAuthParams = {
   targetPublicKey: string;
 };
 
+export type AccessKeyAuthParamsPublicKeyOnly = {
+  accessKey: {
+    publicKey: string;
+    accountId?: string;
+  };
+};
+
 export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
   expirationSeconds?: number;
   fetchIdTokenOnly?: boolean;
@@ -173,7 +185,8 @@ export type SignerEndpoints = [
             challenge: string;
             attestation: Awaited<ReturnType<typeof getWebAuthnAttestation>>;
           };
-        };
+        }
+      | AccessKeyAuthParamsPublicKeyOnly;
     Response: SignupResponse;
   },
   {
@@ -202,6 +215,10 @@ export type SignerEndpoints = [
     Body: {
       email?: string;
       phone?: string;
+      accessKey?: {
+        publicKey: string;
+        accountId?: string;
+      };
     };
     Response: {
       orgId: string | null;

package/src/errors.ts

@@ -33,3 +33,10 @@ export class MfaRequiredError extends BaseError {
     this.multiFactors = multiFactors;
   }
 }
+
+export class UnsupportedFeatureError extends BaseError {
+  override name = "UnsupportedFeatureError";
+  constructor(feature: string) {
+    super(`${feature} not supported by this signer`);
+  }
+}

package/src/index.ts

@@ -1,10 +1,16 @@
 export { BaseAlchemySigner } from "./base.js";
+export {
+  AlchemyServerSigner,
+  createServerSigner,
+  generateAccessKey,
+} from "./serverSigner.js";
 export { BaseSignerClient } from "./client/base.js";
 export {
   AlchemySignerWebClient,
   OauthCancelledError,
   OauthFailedError,
 } from "./client/index.js";
+export { ServerSignerClient } from "./client/server.js";
 export type * from "./client/types.js";
 export {
   NotAuthenticatedError,

package/src/serverSigner.ts

@@ -0,0 +1,171 @@
+import {
+  type AuthorizationRequest,
+  type SmartAccountSigner,
+  unpackSignRawMessageBytes,
+} from "@aa-sdk/core";
+import {
+  ServerSignerClient,
+  type ServerSignerClientParams,
+} from "./client/server.js";
+import {
+  hashMessage,
+  hashTypedData,
+  type Address,
+  type Hex,
+  type SignableMessage,
+  type SignedAuthorization,
+  type TypedData,
+  type TypedDataDefinition,
+} from "viem";
+import { hashAuthorization } from "viem/utils";
+import type { AccessKeyAuthParams } from "./signer.js";
+import { SolanaSigner } from "./solanaSigner.js";
+import { p256 } from "@noble/curves/p256";
+import { bytesToHex } from "@noble/curves/utils";
+
+/**
+ * AlchemyServerSigner is a signer that can sign messages and typed data using an access key.
+ * It extends the SmartAccountSigner interface and uses the ServerSignerClient to sign requests.
+ * Primarily intended to be used server-side.
+ */
+export class AlchemyServerSigner implements SmartAccountSigner {
+  inner: ServerSignerClient;
+  signerType = "alchemy-server-signer";
+
+  /**
+   * Creates an instance of AlchemyServerSigner.
+   *
+   * @param {ServerSignerClient} client The underlying signer client
+   */
+  constructor(client: ServerSignerClient) {
+    this.inner = client;
+  }
+
+  /**
+   * Gets the address of the user from the signer client.
+   *
+   * @returns {Promise<Address>} The address of the user
+   * @throws {Error} If the user cannot be retrieved from the signer client
+   */
+  async getAddress(): Promise<Address> {
+    const { address } = await this.inner.whoami();
+    return address;
+  }
+
+  /**
+   * Signs a message using the inner client.
+   *
+   * @param {SignableMessage} msg The message to sign
+   * @returns {Promise<Hex>} The signed message
+   */
+  async signMessage(msg: SignableMessage): Promise<Hex> {
+    const messageHash = hashMessage(msg);
+    return this.inner.signRawMessage(messageHash);
+  }
+
+  /**
+   * Signs typed data using the inner client.
+   *
+   * @param {TypedDataDefinition<TTypedData, TPrimaryType>} params The typed data to sign
+   * @returns {Promise<Hex>} The signed typed data
+   */
+  async signTypedData<
+    const TTypedData extends TypedData | Record<string, unknown>,
+    TPrimaryType extends keyof TTypedData | "EIP712Domain" = keyof TTypedData,
+  >(params: TypedDataDefinition<TTypedData, TPrimaryType>): Promise<Hex> {
+    const messageHash = hashTypedData(params);
+    return this.inner.signRawMessage(messageHash);
+  }
+
+  /**
+   * Signs an authorization using the inner client.
+   *
+   * @param {Authorization<number, false>} unsignedAuthorization The unsigned authorization to sign
+   * @returns {Promise<Authorization<number, true>>} The signed authorization
+   */
+  async signAuthorization(
+    unsignedAuthorization: AuthorizationRequest<number>,
+  ): Promise<SignedAuthorization<number>> {
+    const hashedAuthorization = hashAuthorization(unsignedAuthorization);
+    const signedAuthorizationHex =
+      await this.inner.signRawMessage(hashedAuthorization);
+    const signature = unpackSignRawMessageBytes(signedAuthorizationHex);
+    const { address, contractAddress, ...unsignedAuthorizationRest } =
+      unsignedAuthorization;
+
+    return {
+      ...unsignedAuthorizationRest,
+      ...signature,
+      address: address ?? contractAddress,
+    };
+  }
+
+  /**
+   * Creates a new instance of `SolanaSigner` using the inner client.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyServerSigner } from "@account-kit/signer";
+   *
+   * const signer = await createServerSigner({
+   *   auth: { accessKey },
+   *   connection: {
+   *     apiKey: "alchemy-api-key",
+   *   },
+   * });
+   *
+   * const solanaSigner = signer.toSolanaSigner();
+   * ```
+   *
+   * @returns {SolanaSigner} A new instance of `SolanaSigner`
+   */
+  toSolanaSigner(): SolanaSigner {
+    return new SolanaSigner(this.inner);
+  }
+}
+
+type CreateServerSignerParams = ServerSignerClientParams & {
+  auth: AccessKeyAuthParams;
+};
+
+/**
+ * Creates a new server signer.
+ *
+ * @example
+ * ```ts
+ *  const signer = await createServerSigner({
+ *   auth: { accessKey },
+ *   connection: {
+ *     apiKey: "alchemy-api-key",
+ *   }
+ * });
+ *
+ * console.log("Signer address:", await signer.getAddress());
+ * ```
+ *
+ * @param {CreateServerSignerParams} params Parameters
+ * @param {AccessKeyAuthParams} params.auth Authentication config for the server signer
+ * @param {ConnectionConfig} params.connection Connection config for the server signer
+ * @returns {Promise<AlchemyServerSigner>} A promise that resolves to a server signer
+ */
+export const createServerSigner = async (
+  params: CreateServerSignerParams,
+): Promise<AlchemyServerSigner> => {
+  const client = new ServerSignerClient(params);
+  const signer = new AlchemyServerSigner(client);
+
+  await signer.inner.authenticateWithAccessKey({
+    ...params.auth,
+    type: "accessKey",
+  });
+
+  return signer;
+};
+
+/**
+ * Generates a new access key for use in the server signer
+ *
+ * @returns {Hex} A randomly generated access key
+ */
+export const generateAccessKey = () =>
+  bytesToHex(p256.utils.randomPrivateKey());

package/src/signer.ts

@@ -11,6 +11,11 @@ import type {
 } from "./client/types.js";
 import { SessionManagerParamsSchema } from "./session/manager.js";
 
+export type AccessKeyAuthParams = {
+  accessKey: string;
+  accountId?: string;
+};
+
 export type AuthParams =
   | {
       type: "email";
@@ -64,7 +69,8 @@ export type AuthParams =
       type: "otp";
       otpCode: string;
       multiFactors?: VerifyMfaParams[];
-    };
+    }
+  | ({ type: "accessKey" } & AccessKeyAuthParams);
 
 export type OauthProviderConfig =
   | {

package/src/version.ts

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