@moveindustries/ts-sdk 5.1.4

package/src/account/Ed25519Account.ts

@@ -0,0 +1,210 @@
+import type { MovementConfig } from "../api";
+import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
+import { Ed25519PrivateKey, Ed25519PublicKey, Ed25519Signature, Signature } from "../core/crypto";
+import { AccountAuthenticatorEd25519 } from "../transactions/authenticator/account";
+import { generateSigningMessageForTransaction } from "../transactions/transactionBuilder/signingMessage";
+import { AnyRawTransaction } from "../transactions/types";
+import { HexInput, SigningScheme } from "../types";
+import type { Account } from "./Account";
+
+/**
+ * Arguments required to create an instance of an Ed25519 signer.
+ *
+ * @param privateKey - The private key used for signing.
+ * @param address - Optional account address associated with the signer.
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+export interface Ed25519SignerConstructorArgs {
+  privateKey: Ed25519PrivateKey;
+  address?: AccountAddressInput;
+}
+
+/**
+ * Arguments for creating an Ed25519 signer from a derivation path.
+ *
+ * @param path - The derivation path for the Ed25519 key.
+ * @param mnemonic - The mnemonic phrase used to generate the key.
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+export interface Ed25519SignerFromDerivationPathArgs {
+  path: string;
+  mnemonic: string;
+}
+
+/**
+ * Arguments required to verify an Ed25519 signature against a given message.
+ *
+ * @param message - The message to be verified, represented in hexadecimal format.
+ * @param signature - The Ed25519 signature to validate.
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+export interface VerifyEd25519SignatureArgs {
+  message: HexInput;
+  signature: Ed25519Signature;
+}
+
+/**
+ * Represents an Ed25519 account that provides signing capabilities through an Ed25519 private key.
+ * This class allows for the creation of accounts, signing messages and transactions, and verifying signatures.
+ *
+ * Note: Generating an instance of this class does not create the account on-chain.
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+export class Ed25519Account implements Account {
+  /**
+   * Private key associated with the account
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly privateKey: Ed25519PrivateKey;
+
+  readonly publicKey: Ed25519PublicKey;
+
+  readonly accountAddress: AccountAddress;
+
+  readonly signingScheme = SigningScheme.Ed25519;
+
+  // region Constructors
+
+  /**
+   * Creates an instance of the Ed25519Signer with the specified parameters.
+   * This constructor initializes the private key, public key, and account address for the signer.
+   *
+   * @param args - The constructor arguments for the Ed25519Signer.
+   * @param args.privateKey - The private key used for signing.
+   * @param args.address - The optional account address; if not provided, it will derive the address from the public key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  constructor(args: Ed25519SignerConstructorArgs) {
+    const { privateKey, address } = args;
+    this.privateKey = privateKey;
+    this.publicKey = privateKey.publicKey();
+    this.accountAddress = address ? AccountAddress.from(address) : this.publicKey.authKey().derivedAddress();
+  }
+
+  /**
+   * Generates a new Ed25519 account using a randomly generated private key.
+   * This function is useful for creating a signer that can be used for cryptographic operations.
+   *
+   * @returns {Ed25519Account} The newly generated Ed25519 account.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  static generate(): Ed25519Account {
+    const privateKey = Ed25519PrivateKey.generate();
+    return new Ed25519Account({ privateKey });
+  }
+
+  /**
+   * Derives an Ed25519 account using a specified BIP44 path and mnemonic seed phrase.
+   *
+   * @param args - The arguments for deriving the account.
+   * @param args.path - The BIP44 derive hardened path, e.g., m/44'/637'/0'/0'/0'.
+   * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
+   * @param args.mnemonic - The mnemonic seed phrase of the account.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  static fromDerivationPath(args: Ed25519SignerFromDerivationPathArgs) {
+    const { path, mnemonic } = args;
+    const privateKey = Ed25519PrivateKey.fromDerivationPath(path, mnemonic);
+    return new Ed25519Account({ privateKey });
+  }
+  // endregion
+
+  // region Account
+  /**
+   * Verify the given message and signature with the public key.
+   *
+   * @param args - The arguments for verifying the signature.
+   * @param args.message - Raw message data in HexInput format.
+   * @param args.signature - Signed message signature.
+   * @returns A boolean indicating whether the signature is valid.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  verifySignature(args: VerifyEd25519SignatureArgs): boolean {
+    return this.publicKey.verifySignature(args);
+  }
+
+  /**
+   * Verify the given message and signature with the public key.
+   *
+   * Ed25519 signatures do not depend on chain state, so this function is equivalent to the synchronous verifySignature method.
+   *
+   * @param args - The arguments for verifying the signature.
+   * @param args.movementConfig - The configuration object for connecting to the Movement network
+   * @param args.message - Raw message data in HexInput format.
+   * @param args.signature - Signed message signature.
+   * @returns A boolean indicating whether the signature is valid.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  async verifySignatureAsync(args: {
+    movementConfig: MovementConfig;
+    message: HexInput;
+    signature: Signature;
+  }): Promise<boolean> {
+    return this.publicKey.verifySignatureAsync({
+      ...args,
+      signature: args.signature,
+    });
+  }
+
+  /**
+   * Sign a message using the account's Ed25519 private key.
+   * This function returns an AccountAuthenticator containing the signature along with the account's public key.
+   *
+   * @param message - The signing message, represented as hexadecimal input.
+   * @returns An AccountAuthenticator containing the signature and the account's public key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  signWithAuthenticator(message: HexInput): AccountAuthenticatorEd25519 {
+    return new AccountAuthenticatorEd25519(this.publicKey, this.privateKey.sign(message));
+  }
+
+  /**
+   * Sign a transaction using the account's Ed25519 private key.
+   * This function returns an AccountAuthenticator that contains the signature of the transaction along with the account's public key.
+   *
+   * @param transaction - The raw transaction to be signed.
+   * @returns An AccountAuthenticator containing the signature and the public key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorEd25519 {
+    return new AccountAuthenticatorEd25519(this.publicKey, this.signTransaction(transaction));
+  }
+
+  /**
+   * Sign the given message using the account's Ed25519 private key.
+   * @param message - The message to be signed in HexInput format.
+   * @returns Signature - The resulting signature of the signed message.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  sign(message: HexInput): Ed25519Signature {
+    return this.privateKey.sign(message);
+  }
+
+  /**
+   * Sign the given transaction using the available signing capabilities.
+   * This function helps ensure that the transaction is properly authenticated before submission.
+   *
+   * @param transaction - The transaction to be signed.
+   * @returns Signature - The resulting signature for the transaction.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  signTransaction(transaction: AnyRawTransaction): Ed25519Signature {
+    return this.sign(generateSigningMessageForTransaction(transaction));
+  }
+
+  // endregion
+}

package/src/account/EphemeralKeyPair.ts

@@ -0,0 +1,222 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { randomBytes } from "@noble/hashes/utils";
+
+import { Deserializer, Serializable, Serializer } from "../bcs";
+import {
+  bytesToBigIntLE,
+  Ed25519PrivateKey,
+  EphemeralPublicKey,
+  EphemeralSignature,
+  padAndPackBytesWithLen,
+  poseidonHash,
+  PrivateKey,
+} from "../core/crypto";
+import { Hex } from "../core/hex";
+import { EphemeralPublicKeyVariant, HexInput } from "../types";
+import { floorToWholeHour, nowInSeconds } from "../utils/helpers";
+
+const TWO_WEEKS_IN_SECONDS = 1_209_600;
+
+/**
+ * Represents an ephemeral key pair used for signing transactions via the Keyless authentication scheme.
+ * This key pair is temporary and includes an expiration time.
+ * For more details on how this class is used, refer to the documentation:
+ * https://movement.dev/guides/keyless-accounts/#1-present-the-user-with-a-sign-in-with-idp-button-on-the-ui
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+export class EphemeralKeyPair extends Serializable {
+  static readonly BLINDER_LENGTH: number = 31;
+
+  /**
+   * A byte array of length BLINDER_LENGTH used to obfuscate the public key from the IdP.
+   * Used in calculating the nonce passed to the IdP and as a secret witness in proof generation.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly blinder: Uint8Array;
+
+  /**
+   * 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.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly expiryDateSecs: number;
+
+  /**
+   * The value passed to the IdP when the user authenticates.  It consists of a hash of the
+   * ephemeral public key, expiry date, and blinder.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly nonce: string;
+
+  /**
+   * A private key used to sign transactions.  This private key is not tied to any account on the chain as it
+   * is ephemeral (not permanent) in nature.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  private privateKey: PrivateKey;
+
+  /**
+   * A public key used to verify transactions.  This public key is not tied to any account on the chain as it
+   * is ephemeral (not permanent) in nature.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  private publicKey: EphemeralPublicKey;
+
+  /**
+   * Creates an instance of the class with a specified private key, optional expiry date, and optional blinder.
+   * This constructor initializes the public key, sets the expiry date to a default value if not provided,
+   * generates a blinder if not supplied, and calculates the nonce based on the public key, expiry date, and blinder.
+   *
+   * @param args - The parameters for constructing the instance.
+   * @param args.privateKey - The private key used for creating the instance.
+   * @param args.expiryDateSecs - Optional expiry date in seconds from the current time. Defaults to two weeks from now.
+   * @param args.blinder - Optional blinder value. If not provided, a new blinder will be generated.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  constructor(args: { privateKey: PrivateKey; expiryDateSecs?: number; blinder?: HexInput }) {
+    super();
+    const { privateKey, expiryDateSecs, blinder } = args;
+    this.privateKey = privateKey;
+    this.publicKey = new EphemeralPublicKey(privateKey.publicKey());
+    // By default, we set the expiry date to be two weeks in the future floored to the nearest hour
+    this.expiryDateSecs = expiryDateSecs || floorToWholeHour(nowInSeconds() + TWO_WEEKS_IN_SECONDS);
+    // Generate the blinder if not provided
+    this.blinder = blinder !== undefined ? Hex.fromHexInput(blinder).toUint8Array() : generateBlinder();
+    // Calculate the nonce
+    const fields = padAndPackBytesWithLen(this.publicKey.bcsToBytes(), 93);
+    fields.push(BigInt(this.expiryDateSecs));
+    fields.push(bytesToBigIntLE(this.blinder));
+    const nonceHash = poseidonHash(fields);
+    this.nonce = nonceHash.toString();
+  }
+
+  /**
+   * Returns the public key of the key pair.
+   * @return EphemeralPublicKey
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  getPublicKey(): EphemeralPublicKey {
+    return this.publicKey;
+  }
+
+  /**
+   * Checks if the current time has surpassed the expiry date of the key pair.
+   * @return boolean - Returns true if the key pair is expired, otherwise false.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  isExpired(): boolean {
+    const currentTimeSecs: number = Math.floor(Date.now() / 1000);
+    return currentTimeSecs > this.expiryDateSecs;
+  }
+
+  /**
+   * Serializes the object's properties into a format suitable for transmission or storage.
+   * This function is essential for preparing the object data for serialization processes.
+   *
+   * @param serializer - The serializer instance used to serialize the object's properties.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  serialize(serializer: Serializer): void {
+    serializer.serializeU32AsUleb128(this.publicKey.variant);
+    serializer.serializeBytes(this.privateKey.toUint8Array());
+    serializer.serializeU64(this.expiryDateSecs);
+    serializer.serializeFixedBytes(this.blinder);
+  }
+
+  /**
+   * Deserializes an ephemeral key pair from the provided deserializer.
+   * This function helps in reconstructing an ephemeral key pair, which is essential for cryptographic operations.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  static deserialize(deserializer: Deserializer): EphemeralKeyPair {
+    const variantIndex = deserializer.deserializeUleb128AsU32();
+    let privateKey: PrivateKey;
+    switch (variantIndex) {
+      case EphemeralPublicKeyVariant.Ed25519:
+        privateKey = Ed25519PrivateKey.deserialize(deserializer);
+        break;
+      default:
+        throw new Error(`Unknown variant index for EphemeralPublicKey: ${variantIndex}`);
+    }
+    const expiryDateSecs = deserializer.deserializeU64();
+    const blinder = deserializer.deserializeFixedBytes(31);
+    return new EphemeralKeyPair({ privateKey, expiryDateSecs: Number(expiryDateSecs), blinder });
+  }
+
+  /**
+   * Deserialize a byte array into an EphemeralKeyPair object.
+   * This function allows you to reconstruct an EphemeralKeyPair from its serialized byte representation.
+   *
+   * @param bytes - The byte array representing the serialized EphemeralKeyPair.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  static fromBytes(bytes: Uint8Array): EphemeralKeyPair {
+    return EphemeralKeyPair.deserialize(new Deserializer(bytes));
+  }
+
+  /**
+   * Generates a new ephemeral key pair with an optional expiry date.
+   * This function allows you to create a temporary key pair for secure operations.
+   *
+   * @param args - Optional parameters for key pair generation.
+   * @param args.scheme - The type of key pair to use for the EphemeralKeyPair. Only Ed25519 is supported for now.
+   * @param args.expiryDateSecs - The date of expiry for the key pair in seconds.
+   * @returns An instance of EphemeralKeyPair containing the generated private key and expiry date.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  static generate(args?: { scheme?: EphemeralPublicKeyVariant; expiryDateSecs?: number }): EphemeralKeyPair {
+    let privateKey: PrivateKey;
+
+    switch (args?.scheme) {
+      case EphemeralPublicKeyVariant.Ed25519:
+      default:
+        privateKey = Ed25519PrivateKey.generate();
+    }
+
+    return new EphemeralKeyPair({ privateKey, expiryDateSecs: args?.expiryDateSecs });
+  }
+
+  /**
+   * Sign the given data using the private key, returning an ephemeral signature.
+   * This function is essential for creating a secure signature that can be used for authentication or verification purposes.
+   *
+   * @param data - The data to be signed, provided in HexInput format.
+   * @returns EphemeralSignature - The resulting ephemeral signature.
+   * @throws Error - Throws an error if the EphemeralKeyPair has expired.
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  sign(data: HexInput): EphemeralSignature {
+    if (this.isExpired()) {
+      throw new Error("EphemeralKeyPair has expired");
+    }
+    return new EphemeralSignature(this.privateKey.sign(data));
+  }
+}
+
+/**
+ * Generates a random byte array of length EphemeralKeyPair.BLINDER_LENGTH.
+ * @returns Uint8Array A random byte array used for blinding.
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+function generateBlinder(): Uint8Array {
+  return randomBytes(EphemeralKeyPair.BLINDER_LENGTH);
+}

package/src/account/FederatedKeylessAccount.ts

@@ -0,0 +1,178 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
+import { getIssAudAndUidVal, Groth16VerificationKey, ZeroKnowledgeSig } from "../core/crypto";
+import { HexInput } from "../types";
+
+import { Deserializer, Serializer } from "../bcs";
+import { FederatedKeylessPublicKey } from "../core/crypto/federatedKeyless";
+import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAccount";
+import { EphemeralKeyPair } from "./EphemeralKeyPair";
+
+/**
+ * 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 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.
+ * @group Implementation
+ * @category Account (On-Chain Model)
+ */
+export class FederatedKeylessAccount extends AbstractKeylessAccount {
+  /**
+   * The FederatedKeylessPublicKey associated with the account
+   * @group Implementation
+   * @category Account (On-Chain Model)
+   */
+  readonly publicKey: FederatedKeylessPublicKey;
+
+  readonly audless: boolean;
+
+  /**
+   * 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.
+   */
+  constructor(args: {
+    address?: AccountAddress;
+    ephemeralKeyPair: EphemeralKeyPair;
+    iss: string;
+    uidKey: string;
+    uidVal: string;
+    aud: string;
+    pepper: HexInput;
+    jwkAddress: AccountAddress;
+    proof: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
+    proofFetchCallback?: ProofFetchCallback;
+    jwt: string;
+    verificationKeyHash?: HexInput;
+    audless?: boolean;
+  }) {
+    const publicKey = FederatedKeylessPublicKey.create(args);
+    super({ publicKey, ...args });
+    this.publicKey = publicKey;
+    this.audless = args.audless ?? false;
+  }
+
+  /**
+   * 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 {
+    super.serialize(serializer);
+    this.publicKey.jwkAddress.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 { address, proof, ephemeralKeyPair, jwt, uidKey, pepper, verificationKeyHash } =
+      AbstractKeylessAccount.partialDeserialize(deserializer);
+    const jwkAddress = AccountAddress.deserialize(deserializer);
+    const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
+    return new FederatedKeylessAccount({
+      address,
+      proof,
+      ephemeralKeyPair,
+      iss,
+      uidKey,
+      uidVal,
+      aud,
+      pepper,
+      jwt,
+      verificationKeyHash,
+      jwkAddress,
+    });
+  }
+
+  /**
+   * Deserialize bytes using this account's information.
+   *
+   * @param bytes The bytes being interpreted.
+   * @returns
+   */
+  static fromBytes(bytes: HexInput): FederatedKeylessAccount {
+    return FederatedKeylessAccount.deserialize(Deserializer.fromHex(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>;
+    jwt: string;
+    ephemeralKeyPair: EphemeralKeyPair;
+    pepper: HexInput;
+    jwkAddress: AccountAddressInput;
+    uidKey?: string;
+    proofFetchCallback?: ProofFetchCallback;
+    verificationKey?: Groth16VerificationKey;
+    verificationKeyHash?: Uint8Array;
+  }): FederatedKeylessAccount {
+    const {
+      address,
+      proof,
+      jwt,
+      ephemeralKeyPair,
+      pepper,
+      jwkAddress,
+      uidKey = "sub",
+      proofFetchCallback,
+      verificationKey,
+      verificationKeyHash,
+    } = args;
+
+    if (verificationKeyHash && verificationKey) {
+      throw new Error("Cannot provide both verificationKey and verificationKeyHash");
+    }
+
+    const { iss, aud, uidVal } = getIssAudAndUidVal({ jwt, uidKey });
+    return new FederatedKeylessAccount({
+      address,
+      proof,
+      ephemeralKeyPair,
+      iss,
+      uidKey,
+      uidVal,
+      aud,
+      pepper,
+      jwkAddress: AccountAddress.from(jwkAddress),
+      jwt,
+      proofFetchCallback,
+      verificationKeyHash: verificationKeyHash ?? (verificationKey ? verificationKey.hash() : undefined),
+    });
+  }
+}