@aptos-labs/ts-sdk 1.31.0 → 1.32.1

package/dist/esm/types/types.mjs

@@ -0,0 +1,2 @@
+import{A,B,C,D,E,F,G,a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z}from"../chunk-WQF3IOXC.mjs";import"../chunk-KDMSOCZY.mjs";export{g as AccountAuthenticatorVariant,i as AnyPublicKeyVariant,j as AnySignatureVariant,G as DeriveScheme,m as EphemeralCertificateVariant,k as EphemeralPublicKeyVariant,l as EphemeralSignatureVariant,a as MimeType,C as MoveAbility,B as MoveFunctionVisibility,h as PrivateKeyVariants,D as RoleType,c as ScriptTransactionArgumentVariants,E as SigningScheme,F as SigningSchemeInput,f as TransactionAuthenticatorVariant,d as TransactionPayloadVariants,o as TransactionResponseType,e as TransactionVariants,b as TypeTagVariants,n as ZkpVariant,v as isBlockEpilogueTransactionResponse,s as isBlockMetadataTransactionResponse,w as isEd25519Signature,z as isFeePayerSignature,r as isGenesisTransactionResponse,y as isMultiAgentSignature,A as isMultiEd25519Signature,p as isPendingTransactionResponse,x as isSecp256k1Signature,t as isStateCheckpointTransactionResponse,q as isUserTransactionResponse,u as isValidatorTransactionResponse};
+//# sourceMappingURL=types.mjs.map

package/dist/esm/types/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/esm/utils/const.d.mts

@@ -54,5 +54,11 @@ declare enum ProcessorType {
     USER_TRANSACTION_PROCESSOR = "user_transaction_processor",
     OBJECT_PROCESSOR = "objects_processor"
 }
+/**
+ * Regular expression pattern for Firebase Auth issuer URLs
+ * Matches URLs in the format: https://securetoken.google.com/[project-id]
+ * where project-id can contain letters, numbers, hyphens, and underscores
+ */
+declare const FIREBASE_AUTH_ISS_PATTERN: RegExp;
 
-export { APTOS_COIN, APTOS_FA, AptosApiType, DEFAULT_MAX_GAS_AMOUNT, DEFAULT_TXN_EXP_SEC_FROM_NOW, DEFAULT_TXN_TIMEOUT_SEC, ProcessorType, RAW_TRANSACTION_SALT, RAW_TRANSACTION_WITH_DATA_SALT };
+export { APTOS_COIN, APTOS_FA, AptosApiType, DEFAULT_MAX_GAS_AMOUNT, DEFAULT_TXN_EXP_SEC_FROM_NOW, DEFAULT_TXN_TIMEOUT_SEC, FIREBASE_AUTH_ISS_PATTERN, ProcessorType, RAW_TRANSACTION_SALT, RAW_TRANSACTION_WITH_DATA_SALT };

package/dist/esm/utils/const.mjs

@@ -1,2 +1,2 @@
-import{a,b,c,d,e,f,g,h,i}from"../chunk-J245N3XF.mjs";import"../chunk-KDMSOCZY.mjs";export{e as APTOS_COIN,f as APTOS_FA,a as AptosApiType,b as DEFAULT_MAX_GAS_AMOUNT,c as DEFAULT_TXN_EXP_SEC_FROM_NOW,d as DEFAULT_TXN_TIMEOUT_SEC,i as ProcessorType,g as RAW_TRANSACTION_SALT,h as RAW_TRANSACTION_WITH_DATA_SALT};
+import{a,b,c,d,e,f,g,h,i,j}from"../chunk-J7PJSK3J.mjs";import"../chunk-KDMSOCZY.mjs";export{e as APTOS_COIN,f as APTOS_FA,a as AptosApiType,b as DEFAULT_MAX_GAS_AMOUNT,c as DEFAULT_TXN_EXP_SEC_FROM_NOW,d as DEFAULT_TXN_TIMEOUT_SEC,j as FIREBASE_AUTH_ISS_PATTERN,i as ProcessorType,g as RAW_TRANSACTION_SALT,h as RAW_TRANSACTION_WITH_DATA_SALT};
 //# sourceMappingURL=const.mjs.map

package/dist/esm/utils/helpers.d.mts

@@ -1,8 +1,8 @@
-import { MoveStructId } from '../types/index.mjs';
-import './apiEndpoints.mjs';
+import { MoveStructId } from '../types/types.mjs';
 import '../types/indexer.mjs';
 import '../types/generated/operations.mjs';
 import '../types/generated/types.mjs';
+import './apiEndpoints.mjs';
 
 /**
  * Sleep for the specified amount of time in milliseconds.
@@ -11,6 +11,13 @@ import '../types/generated/types.mjs';
  * @param timeMs - The time in milliseconds to sleep.
  */
 declare function sleep(timeMs: number): Promise<null>;
