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

package/package.json

@@ -57,7 +57,6 @@
     "form-data": "^4.0.0",
     "jose": "^5.1.3",
     "js-base64": "^3.7.7",
-    "jwks-rsa": "^3.1.0",
     "jwt-decode": "^4.0.0",
     "poseidon-lite": "^0.2.0"
   },
@@ -93,5 +92,5 @@
     "typedoc": "^0.25.4",
     "typescript": "^5.3.3"
   },
-  "version": "1.16.0-zeta.0"
+  "version": "1.16.0-zeta.2"
 }

package/src/account/EphemeralKeyPair.ts

@@ -12,7 +12,7 @@ import {
 } from "../core/crypto";
 import { Hex } from "../core/hex";
 import { bytesToBigIntLE, padAndPackBytesWithLen, poseidonHash } from "../core/crypto/poseidon";
-import { AnyNumber, EphemeralPublicKeyVariant, HexInput } from "../types";
+import { EphemeralPublicKeyVariant, HexInput } from "../types";
 import { Deserializer, Serializable, Serializer } from "../bcs";
 import { currentTimeInSeconds, floorToWholeHour } from "../utils/helpers";
 
@@ -29,7 +29,7 @@ export class EphemeralKeyPair extends Serializable {
    * A timestamp in seconds indicating when the ephemeral key pair is expired.  After expiry, a new
    * EphemeralKeyPair must be generated and a new JWT needs to be created.
    */
-  readonly expiryDateSecs: bigint | number;
+  readonly expiryDateSecs: number;
 
   /**
    * The value passed to the IdP when the user authenticates.  It comprises of a hash of the
@@ -49,13 +49,13 @@ export class EphemeralKeyPair extends Serializable {
    */
   private publicKey: EphemeralPublicKey;
 
-  constructor(args: { privateKey: PrivateKey; expiryDateSecs?: AnyNumber; blinder?: HexInput }) {
+  constructor(args: { privateKey: PrivateKey; expiryDateSecs?: number; blinder?: HexInput }) {
     super();
     const { privateKey, expiryDateSecs, blinder } = args;
     this.privateKey = privateKey;
     this.publicKey = new EphemeralPublicKey(privateKey.publicKey());
     // We set the expiry date to be the nearest floored hour
-    this.expiryDateSecs = expiryDateSecs || BigInt(floorToWholeHour(currentTimeInSeconds() + EPK_HORIZON_SECS));
+    this.expiryDateSecs = expiryDateSecs || floorToWholeHour(currentTimeInSeconds() + EPK_HORIZON_SECS);
     // Generate the blinder if not provided
     this.blinder = blinder !== undefined ? Hex.fromHexInput(blinder).toUint8Array() : generateBlinder();
     // Calculate the nonce
@@ -98,7 +98,7 @@ export class EphemeralKeyPair extends Serializable {
     }
     const expiryDateSecs = deserializer.deserializeU64();
     const blinder = deserializer.deserializeFixedBytes(31);
-    return new EphemeralKeyPair({ privateKey, expiryDateSecs, blinder });
+    return new EphemeralKeyPair({ privateKey, expiryDateSecs: Number(expiryDateSecs), blinder });
   }
 
   static fromBytes(bytes: Uint8Array): EphemeralKeyPair {
@@ -111,7 +111,7 @@ export class EphemeralKeyPair extends Serializable {
    * @param expiryDateSecs the date of expiry.
    * @return boolean
    */
-  static generate(args?: { scheme: EphemeralPublicKeyVariant; expiryDateSecs?: bigint | number }): EphemeralKeyPair {
+  static generate(args?: { scheme: EphemeralPublicKeyVariant; expiryDateSecs?: number }): EphemeralKeyPair {
     let privateKey: PrivateKey;
 
     switch (args?.scheme) {

package/src/account/KeylessAccount.ts

@@ -2,7 +2,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { JwtPayload, jwtDecode } from "jwt-decode";
-import { JwksClient } from "jwks-rsa";
 import EventEmitter from "eventemitter3";
 import { EphemeralCertificateVariant, HexInput, SigningScheme } from "../types";
 import { AccountAddress } from "../core/accountAddress";
@@ -22,76 +21,95 @@ import { EphemeralKeyPair } from "./EphemeralKeyPair";
 import { Hex } from "../core/hex";
 import { AccountAuthenticatorSingleKey } from "../transactions/authenticator/account";
 import { Deserializer, Serializable, Serializer } from "../bcs";
-import {
-  deriveTransactionType,
-  generateSigningMessageForBcsCryptoHashable,
-} from "../transactions/transactionBuilder/signingMessage";
+import { deriveTransactionType } from "../transactions/transactionBuilder/signingMessage";
 import { AnyRawTransaction, AnyRawTransactionInstance } from "../transactions/types";
-import { AptosApiError } from "../client/types";
-import { AptsoDomainSeparator, CryptoHashable } from "../bcs/cryptoHasher";
+import { AptsoDomainSeparator, CryptoHashable } from "../core/crypto/cryptoHasher";
 import { base64UrlDecode } from "../utils/helpers";
 
 export const IssuerToJwkEndpoint: Record<string, string> = {
   "https://accounts.google.com": "https://www.googleapis.com/oauth2/v3/certs",
 };
 
-export enum KeylessErrorType {
-  JWK_EXPIRED,
-  EPK_EXPIRED,
-  PROOF_NOT_FOUND,
-  UNKNOWN_INVALID_SIGNATURE,
-  UNKNOWN,
-}
-export class KeylessError extends Error {
-  readonly type: KeylessErrorType;
-
-  constructor(type: KeylessErrorType) {
-    super();
-    this.type = type;
-  }
-
-  static async fromAptosApiError(error: AptosApiError, signer: KeylessAccount): Promise<KeylessError> {
-    if (!error.data.message.includes("INVALID_SIGNATURE")) {
-      return new KeylessError(KeylessErrorType.UNKNOWN);
-    }
-    if (signer.isExpired()) {
-      return new KeylessError(KeylessErrorType.EPK_EXPIRED);
-    }
-    if (!(await signer.checkJwkValidity())) {
-      return new KeylessError(KeylessErrorType.JWK_EXPIRED);
-    }
-    return new KeylessError(KeylessErrorType.UNKNOWN_INVALID_SIGNATURE);
-  }
-}
-
+/**
+ * Account implementation for the Keyless authentication scheme.
+ *
+ * Used to represent a Keyless based account and sign transactions with it.
+ *
+ * Use KeylessAccount.fromJWTAndProof to instantiate a KeylessAccount with a JWT, proof and EphemeralKeyPair.
+ *
+ * When the proof expires or the JWT becomes invalid, the KeylessAccount must be instantiated again with a new JWT,
+ * EphemeralKeyPair, and corresponding proof.
+ */
 export class KeylessAccount extends Serializable implements Account {
   static readonly PEPPER_LENGTH: number = 31;
 
+  /**
+   * The KeylessPublicKey associated with the account
+   */
   readonly publicKey: KeylessPublicKey;
 
+  /**
+   * The EphemeralKeyPair used to generate sign.
+   */
   readonly ephemeralKeyPair: EphemeralKeyPair;
 
+  /**
+   * The claim on the JWT to identify a user.  This is typically 'sub' or 'email'.
+   */
   readonly uidKey: string;
 
+  /**
+   * The value of the uidKey claim on the JWT.  This intended to be a stable user identifier.
+   */
   readonly uidVal: string;
 
+  /**
+   * 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.
+   */
   readonly aud: string;
 
+  /**
+   * A value contains 31 bytes of entropy that preserves privacy of the account. Typically fetched from a pepper provider.
+   */
   readonly pepper: Uint8Array;
 
+  /**
+   * Account address associated with the account
+   */
   readonly accountAddress: AccountAddress;
 
+  /**
+   * The zero knowledge signature (if ready) which contains the proof used to validate the EphemeralKeyPair.
+   */
   proof: ZeroKnowledgeSig | undefined;
 
+  /**
+   * The proof of the EphemeralKeyPair or a promise that provides the proof.  This is used to allow for awaiting on
+   * fetching the proof.
+   */
   readonly proofOrPromise: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
 
+  /**
+   * Signing scheme used to sign transactions
+   */
   readonly signingScheme: SigningScheme;
 
+  /**
+   * The JWT token used to derive the account
+   */
   private jwt: string;
 
+  /**
+   * A value that caches the JWT's validity.  A JWT becomes invalid when it's corresponding JWK is rotated from the
+   * identity provider's JWK keyset.
+   */
   private isJwtValid: boolean;
 
-  readonly emitter: EventEmitter<ProofFetchEvents>;
+  /**
+   * An event emitter used to assist in handling asycronous proof fetching.
+   */
+  private readonly emitter: EventEmitter<ProofFetchEvents>;
 
   constructor(args: {
     address?: AccountAddress;
@@ -189,28 +207,6 @@ export class KeylessAccount extends Serializable implements Account {
     return this.ephemeralKeyPair.isExpired();
   }
 
-  /**
-   * Checks if the the JWK used to verify the token still exists on the issuer's JWK uri.
-   * Caches the result.
-   * @return boolean
-   */
-  async checkJwkValidity(): Promise<boolean> {
-    if (!this.isJwtValid) {
-      return false;
-    }
-    const jwtHeader = jwtDecode(this.jwt, { header: true });
-    const client = new JwksClient({
-      jwksUri: IssuerToJwkEndpoint[this.publicKey.iss],
-    });
-    try {
-      await client.getSigningKey(jwtHeader.kid);
-      return true;
-    } catch (error) {
-      this.isJwtValid = false;
-      return false;
-    }
-  }
-
   /**
    * Sign a message using Keyless.
    * @param message the message to sign, as binary input
@@ -251,13 +247,10 @@ export class KeylessAccount extends Serializable implements Account {
   sign(data: HexInput): KeylessSignature {
     const { expiryDateSecs } = this.ephemeralKeyPair;
     if (this.isExpired()) {
-      throw new KeylessError(KeylessErrorType.EPK_EXPIRED);
+      throw new Error("EphemeralKeyPair is expired");
     }
     if (this.proof === undefined) {
-      throw new KeylessError(KeylessErrorType.PROOF_NOT_FOUND);
-    }
-    if (!this.isJwtValid) {
-      throw new KeylessError(KeylessErrorType.JWK_EXPIRED);
+      throw new Error("Proof not defined");
     }
     const ephemeralPublicKey = this.ephemeralKeyPair.getPublicKey();
     const ephemeralSignature = this.ephemeralKeyPair.sign(data);
@@ -283,7 +276,7 @@ export class KeylessAccount extends Serializable implements Account {
     }
     const raw = deriveTransactionType(transaction);
     const txnAndProof = new TransactionAndProof(raw, this.proof.proof);
-    const signMess = generateSigningMessageForBcsCryptoHashable(txnAndProof);
+    const signMess = txnAndProof.hash();
     return this.sign(signMess);
   }
 
@@ -328,18 +321,31 @@ export class KeylessAccount extends Serializable implements Account {
   }
 }
 
+/**
+ * A container class to hold a transaction and a proof.  It implements CryptoHashable which is used to create
+ * the signing message for Keyless transactions.  We sign over the proof to ensure non-malleability.
+ */
 export class TransactionAndProof extends CryptoHashable {
+  /**
+   * The transaction to sign.
+   */
   transaction: AnyRawTransactionInstance;
 
+  /**
+   * The zero knowledge proof used in signing the transaction.
+   */
   proof?: ZkProof;
 
+  /**
+   * The domain separator prefix used when hashing.
+   */
   domainSeparator: AptsoDomainSeparator;
 
   constructor(transaction: AnyRawTransactionInstance, proof?: ZkProof) {
     super();
     this.transaction = transaction;
     this.proof = proof;
-    this.domainSeparator = "APTOS::TransactionAndProof"
+    this.domainSeparator = "APTOS::TransactionAndProof";
   }
 
   serialize(serializer: Serializer): void {

package/src/api/keyless.ts

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { EphemeralKeyPair, KeylessAccount, ProofFetchCallback } from "../account";
-import { deriveKeylessAccount, getPepper } from "../internal/keyless";
-import { HexInput } from "../types";
+import { KeylessConfiguration } from "../core";
+import { deriveKeylessAccount, getKeylessConfig, getPepper } from "../internal/keyless";
+import { HexInput, LedgerVersionArg } from "../types";
 import { AptosConfig } from "./aptosConfig";
 
 /**
@@ -12,6 +13,16 @@ import { AptosConfig } from "./aptosConfig";
 export class Keyless {
   constructor(readonly config: AptosConfig) {}
 
+  /**
+   * Gets the parameters of how Keyless Accounts are configured on chain.
+   *
+   * @param args.options.ledgerVersion The ledger version to query, if not provided it will get the latest version
+   * @returns KeylessConfiguration
+   */
+  async getKeylessConfig(options?: LedgerVersionArg): Promise<KeylessConfiguration> {
+    return getKeylessConfig({ aptosConfig: this.config, options });
+  }
+
   /**
    * Fetches the pepper from the Aptos pepper service API.
    *
@@ -30,7 +41,6 @@ export class Keyless {
    * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
    * @param args.uidKey a key in the JWT token to use to set the uidVal in the IdCommitment
    * @param args.pepper the pepper
-   * @param args.extraFieldKey a key in the JWT token used to reveal a value on chain
    * @param args.proofFetchCallback a callback function that if set, the fetch of the proof will be done asyncronously. Once
    * if finishes the callback function will be called.
    * @returns A KeylessAccount that can be used to sign transactions
@@ -40,7 +50,6 @@ export class Keyless {
     ephemeralKeyPair: EphemeralKeyPair;
     uidKey?: string;
     pepper?: HexInput;
-    extraFieldKey?: string;
     proofFetchCallback?: ProofFetchCallback;
   }): Promise<KeylessAccount> {
     return deriveKeylessAccount({ aptosConfig: this.config, ...args });

package/src/bcs/deserializer.ts

@@ -77,16 +77,22 @@ export class Deserializer {
   }
 
   /**
-   * Deserializes a an optional string.
+   * Deserializes a an optional deserializable class.
+   *
+   * BCS layout for Optional<T>: 0 if none, else 1 | bcs representation of class
    *
-   * BCS layout for Optional<String>: 0 if none, else 1 | string_length | string_content
    * @example
-   * ```ts
-   * const deserializer = new Deserializer(new Uint8Array([0x00]));
-   * assert(deserializer.deserializeOptionStr() === undefined);
-   * const deserializer = new Deserializer(new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
-   * assert(deserializer.deserializeOptionStr() === "1234abcd");
-   * ```
+   * const deserializer = new Deserializer(new Uint8Array([1, 2, 3]));
+   * const value = deserializer.deserializeOption(MyClass); // where MyClass has a `deserialize` function
+   * // value is now an instance of MyClass
+   *
+   * const deserializer = new Deserializer(new Uint8Array([0]));
+   * const value = deserializer.deserializeOption(MyClass); // where MyClass has a `deserialize` function
+   * // value is undefined
+   *
+   * @param cls The BCS-deserializable class to deserialize the buffered bytes into.
+   *
+   * @returns the deserialized value of class type T
    */
   deserializeOption<T>(cls: Deserializable<T>): T | undefined {
     const exists = this.deserializeUleb128AsU32();

package/src/bcs/serializer.ts

@@ -317,6 +317,24 @@ export class Serializer {
     });
   }
 
+  /**
+   * Serializes a BCS Serializable values into a serializer instance or undefined.
+   * Note that this does not return anything. The bytes are added to the serializer instance's byte buffer.
+   *
+   * @param values The array of BCS Serializable values
+   *
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeOption(new AccountAddress(...));
+   * const serializedBytes = serializer.toUint8Array();
+   * // serializedBytes is now the BCS-serialized byte representation of AccountAddress
+   *
+   * const serializer = new Serializer();
+   * serializer.serializeOption(undefined);
+   * assert(serializer.toUint8Array() === new Uint8Array([0x00]));
+   * ```
+   */
   serializeOption<T extends Serializable>(value?: T): void {
     if (value === undefined) {
       this.serializeU32AsUleb128(0);
@@ -326,6 +344,28 @@ export class Serializer {
     }
   }
 
+  /**
+   * Serializes an optional string. UTF8 string is supported.
+   *
+   * The existence of the string is encoded first, 0 if undefined and 1 if it exists.
+   * Them the number of bytes in the string content is serialized, as a uleb128-encoded u32 integer.
+   * Then the string content is serialized as UTF8 encoded bytes.
+   *
+   * BCS layout for optional "string": 1 | string_length | string_content
+   * where string_length is a u32 integer encoded as a uleb128 integer, equal to the number of bytes in string_content.
+   *
+   * BCS layout for undefined: 0
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeOptionStr("1234abcd");
+   * assert(serializer.toUint8Array() === new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
+   *
+   * const serializer = new Serializer();
+   * serializer.serializeOptionStr(undefined);
+   * assert(serializer.toUint8Array() === new Uint8Array([0]));
+   * ```
+   */
   serializeOptionStr(value?: string): void {
     if (value === undefined) {
       this.serializeU32AsUleb128(0);

package/src/client/core.ts

@@ -100,20 +100,16 @@ export async function aptosRequest<Req extends {}, Res extends {}>(
       );
     }
     result.data = indexerResponse.data as Res;
+  } else if (apiType === AptosApiType.PEPPER || apiType === AptosApiType.PROVER) {
+    if (result.status >= 500) {
+      throw new AptosApiError(options, result, `${response.data}`);
+    }
   }
 
   if (result.status >= 200 && result.status < 300) {
     return result;
   }
 
-  if (result.status >= 500) {
-    throw new AptosApiError(options, result, `${response.data}`);
-  }
-
-  if (aptosConfig.isPepperServiceRequest(url) || aptosConfig.isProverServiceRequest(url)) {
-    throw new AptosApiError(options, result, `${response.data}`);
-  }
-
   let errorMessage: string;
 
   if (result && result.data && "message" in result.data && "error_code" in result.data) {

package/src/client/get.ts

@@ -89,6 +89,12 @@ export async function getAptosFullNode<Req extends {}, Res extends {}>(
   });
 }
 
+/**
+ * Makes a get request to the pepper service
+ *
+ * @param options GetAptosRequestOptions
+ * @returns AptosResponse
+ */
 export async function getAptosPepperService<Req extends {}, Res extends {}>(
   options: GetAptosRequestOptions,
 ): Promise<AptosResponse<Req, Res>> {

package/src/client/post.ts

@@ -136,6 +136,12 @@ export async function postAptosFaucet<Req extends {}, Res extends {}>(
   });
 }
 
+/**
+ * Makes a post request to the pepper service
+ *
+ * @param options GetAptosRequestOptions
+ * @returns AptosResponse
+ */
 export async function postAptosPepperService<Req extends {}, Res extends {}>(
   options: PostAptosRequestOptions,
 ): Promise<AptosResponse<Req, Res>> {

package/src/core/crypto/cryptoHasher.ts

@@ -0,0 +1,16 @@
+import { generateSigningMessage } from "../../transactions/transactionBuilder/signingMessage";
+import { Serializable } from "../../bcs/serializer";
+
+export type AptsoDomainSeparator = `APTOS::${string}`;
+export abstract class CryptoHashable extends Serializable {
+  abstract readonly domainSeparator: AptsoDomainSeparator;
+
+  /**
+   * Hashes the bcs serialized from of the class. This is the typescript corollary to the BCSCryptoHash macro in aptos-core.
+   *
+   * @returns Uint8Array
+   */
+  hash(): Uint8Array {
+    return generateSigningMessage(this.bcsToBytes(), this.domainSeparator);
+  }
+}