@aptos-labs/ts-sdk 1.35.0-zeta.2 → 1.36.0-zeta.0

package/src/core/crypto/multiEd25519.ts

@@ -1,12 +1,12 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+import { AptosConfig } from "../../api";
 import { Deserializer, Serializer } from "../../bcs";
-import { SigningScheme as AuthenticationKeyScheme } from "../../types";
+import { SigningScheme as AuthenticationKeyScheme, HexInput } from "../../types";
 import { AuthenticationKey } from "../authenticationKey";
 import { Ed25519PublicKey, Ed25519Signature } from "./ed25519";
 import { AbstractMultiKey } from "./multiKey";
-import { VerifySignatureArgs } from "./publicKey";
 import { Signature } from "./signature";
 
 /**
@@ -106,7 +106,7 @@ export class MultiEd25519PublicKey extends AbstractMultiKey {
    * @group Implementation
    * @category Serialization
    */
-  verifySignature(args: VerifySignatureArgs): boolean {
+  verifySignature(args: { message: HexInput; signature: MultiEd25519Signature }): boolean {
     const { message, signature } = args;
     if (!(signature instanceof MultiEd25519Signature)) {
       return false;
@@ -141,6 +141,14 @@ export class MultiEd25519PublicKey extends AbstractMultiKey {
     return true;
   }
 
+  async verifySignatureAsync(args: {
+    aptosConfig: AptosConfig;
+    message: HexInput;
+    signature: MultiEd25519Signature;
+  }): Promise<boolean> {
+    return this.verifySignature(args);
+  }
+
   /**
    * Generates an authentication key based on the current instance's byte representation.
    * This function is essential for creating a secure authentication key that can be used for various cryptographic operations.

package/src/core/crypto/multiKey.ts

@@ -1,10 +1,11 @@
-import { SigningScheme as AuthenticationKeyScheme } from "../../types";
+import { SigningScheme as AuthenticationKeyScheme, HexInput } from "../../types";
 import { Deserializer } from "../../bcs/deserializer";
 import { Serializer } from "../../bcs/serializer";
 import { AuthenticationKey } from "../authenticationKey";
 import { AccountPublicKey, PublicKey, VerifySignatureArgs } from "./publicKey";
 import { Signature } from "./signature";
 import { AnyPublicKey, AnySignature } from "./singleKey";
+import { AptosConfig } from "../../api";
 
 /**
  * Counts the number of set bits (1s) in a byte.
@@ -165,19 +166,63 @@ export class MultiKey extends AbstractMultiKey {
 
   // region AccountPublicKey
 
+  /**
+   * Verifies the provided signature against the given message.
+   * This function helps ensure the integrity and authenticity of the message by checking if the signature is valid.
+   *
+   * Note: This function will fail if a keyless signature is used.  Use `verifySignatureAsync` instead.
+   *
+   * @param args - The arguments for verifying the signature.
+   * @param args.message - The message that was signed.
+   * @param args.signature - The signature to verify.
+   * @group Implementation
+   * @category Serialization
+   */
+  verifySignature(args: { message: HexInput; signature: MultiKeySignature }): boolean {
+    const { message, signature } = args;
+    if (signature.signatures.length !== this.signaturesRequired) {
+      throw new Error("The number of signatures does not match the number of required signatures");
+    }
+    const signerIndices = signature.bitMapToSignerIndices();
+    for (let i = 0; i < signature.signatures.length; i += 1) {
+      const singleSignature = signature.signatures[i];
+      const publicKey = this.publicKeys[signerIndices[i]];
+      if (!publicKey.verifySignature({ message, signature: singleSignature })) {
+        return false;
+      }
+    }
+    return true;
+  }
+
   /**
    * Verifies the provided signature against the given message.
    * This function helps ensure the integrity and authenticity of the message by checking if the signature is valid.
    *
    * @param args - The arguments for verifying the signature.
+   * @param args.aptosConfig - The Aptos configuration to use
    * @param args.message - The message that was signed.
    * @param args.signature - The signature to verify.
    * @group Implementation
    * @category Serialization
    */
-  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
-  verifySignature(args: VerifySignatureArgs): boolean {
-    throw new Error("not implemented");
+  async verifySignatureAsync(args: {
+    aptosConfig: AptosConfig;
+    message: HexInput;
+    signature: MultiKeySignature;
+  }): Promise<boolean> {
+    const { message, signature, aptosConfig } = args;
+    if (signature.signatures.length !== this.signaturesRequired) {
+      throw new Error("The number of signatures does not match the number of required signatures");
+    }
+    const signerIndices = signature.bitMapToSignerIndices();
+    for (let i = 0; i < signature.signatures.length; i += 1) {
+      const singleSignature = signature.signatures[i];
+      const publicKey = this.publicKeys[signerIndices[i]];
+      if (!(await publicKey.verifySignatureAsync({ aptosConfig, message, signature: singleSignature }))) {
+        return false;
+      }
+    }
+    return true;
   }
 
   /**
@@ -380,6 +425,31 @@ export class MultiKeySignature extends Signature {
     return bitmap;
   }
 
+  /**
+   * Converts the bitmap to an array of signer indices.
+   *
+   * Example:
+   *
+   * bitmap: [0b10001000, 0b01000000, 0b00000000, 0b00000000]
+   * signerIndices: [0, 4, 9]
+   *
+   * @returns An array of signer indices.
+   * @group Implementation
+   * @category Serialization
+   */
+  bitMapToSignerIndices(): number[] {
+    const signerIndices: number[] = [];
+    for (let i = 0; i < this.bitmap.length; i += 1) {
+      const byte = this.bitmap[i];
+      for (let bit = 0; bit < 8; bit += 1) {
+        if ((byte & (128 >> bit)) !== 0) {
+          signerIndices.push(i * 8 + bit);
+        }
+      }
+    }
+    return signerIndices;
+  }
+
   // region Serializable
 
   serialize(serializer: Serializer): void {

package/src/core/crypto/publicKey.ts

@@ -1,3 +1,4 @@
+import { AptosConfig } from "../../api";
 import { Serializable } from "../../bcs";
 import { HexInput } from "../../types";
 import { AuthenticationKey } from "../authenticationKey";
@@ -17,6 +18,23 @@ export interface VerifySignatureArgs {
   signature: Signature;
 }
 
+/**
+ * Represents the arguments required to verify a digital signature asynchronously.
+ *
+ * The validity of certain types of signatures are dependent on network state.  This is the case for
+ * Keyless signatures which need to lookup the verification key and keyless configuration.
+ *
+ * @param aptosConfig - The Aptos configuration to use
+ * @param message - The original message that was signed.
+ * @param signature - The signature to be verified against the message.
+ * @group Implementation
+ * @category Serialization
+ */
+export type VerifySignatureAsyncArgs = VerifySignatureArgs & {
+  aptosConfig: AptosConfig;
+  options?: any;
+};
+
 /**
  * Represents an abstract public key.
  *
@@ -35,6 +53,16 @@ export abstract class PublicKey extends Serializable {
    */
   abstract verifySignature(args: VerifySignatureArgs): boolean;
 
+  /**
+   * Verifies signature with the public key and makes any network calls required to get state required to verify the signature.
+   * @param args.aptosConfig The Aptos configuration
+   * @param args.message The message that was signed
+   * @param args.signature The signature to verify
+   * @group Implementation
+   * @category Serialization
+   */
+  abstract verifySignatureAsync(args: VerifySignatureAsyncArgs): Promise<boolean>;
+
   /**
    * Get the raw public key bytes
    * @group Implementation

package/src/core/crypto/secp256k1.ts

@@ -9,9 +9,10 @@ import { Hex } from "../hex";
 import { HexInput, PrivateKeyVariants } from "../../types";
 import { isValidBIP44Path, mnemonicToSeed } from "./hdKey";
 import { PrivateKey } from "./privateKey";
-import { PublicKey, VerifySignatureArgs } from "./publicKey";
+import { PublicKey } from "./publicKey";
 import { Signature } from "./signature";
 import { convertSigningMessage } from "./utils";
+import { AptosConfig } from "../../api";
 
 /**
  * Represents a Secp256k1 ECDSA public key.
@@ -69,7 +70,7 @@ export class Secp256k1PublicKey extends PublicKey {
    * @group Implementation
    * @category Serialization
    */
-  verifySignature(args: VerifySignatureArgs): boolean {
+  verifySignature(args: { message: HexInput; signature: Secp256k1Signature }): boolean {
     const { message, signature } = args;
     const messageToVerify = convertSigningMessage(message);
     const messageBytes = Hex.fromHexInput(messageToVerify).toUint8Array();
@@ -78,6 +79,28 @@ export class Secp256k1PublicKey extends PublicKey {
     return secp256k1.verify(signatureBytes, messageSha3Bytes, this.key.toUint8Array(), { lowS: true });
   }
 
+  /**
+   * Note: Secp256k1Signatures can be verified syncronously.
+   *
+   * Verifies the provided signature against the given message.
+   * This function helps ensure the integrity and authenticity of the message by confirming that the signature is valid.
+   *
+   * @param args - The arguments for signature verification.
+   * @param args.aptosConfig - The configuration object for connecting to the Aptos network
+   * @param args.message - The message that was signed.
+   * @param args.signature - The signature to verify, which must be an instance of Secp256k1Signature.
+   * @returns A boolean indicating whether the signature is valid for the given message.
+   * @group Implementation
+   * @category Serialization
+   */
+  async verifySignatureAsync(args: {
+    aptosConfig: AptosConfig;
+    message: HexInput;
+    signature: Secp256k1Signature;
+  }): Promise<boolean> {
+    return this.verifySignature(args);
+  }
+
   /**
    * Get the data as a Uint8Array representation.
    *

package/src/core/crypto/singleKey.ts

@@ -1,12 +1,18 @@
 import { Deserializer, Serializer } from "../../bcs";
-import { AnyPublicKeyVariant, AnySignatureVariant, SigningScheme as AuthenticationKeyScheme } from "../../types";
+import {
+  AnyPublicKeyVariant,
+  AnySignatureVariant,
+  SigningScheme as AuthenticationKeyScheme,
+  HexInput,
+} from "../../types";
 import { AuthenticationKey } from "../authenticationKey";
 import { Ed25519PrivateKey, Ed25519PublicKey, Ed25519Signature } from "./ed25519";
-import { AccountPublicKey, PublicKey, VerifySignatureArgs } from "./publicKey";
+import { AccountPublicKey, PublicKey, VerifySignatureArgs, VerifySignatureAsyncArgs } from "./publicKey";
 import { Secp256k1PrivateKey, Secp256k1PublicKey, Secp256k1Signature } from "./secp256k1";
 import { KeylessPublicKey, KeylessSignature } from "./keyless";
 import { Signature } from "./signature";
 import { FederatedKeylessPublicKey } from "./federatedKeyless";
+import { AptosConfig } from "../../api";
 
 export type PrivateKeyInput = Ed25519PrivateKey | Secp256k1PrivateKey;
 
@@ -77,18 +83,37 @@ export class AnyPublicKey extends AccountPublicKey {
    * @group Implementation
    * @category Serialization
    */
-  verifySignature(args: VerifySignatureArgs): boolean {
+  verifySignature(args: { message: HexInput; signature: AnySignature }): boolean {
     const { message, signature } = args;
-    if (!AnySignature.isInstance(signature)) {
-      return false;
-    }
-
     return this.publicKey.verifySignature({
       message,
       signature: signature.signature,
     });
   }
 
+  /**
+   * Verifies the provided signature against the given message.
+   * This function helps ensure the integrity and authenticity of the message by confirming that the signature is valid.
+   *
+   * @param args - The arguments for signature verification.
+   * @param args.aptosConfig - The configuration object for connecting to the Aptos network
+   * @param args.message - The message that was signed.
+   * @param args.signature - The signature to verify, which must be an instance of AnySignature.
+   * @returns A boolean indicating whether the signature is valid for the given message.
+   * @group Implementation
+   * @category Serialization
+   */
+  async verifySignatureAsync(args: {
+    aptosConfig: AptosConfig;
+    message: HexInput;
+    signature: AnySignature;
+  }): Promise<boolean> {
+    return await this.publicKey.verifySignatureAsync({
+      ...args,
+      signature: args.signature.signature,
+    });
+  }
+
   /**
    * Generates an authentication key from the current instance's byte representation.
    * This function is essential for creating a unique identifier for authentication purposes.

package/src/errors/index.ts

@@ -7,6 +7,7 @@ export enum KeylessErrorCategory {
   EXTERNAL_API_ERROR,
   SESSION_EXPIRED,
   INVALID_STATE,
+  INVALID_SIGNATURE,
   UNKNOWN,
 }
 
@@ -79,6 +80,20 @@ export enum KeylessErrorType {
 
   FULL_NODE_OTHER,
 
+  SIGNATURE_TYPE_INVALID,
+
+  SIGNATURE_EXPIRED,
+
+  MAX_EXPIRY_HORIZON_EXCEEDED,
+
+  EPHEMERAL_SIGNATURE_VERIFICATION_FAILED,
+
+  TRAINING_WHEELS_SIGNATURE_MISSING,
+
+  TRAINING_WHEELS_SIGNATURE_VERIFICATION_FAILED,
+
+  PROOF_VERIFICATION_FAILED,
+
   UNKNOWN,
 }
 
@@ -213,6 +228,41 @@ const KeylessErrors: { [key in KeylessErrorType]: [string, KeylessErrorCategory,
     KeylessErrorCategory.API_ERROR,
     KeylessErrorResolutionTip.SERVER_ERROR,
   ],
+  [KeylessErrorType.SIGNATURE_TYPE_INVALID]: [
+    "The signature is not a valid Keyless signature.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.JOIN_SUPPORT_GROUP,
+  ],
+  [KeylessErrorType.SIGNATURE_EXPIRED]: [
+    "The ephemeral key pair used to sign the message has expired.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.MAX_EXPIRY_HORIZON_EXCEEDED]: [
+    "The expiry horizon on the signature exceeds the maximum allowed value.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.EPHEMERAL_SIGNATURE_VERIFICATION_FAILED]: [
+    "Failed to verify the ephemeral signature with the ephemeral public key.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.TRAINING_WHEELS_SIGNATURE_MISSING]: [
+    "The training wheels signature is missing but is required by the Keyless configuration.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.TRAINING_WHEELS_SIGNATURE_VERIFICATION_FAILED]: [
+    "Failed to verify the training wheels signature with the training wheels public key.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
+  [KeylessErrorType.PROOF_VERIFICATION_FAILED]: [
+    "The proof verification failed.",
+    KeylessErrorCategory.INVALID_SIGNATURE,
+    KeylessErrorResolutionTip.REAUTHENTICATE,
+  ],
   [KeylessErrorType.UNKNOWN]: [
     "An unknown error has occurred.",
     KeylessErrorCategory.UNKNOWN,