+/**
+ * Get the error message from an unknown error.
+ *
+ * @param error The error to get the message from
+ * @returns The error message
+ */
+declare function getErrorMessage(error: unknown): string;
 declare const nowInSeconds: () => number;
 /**
  * Floors the given timestamp to the nearest whole hour.
@@ -86,4 +93,4 @@ declare const isEncodedStruct: (structObj: any) => structObj is {
     struct_name: string;
 };
 
-export { base64UrlDecode, convertAmountFromHumanReadableToOnChain, convertAmountFromOnChainToHumanReadable, floorToWholeHour, isEncodedStruct, nowInSeconds, parseEncodedStruct, sleep };
+export { base64UrlDecode, convertAmountFromHumanReadableToOnChain, convertAmountFromOnChainToHumanReadable, floorToWholeHour, getErrorMessage, isEncodedStruct, nowInSeconds, parseEncodedStruct, sleep };

package/dist/esm/utils/helpers.mjs

@@ -1,2 +1,2 @@
-import{a,b,c,d,e,f,g,h}from"../chunk-LEKBJ2EG.mjs";import"../chunk-KDMSOCZY.mjs";export{d as base64UrlDecode,e as convertAmountFromHumanReadableToOnChain,f as convertAmountFromOnChainToHumanReadable,c as floorToWholeHour,h as isEncodedStruct,b as nowInSeconds,g as parseEncodedStruct,a as sleep};
+import{a,b,c,d,e,f,g,h,i}from"../chunk-V4FKFCBL.mjs";import"../chunk-KDMSOCZY.mjs";export{e as base64UrlDecode,f as convertAmountFromHumanReadableToOnChain,g as convertAmountFromOnChainToHumanReadable,d as floorToWholeHour,b as getErrorMessage,i as isEncodedStruct,c as nowInSeconds,h as parseEncodedStruct,a as sleep};
 //# sourceMappingURL=helpers.mjs.map

package/dist/esm/utils/index.d.mts

@@ -1,9 +1,9 @@
 export { Network, NetworkToChainId, NetworkToFaucetAPI, NetworkToIndexerAPI, NetworkToNetworkName, NetworkToNodeAPI, NetworkToPepperAPI, NetworkToProverAPI } from './apiEndpoints.mjs';
-export { APTOS_COIN, APTOS_FA, AptosApiType, DEFAULT_MAX_GAS_AMOUNT, DEFAULT_TXN_EXP_SEC_FROM_NOW, DEFAULT_TXN_TIMEOUT_SEC, ProcessorType, RAW_TRANSACTION_SALT, RAW_TRANSACTION_WITH_DATA_SALT } from './const.mjs';
+export { APTOS_COIN, APTOS_FA, AptosApiType, DEFAULT_MAX_GAS_AMOUNT, DEFAULT_TXN_EXP_SEC_FROM_NOW, DEFAULT_TXN_TIMEOUT_SEC, FIREBASE_AUTH_ISS_PATTERN, ProcessorType, RAW_TRANSACTION_SALT, RAW_TRANSACTION_WITH_DATA_SALT } from './const.mjs';
 export { DeserializableClass, normalizeBundle } from './normalizeBundle.mjs';
-export { base64UrlDecode, convertAmountFromHumanReadableToOnChain, convertAmountFromOnChainToHumanReadable, floorToWholeHour, isEncodedStruct, nowInSeconds, parseEncodedStruct, sleep } from './helpers.mjs';
+export { base64UrlDecode, convertAmountFromHumanReadableToOnChain, convertAmountFromOnChainToHumanReadable, floorToWholeHour, getErrorMessage, isEncodedStruct, nowInSeconds, parseEncodedStruct, sleep } from './helpers.mjs';
 import '../bcs/deserializer.mjs';
-import '../types/index.mjs';
+import '../types/types.mjs';
 import '../types/indexer.mjs';
 import '../types/generated/operations.mjs';
 import '../types/generated/types.mjs';

package/dist/esm/utils/index.mjs

@@ -1,2 +1,2 @@
-import"../chunk-HGLO5LDS.mjs";import{a as r}from"../chunk-4CDDWSKZ.mjs";import{a as j,b as k,c as l,d as m,e as n,f as o,g as p,h as q}from"../chunk-D3OEQLUE.mjs";import{a,b,c,d,e,f,g,h,i}from"../chunk-J245N3XF.mjs";import"../chunk-FZY4PMEE.mjs";import"../chunk-IECDO22V.mjs";import"../chunk-6FLHGOKP.mjs";import"../chunk-OZN3OOJV.mjs";import"../chunk-JGNMNCQB.mjs";import"../chunk-7XS45O6M.mjs";import"../chunk-4WPQQPUF.mjs";import"../chunk-N47FTRYO.mjs";import"../chunk-QQIVWB6G.mjs";import"../chunk-KFNDDPOW.mjs";import"../chunk-6Q2O5G3J.mjs";import"../chunk-56CNRT2K.mjs";import{a as s,b as t,c as u,d as v,e as w,f as x,g as y,h as z}from"../chunk-LEKBJ2EG.mjs";import"../chunk-KDMSOCZY.mjs";export{e as APTOS_COIN,f as APTOS_FA,a as AptosApiType,b as DEFAULT_MAX_GAS_AMOUNT,c as DEFAULT_TXN_EXP_SEC_FROM_NOW,d as DEFAULT_TXN_TIMEOUT_SEC,o as Network,p as NetworkToChainId,l as NetworkToFaucetAPI,j as NetworkToIndexerAPI,q as NetworkToNetworkName,k as NetworkToNodeAPI,m as NetworkToPepperAPI,n as NetworkToProverAPI,i as ProcessorType,g as RAW_TRANSACTION_SALT,h as RAW_TRANSACTION_WITH_DATA_SALT,v as base64UrlDecode,w as convertAmountFromHumanReadableToOnChain,x as convertAmountFromOnChainToHumanReadable,u as floorToWholeHour,z as isEncodedStruct,r as normalizeBundle,t as nowInSeconds,y as parseEncodedStruct,s as sleep};
+import"../chunk-HGLO5LDS.mjs";import{a as s}from"../chunk-UZTJWOLS.mjs";import{a as t,b as u,c as v,d as w,e as x,f as y,g as z,h as A,i as B}from"../chunk-V4FKFCBL.mjs";import{a,b,c,d,e,f,g,h}from"../chunk-D3OEQLUE.mjs";import{a as i,b as j,c as k,d as l,e as m,f as n,g as o,h as p,i as q,j as r}from"../chunk-J7PJSK3J.mjs";import"../chunk-FZY4PMEE.mjs";import"../chunk-ZMBXHMVQ.mjs";import"../chunk-BRV3RLKW.mjs";import"../chunk-Q3CWUEXI.mjs";import"../chunk-42H7WETG.mjs";import"../chunk-FD6FGKYY.mjs";import"../chunk-WQF3IOXC.mjs";import"../chunk-4WPQQPUF.mjs";import"../chunk-D52UKPQF.mjs";import"../chunk-AJ5JHBAE.mjs";import"../chunk-SPRNSFUV.mjs";import"../chunk-6Q2O5G3J.mjs";import"../chunk-56CNRT2K.mjs";import"../chunk-KDMSOCZY.mjs";export{m as APTOS_COIN,n as APTOS_FA,i as AptosApiType,j as DEFAULT_MAX_GAS_AMOUNT,k as DEFAULT_TXN_EXP_SEC_FROM_NOW,l as DEFAULT_TXN_TIMEOUT_SEC,r as FIREBASE_AUTH_ISS_PATTERN,f as Network,g as NetworkToChainId,c as NetworkToFaucetAPI,a as NetworkToIndexerAPI,h as NetworkToNetworkName,b as NetworkToNodeAPI,d as NetworkToPepperAPI,e as NetworkToProverAPI,q as ProcessorType,o as RAW_TRANSACTION_SALT,p as RAW_TRANSACTION_WITH_DATA_SALT,x as base64UrlDecode,y as convertAmountFromHumanReadableToOnChain,z as convertAmountFromOnChainToHumanReadable,w as floorToWholeHour,u as getErrorMessage,B as isEncodedStruct,s as normalizeBundle,v as nowInSeconds,A as parseEncodedStruct,t as sleep};
 //# sourceMappingURL=index.mjs.map

package/dist/esm/utils/normalizeBundle.d.mts

@@ -1,10 +1,10 @@
 import { Deserializer } from '../bcs/deserializer.mjs';
 import { Serializable } from '../bcs/serializer.mjs';
-import '../types/index.mjs';
-import './apiEndpoints.mjs';
+import '../types/types.mjs';
 import '../types/indexer.mjs';
 import '../types/generated/operations.mjs';
 import '../types/generated/types.mjs';
+import './apiEndpoints.mjs';
 import '../core/hex.mjs';
 import '../core/common.mjs';
 

package/dist/esm/utils/normalizeBundle.mjs

@@ -1,2 +1,2 @@
-import{a}from"../chunk-4CDDWSKZ.mjs";import"../chunk-FZY4PMEE.mjs";import"../chunk-IECDO22V.mjs";import"../chunk-6FLHGOKP.mjs";import"../chunk-OZN3OOJV.mjs";import"../chunk-JGNMNCQB.mjs";import"../chunk-7XS45O6M.mjs";import"../chunk-4WPQQPUF.mjs";import"../chunk-N47FTRYO.mjs";import"../chunk-QQIVWB6G.mjs";import"../chunk-KFNDDPOW.mjs";import"../chunk-6Q2O5G3J.mjs";import"../chunk-56CNRT2K.mjs";import"../chunk-KDMSOCZY.mjs";export{a as normalizeBundle};
+import{a}from"../chunk-UZTJWOLS.mjs";import"../chunk-FZY4PMEE.mjs";import"../chunk-ZMBXHMVQ.mjs";import"../chunk-BRV3RLKW.mjs";import"../chunk-Q3CWUEXI.mjs";import"../chunk-42H7WETG.mjs";import"../chunk-FD6FGKYY.mjs";import"../chunk-WQF3IOXC.mjs";import"../chunk-4WPQQPUF.mjs";import"../chunk-D52UKPQF.mjs";import"../chunk-AJ5JHBAE.mjs";import"../chunk-SPRNSFUV.mjs";import"../chunk-6Q2O5G3J.mjs";import"../chunk-56CNRT2K.mjs";import"../chunk-KDMSOCZY.mjs";export{a as normalizeBundle};
 //# sourceMappingURL=normalizeBundle.mjs.map

package/dist/esm/version.d.mts

@@ -3,6 +3,6 @@
  *
  * hardcoded for now, we would want to have it injected dynamically
  */
-declare const VERSION = "1.31.0";
+declare const VERSION = "1.32.1";
 
 export { VERSION };

package/dist/esm/version.mjs

@@ -1,2 +1,2 @@
-import{a}from"./chunk-2CGJLPHP.mjs";import"./chunk-KDMSOCZY.mjs";export{a as VERSION};
+import{a}from"./chunk-RZGTHCJY.mjs";import"./chunk-KDMSOCZY.mjs";export{a as VERSION};
 //# sourceMappingURL=version.mjs.map

package/package.json

@@ -96,5 +96,5 @@
     "typedoc-plugin-missing-exports": "^3.0.0",
     "typescript": "^5.6.2"
   },
-  "version": "1.31.0"
+  "version": "1.32.1"
 }

package/src/account/AbstractKeylessAccount.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import EventEmitter from "eventemitter3";
+import { jwtDecode } from "jwt-decode";
 import { EphemeralCertificateVariant, HexInput, SigningScheme } from "../types";
 import { AccountAddress } from "../core/accountAddress";
 import {
@@ -12,23 +13,39 @@ import {
   EphemeralCertificate,
   ZeroKnowledgeSig,
   ZkProof,
+  getKeylessJWKs,
+  MoveJWK,
+  getKeylessConfig,
 } from "../core/crypto";
 
-import { Account } from "./Account";
 import { EphemeralKeyPair } from "./EphemeralKeyPair";
 import { Hex } from "../core/hex";
 import { AccountAuthenticatorSingleKey } from "../transactions/authenticator/account";
-import { Serializable, Serializer } from "../bcs";
+import { Deserializer, Serializable, Serializer } from "../bcs";
 import { deriveTransactionType, generateSigningMessage } from "../transactions/transactionBuilder/signingMessage";
 import { AnyRawTransaction, AnyRawTransactionInstance } from "../transactions/types";
 import { base64UrlDecode } from "../utils/helpers";
 import { FederatedKeylessPublicKey } from "../core/crypto/federatedKeyless";
+import { Account } from "./Account";
+import { AptosConfig } from "../api/aptosConfig";
+import { KeylessError, KeylessErrorType } from "../errors";
+
+/**
+ * An interface which defines if an Account utilizes Keyless signing.
+ */
+export interface KeylessSigner extends Account {
+  checkKeylessAccountValidity(aptosConfig: AptosConfig): Promise<void>;
+}
+
+export function isKeylessSigner(obj: any): obj is KeylessSigner {
+  return obj !== null && obj !== undefined && typeof obj.checkKeylessAccountValidity === "function";
+}
 
 /**
  * Account implementation for the Keyless authentication scheme.  This abstract class is used for standard Keyless Accounts
  * and Federated Keyless Accounts.
  */
-export abstract class AbstractKeylessAccount extends Serializable implements Account {
+export abstract class AbstractKeylessAccount extends Serializable implements KeylessSigner {
   static readonly PEPPER_LENGTH: number = 31;
 
   /**
@@ -88,12 +105,36 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
    */
   readonly jwt: string;
 
+  /**
+   * The hash of the verification key used to verify the proof. This is optional and can be used to check verifying key
+   * rotations which may invalidate the proof.
+   */
+  readonly verificationKeyHash?: Uint8Array;
+
   /**
    * An event emitter used to assist in handling asynchronous proof fetching.
    */
   private readonly emitter: EventEmitter<ProofFetchEvents>;
 
-  // Use the static constructor 'create' instead.
+  /**
+   * Use the static generator `create(...)` instead.
+   * Creates an instance of the KeylessAccount with an optional proof.
+   *
+   * @param args - The parameters for creating a KeylessAccount.
+   * @param args.address - Optional account address associated with the KeylessAccount.
+   * @param args.publicKey - A KeylessPublicKey or FederatedKeylessPublicKey.
+   * @param args.ephemeralKeyPair - The ephemeral key pair used in the account creation.
+   * @param args.iss - A JWT issuer.
+   * @param args.uidKey - The claim on the JWT to identify a user.  This is typically 'sub' or 'email'.
+   * @param args.uidVal - The unique id for this user, intended to be a stable user identifier.
+   * @param args.aud - The value of the 'aud' claim on the JWT, also known as client ID.  This is the identifier for the dApp's
+   * OIDC registration with the identity provider.
+   * @param args.pepper - A hexadecimal input used for additional security.
+   * @param args.proof - A Zero Knowledge Signature or a promise that resolves to one.
+   * @param args.proofFetchCallback - Optional callback function for fetching proof.
+   * @param args.jwt - A JSON Web Token used for authentication.
+   * @param args.verificationKeyHash Optional 32-byte verification key hash as hex input used to check proof validity.
+   */
   protected constructor(args: {
     address?: AccountAddress;
     publicKey: KeylessPublicKey | FederatedKeylessPublicKey;
@@ -106,9 +147,22 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
     proof: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
     proofFetchCallback?: ProofFetchCallback;
     jwt: string;
+    verificationKeyHash?: HexInput;
   }) {
     super();
-    const { address, ephemeralKeyPair, publicKey, uidKey, uidVal, aud, pepper, proof, proofFetchCallback, jwt } = args;
+    const {
+      address,
+      ephemeralKeyPair,
+      publicKey,
+      uidKey,
+      uidVal,
+      aud,
+      pepper,
+      proof,
+      proofFetchCallback,
+      jwt,
+      verificationKeyHash,
+    } = args;
     this.ephemeralKeyPair = ephemeralKeyPair;
     this.publicKey = publicKey;
     this.accountAddress = address ? AccountAddress.from(address) : this.publicKey.authKey().derivedAddress();
@@ -137,11 +191,17 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
       throw new Error(`Pepper length in bytes should be ${AbstractKeylessAccount.PEPPER_LENGTH}`);
     }
     this.pepper = pepperBytes;
+    if (verificationKeyHash !== undefined) {
+      if (Hex.hexInputToUint8Array(verificationKeyHash).length !== 32) {
+        throw new Error("verificationKeyHash must be 32 bytes");
+      }
+      this.verificationKeyHash = Hex.hexInputToUint8Array(verificationKeyHash);
+    }
   }
 
   /**
-   * This initializes the asynchronous proof fetch
-   * @return
+   * This initializes the asynchronous proof fetch.
+   * @return Emits whether the proof succeeds or fails, but has no return.
    */
   async init(promise: Promise<ZeroKnowledgeSig>) {
     try {
@@ -156,7 +216,14 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
     }
   }
 
+  /**
+   * Serializes the jwt data into a format suitable for transmission or storage.
+   * This function ensures that both the jwt data and the proof are properly serialized.
+   *
+   * @param serializer - The serializer instance used to convert the jwt data into bytes.
+   */
   serialize(serializer: Serializer): void {
+    this.accountAddress.serialize(serializer);
     serializer.serializeStr(this.jwt);
     serializer.serializeStr(this.uidKey);
     serializer.serializeFixedBytes(this.pepper);
@@ -165,6 +232,27 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
       throw new Error("Cannot serialize - proof undefined");
     }
     this.proof.serialize(serializer);
+    serializer.serializeOption(this.verificationKeyHash, 32);
+  }
+
+  static partialDeserialize(deserializer: Deserializer): {
+    address: AccountAddress;
+    jwt: string;
+    uidKey: string;
+    pepper: Uint8Array;
+    ephemeralKeyPair: EphemeralKeyPair;
+    proof: ZeroKnowledgeSig;
+    verificationKeyHash?: Uint8Array;
+  } {
+    const address = AccountAddress.deserialize(deserializer);
+    const jwt = deserializer.deserializeStr();
+    const uidKey = deserializer.deserializeStr();
+    const pepper = deserializer.deserializeFixedBytes(31);
+    const ephemeralKeyPair = EphemeralKeyPair.deserialize(deserializer);
+    const proof = ZeroKnowledgeSig.deserialize(deserializer);
+    const verificationKeyHash = deserializer.deserializeOption("fixedBytes", 32);
+
+    return { address, jwt, uidKey, pepper, ephemeralKeyPair, proof, verificationKeyHash };
   }
 
   /**
@@ -208,6 +296,45 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
     }
   }
 
+  /**
+   * Validates that the Keyless Account can be used to sign transactions.
+   * @return
+   */
+  async checkKeylessAccountValidity(aptosConfig: AptosConfig): Promise<void> {
+    if (this.isExpired()) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.EPHEMERAL_KEY_PAIR_EXPIRED,
+      });
+    }
+    await this.waitForProofFetch();
+    if (this.proof === undefined) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.ASYNC_PROOF_FETCH_FAILED,
+      });
+    }
+    const header = jwtDecode(this.jwt, { header: true });
+    if (header.kid === undefined) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.JWT_PARSING_ERROR,
+        details: "checkKeylessAccountValidity failed. JWT is missing 'kid' in header. This should never happen.",
+      });
+    }
+    if (this.verificationKeyHash !== undefined) {
+      const { verificationKey } = await getKeylessConfig({ aptosConfig });
+      if (Hex.hexInputToString(verificationKey.hash()) !== Hex.hexInputToString(this.verificationKeyHash)) {
+        throw KeylessError.fromErrorType({
+          type: KeylessErrorType.INVALID_PROOF_VERIFICATION_KEY_NOT_FOUND,
+        });
+      }
+    } else {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[Aptos SDK] The verification key hash was not set. Proof may be invalid if the verification key has rotated.",
+      );
+    }
+    await AbstractKeylessAccount.fetchJWK({ aptosConfig, publicKey: this.publicKey, kid: header.kid });
+  }
+
   /**
    * Sign the given message using Keyless.
    * @param message in HexInput format
@@ -216,10 +343,15 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
   sign(message: HexInput): KeylessSignature {
     const { expiryDateSecs } = this.ephemeralKeyPair;
     if (this.isExpired()) {
-      throw new Error("EphemeralKeyPair is expired");
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.EPHEMERAL_KEY_PAIR_EXPIRED,
+      });
     }
     if (this.proof === undefined) {
-      throw new Error("Proof not found - make sure to call `await account.waitForProofFetch()` before signing.");
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.PROOF_NOT_FOUND,
+        details: "Proof not found - make sure to call `await account.checkKeylessAccountValidity()` before signing.",
+      });
     }
     const ephemeralPublicKey = this.ephemeralKeyPair.getPublicKey();
     const ephemeralSignature = this.ephemeralKeyPair.sign(message);
@@ -241,7 +373,10 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
    */
   signTransaction(transaction: AnyRawTransaction): KeylessSignature {
     if (this.proof === undefined) {
-      throw new Error("Proof not found - make sure to call `await account.waitForProofFetch()` before signing.");
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.PROOF_NOT_FOUND,
+        details: "Proof not found - make sure to call `await account.checkKeylessAccountValidity()` before signing.",
+      });
     }
     const raw = deriveTransactionType(transaction);
     const txnAndProof = new TransactionAndProof(raw, this.proof.proof);
@@ -270,6 +405,58 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc
     }
     return true;
   }
+
+  /**
+   * Fetches the JWK from the issuer's well-known JWKS endpoint.
+   *
+   * @param args.publicKey The keyless public key to query
+   * @param args.kid The kid of the JWK to fetch
+   * @returns A JWK matching the `kid` in the JWT header.
+   * @throws {KeylessError} If the JWK cannot be fetched
+   */
+  static async fetchJWK(args: {
+    aptosConfig: AptosConfig;
+    publicKey: KeylessPublicKey | FederatedKeylessPublicKey;
+    kid: string;
+  }): Promise<MoveJWK> {
+    const { aptosConfig, publicKey, kid } = args;
+    const keylessPubKey = publicKey instanceof KeylessPublicKey ? publicKey : publicKey.keylessPublicKey;
+    const { iss } = keylessPubKey;
+
+    let allJWKs: Map<string, MoveJWK[]>;
+    const jwkAddr = publicKey instanceof FederatedKeylessPublicKey ? publicKey.jwkAddress : undefined;
+    try {
+      allJWKs = await getKeylessJWKs({ aptosConfig, jwkAddr });
+    } catch (error) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.FULL_NODE_JWKS_LOOKUP_ERROR,
+        error,
+        details: `Failed to fetch ${jwkAddr ? "Federated" : "Patched"}JWKs ${jwkAddr ? `for address ${jwkAddr}` : "0x1"}`,
+      });
+    }
+
+    // Find the corresponding JWK set by `iss`
+    const jwksForIssuer = allJWKs.get(iss);
+
+    if (jwksForIssuer === undefined) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.INVALID_JWT_ISS_NOT_RECOGNIZED,
+        details: `JWKs for issuer ${iss} not found.`,
+      });
+    }
+
+    // Find the corresponding JWK by `kid`
+    const jwk = jwksForIssuer.find((key) => key.kid === kid);
+
+    if (jwk === undefined) {
+      throw KeylessError.fromErrorType({
+        type: KeylessErrorType.INVALID_JWT_JWK_NOT_FOUND,
+        details: `JWK with kid '${kid}' for issuer '${iss}' not found.`,
+      });
+    }
+
+    return jwk;
+  }
 }
 
 /**
@@ -298,6 +485,12 @@ export class TransactionAndProof extends Serializable {
     this.proof = proof;
   }
 
+  /**
+   * Serializes the transaction data into a format suitable for transmission or storage.
+   * This function ensures that both the transaction bytes and the proof are properly serialized.
+   *
+   * @param serializer - The serializer instance used to convert the transaction data into bytes.
+   */
   serialize(serializer: Serializer): void {
     serializer.serializeFixedBytes(this.transaction.bcsToBytes());
     serializer.serializeOption(this.proof);

package/src/account/FederatedKeylessAccount.ts

@@ -1,23 +1,23 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-import { JwtPayload, jwtDecode } from "jwt-decode";
 import { HexInput } from "../types";
 import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
-import { ZeroKnowledgeSig } from "../core/crypto";
+import { getIssAudAndUidVal, Groth16VerificationKey, ZeroKnowledgeSig } from "../core/crypto";
 
 import { EphemeralKeyPair } from "./EphemeralKeyPair";
 import { Deserializer, Serializer } from "../bcs";
 import { FederatedKeylessPublicKey } from "../core/crypto/federatedKeyless";
 import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAccount";
+import { Hex } from "../core";
 
 /**
  * Account implementation for the FederatedKeyless authentication scheme.
  *
  * Used to represent a FederatedKeyless based account and sign transactions with it.
  *
- * Use `FederatedKeylessAccount.create()` to instantiate a KeylessAccount with a JWT, proof, EphemeralKeyPair and the
- * address the JWKs are installed that will be used to verify the JWT.
+ * Use `FederatedKeylessAccount.create()` to instantiate a KeylessAccount with a JSON Web Token (JWT), proof, EphemeralKeyPair and the
+ * address the JSON Web Key Set (JWKS) are installed that will be used to verify the JWT.
  *
  * When the proof expires or the JWT becomes invalid, the KeylessAccount must be instantiated again with a new JWT,
  * EphemeralKeyPair, and corresponding proof.
@@ -28,7 +28,20 @@ export class FederatedKeylessAccount extends AbstractKeylessAccount {
    */
   readonly publicKey: FederatedKeylessPublicKey;
 
-  // Use the static constructor 'create' instead.
+  /**
+   * Use the static generator `FederatedKeylessAccount.create(...)` instead.
+   * Creates a KeylessAccount instance using the provided parameters.
+   * This function allows you to set up a KeylessAccount with specific attributes such as address, proof, and JWT.
+   *
+   * @param args - The parameters for creating a KeylessAccount.
+   * @param args.address - Optional account address associated with the KeylessAccount.
+   * @param args.proof - A Zero Knowledge Signature or a promise that resolves to one.
+   * @param args.jwt - A JSON Web Token used for authentication.
+   * @param args.ephemeralKeyPair - The ephemeral key pair used in the account creation.
+   * @param args.jwkAddress - The address which stores the JSON Web Key Set (JWKS) used to verify the JWT.
+   * @param args.uidKey - Optional key for user identification, defaults to "sub".
+   * @param args.proofFetchCallback - Optional callback function for fetching proof.
+   */
   private constructor(args: {
     address?: AccountAddress;
     ephemeralKeyPair: EphemeralKeyPair;
@@ -41,45 +54,75 @@ export class FederatedKeylessAccount extends AbstractKeylessAccount {
     proof: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
     proofFetchCallback?: ProofFetchCallback;
     jwt: string;
+    verificationKeyHash?: HexInput;
   }) {
     const publicKey = FederatedKeylessPublicKey.create(args);
     super({ publicKey, ...args });
     this.publicKey = publicKey;
   }
 
+  /**
+   * Serializes the transaction data into a format suitable for transmission or storage.
+   * This function ensures that both the transaction bytes and the proof are properly serialized.
+   *
+   * @param serializer - The serializer instance used to convert the transaction data into bytes.
+   */
   serialize(serializer: Serializer): void {
-    if (this.proof === undefined) {
-      throw new Error("Cannot serialize - proof undefined");
-    }
-    serializer.serializeStr(this.jwt);
-    serializer.serializeStr(this.uidKey);
-    serializer.serializeFixedBytes(this.pepper);
+    super.serialize(serializer);
     this.publicKey.jwkAddress.serialize(serializer);
-    this.ephemeralKeyPair.serialize(serializer);
-    this.proof.serialize(serializer);
   }
 
+  /**
+   * Deserializes the provided deserializer to create a KeylessAccount instance.
+   * This function extracts necessary components such as the JWT, UID key, pepper, ephemeral key pair, and proof from the deserializer.
+   *
+   * @param deserializer - The deserializer instance used to retrieve the serialized data.
+   * @returns A KeylessAccount instance created from the deserialized data.
+   */
   static deserialize(deserializer: Deserializer): FederatedKeylessAccount {
-    const jwt = deserializer.deserializeStr();
-    const uidKey = deserializer.deserializeStr();
-    const pepper = deserializer.deserializeFixedBytes(31);
+    const { address, proof, ephemeralKeyPair, jwt, uidKey, pepper, verificationKeyHash } =
+      AbstractKeylessAccount.partialDeserialize(deserializer);
     const jwkAddress = AccountAddress.deserialize(deserializer);
-    const ephemeralKeyPair = EphemeralKeyPair.deserialize(deserializer);
-    const proof = ZeroKnowledgeSig.deserialize(deserializer);
-    return FederatedKeylessAccount.create({
+    const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
+    return new FederatedKeylessAccount({
+      address,
       proof,
-      pepper,
-      jwkAddress,
+      ephemeralKeyPair,
+      iss,
       uidKey,
+      uidVal,
+      aud,
+      pepper,
       jwt,
-      ephemeralKeyPair,
+      verificationKeyHash,
+      jwkAddress,
     });
   }
 
-  static fromBytes(bytes: Uint8Array): FederatedKeylessAccount {
-    return FederatedKeylessAccount.deserialize(new Deserializer(bytes));
+  /**
+   * Deserialize bytes using this account's information.
+   *
+   * @param bytes The bytes being interpreted.
+   * @returns
+   */
+  static fromBytes(bytes: HexInput): FederatedKeylessAccount {
+    return FederatedKeylessAccount.deserialize(new Deserializer(Hex.hexInputToUint8Array(bytes)));
   }
 
+  /**
+   * Creates a KeylessAccount instance using the provided parameters.
+   * This function allows you to set up a KeylessAccount with specific attributes such as address, proof, and JWT.
+   * This is used instead of the KeylessAccount constructor.
+   *
+   * @param args - The parameters for creating a KeylessAccount.
+   * @param args.address - Optional account address associated with the KeylessAccount.
+   * @param args.proof - A Zero Knowledge Signature or a promise that resolves to one.
+   * @param args.jwt - A JSON Web Token used for authentication.
+   * @param args.ephemeralKeyPair - The ephemeral key pair used in the account creation.
+   * @param args.jwkAddress - The address which stores the JSON Web Key Set (JWKS) used to verify the JWT.
+   * @param args.uidKey - Optional key for user identification, defaults to "sub".
+   * @param args.proofFetchCallback - Optional callback function for fetching proof.
+   */
   static create(args: {
     address?: AccountAddress;
     proof: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
@@ -89,29 +132,34 @@ export class FederatedKeylessAccount extends AbstractKeylessAccount {
     jwkAddress: AccountAddressInput;
     uidKey?: string;
     proofFetchCallback?: ProofFetchCallback;
+    verificationKey?: Groth16VerificationKey;
   }): FederatedKeylessAccount {
-    const { address, proof, jwt, ephemeralKeyPair, pepper, jwkAddress, uidKey = "sub", proofFetchCallback } = args;
+    const {
+      address,
+      proof,
+      jwt,
+      ephemeralKeyPair,
+      pepper,
+      jwkAddress,
+      uidKey = "sub",
+      proofFetchCallback,
+      verificationKey,
+    } = args;
 
-    const jwtPayload = jwtDecode<JwtPayload & { [key: string]: string }>(jwt);
-    if (typeof jwtPayload.iss !== "string") {
-      throw new Error("iss was not found");
-    }
-    if (typeof jwtPayload.aud !== "string") {
-      throw new Error("aud was not found or an array of values");
-    }
-    const uidVal = jwtPayload[uidKey];
+    const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
     return new FederatedKeylessAccount({
       address,
       proof,
       ephemeralKeyPair,
-      iss: jwtPayload.iss,
+      iss,
       uidKey,
       uidVal,
-      aud: jwtPayload.aud,
+      aud,
       pepper,
       jwkAddress: AccountAddress.from(jwkAddress),
       jwt,
       proofFetchCallback,
+      verificationKeyHash: verificationKey ? verificationKey.hash() : undefined,
     });
   }
 }