@moveindustries/ts-sdk 5.1.4

package/src/core/authenticationKey.ts

@@ -0,0 +1,157 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { sha3_256 as sha3Hash } from "@noble/hashes/sha3";
+import { Deserializer } from "../bcs/deserializer";
+import { Serializable, Serializer } from "../bcs/serializer";
+import { AuthenticationKeyScheme, HexInput } from "../types";
+import { AccountAddress } from "./accountAddress";
+import type { AccountPublicKey } from "./crypto";
+import { Hex } from "./hex";
+
+/**
+ * Represents an authentication key used for account management. Each account stores an authentication key that enables account
+ * owners to rotate their private key(s) without changing the address that hosts their account. The authentication key is a
+ * SHA3-256 hash of data and is always 32 bytes in length.
+ *
+ * @see {@link https://movement.dev/concepts/accounts | Account Basics}
+ *
+ * Account addresses can be derived from the AuthenticationKey.
+ * @group Implementation
+ * @category Serialization
+ */
+export class AuthenticationKey extends Serializable {
+  /**
+   * An authentication key is always a SHA3-256 hash of data, and is always 32 bytes.
+   *
+   * The data to hash depends on the underlying public key type and the derivation scheme.
+   * @group Implementation
+   * @category Serialization
+   */
+  static readonly LENGTH: number = 32;
+
+  /**
+   * The raw bytes of the authentication key.
+   * @group Implementation
+   * @category Serialization
+   */
+  public readonly data: Hex;
+
+  /**
+   * Creates an instance of the AuthenticationKey using the provided hex input.
+   * This ensures that the hex input is valid and conforms to the required length for an Authentication Key.
+   *
+   * @param args - The arguments for constructing the AuthenticationKey.
+   * @param args.data - The hex input data to be used for the Authentication Key.
+   * @throws {Error} Throws an error if the length of the provided hex input is not equal to the required Authentication Key
+   * length.
+   * @group Implementation
+   * @category Serialization
+   */
+  constructor(args: { data: HexInput }) {
+    super();
+    const { data } = args;
+    const hex = Hex.fromHexInput(data);
+    if (hex.toUint8Array().length !== AuthenticationKey.LENGTH) {
+      throw new Error(`Authentication Key length should be ${AuthenticationKey.LENGTH}`);
+    }
+    this.data = hex;
+  }
+
+  /**
+   * Serializes the fixed bytes data into a format suitable for transmission or storage.
+   *
+   * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category Serialization
+   */
+  serialize(serializer: Serializer): void {
+    serializer.serializeFixedBytes(this.data.toUint8Array());
+  }
+
+  /**
+   * Deserialize an AuthenticationKey from the byte buffer in a Deserializer instance.
+   * @param deserializer - The deserializer to deserialize the AuthenticationKey from.
+   * @returns An instance of AuthenticationKey.
+   * @group Implementation
+   * @category Serialization
+   */
+  static deserialize(deserializer: Deserializer): AuthenticationKey {
+    const bytes = deserializer.deserializeFixedBytes(AuthenticationKey.LENGTH);
+    return new AuthenticationKey({ data: bytes });
+  }
+
+  /**
+   * Convert the internal data representation to a Uint8Array.
+   *
+   * This function is useful for obtaining a byte representation of the data, which can be utilized for serialization or transmission.
+   *
+   * @returns Uint8Array representation of the internal data.
+   * @group Implementation
+   * @category Serialization
+   */
+  toUint8Array(): Uint8Array {
+    return this.data.toUint8Array();
+  }
+
+  /**
+   * Generates an AuthenticationKey from the specified scheme and input bytes.
+   * This function is essential for creating a valid authentication key based on a given scheme.
+   *
+   * @param args - The arguments for generating the AuthenticationKey.
+   * @param args.scheme - The authentication key scheme to use.
+   * @param args.input - The input data in hexadecimal format to derive the key.
+   * @returns An instance of AuthenticationKey containing the generated key data.
+   * @group Implementation
+   * @category Serialization
+   */
+  static fromSchemeAndBytes(args: { scheme: AuthenticationKeyScheme; input: HexInput }): AuthenticationKey {
+    const { scheme, input } = args;
+    const inputBytes = Hex.fromHexInput(input).toUint8Array();
+    const hashInput = new Uint8Array([...inputBytes, scheme]);
+    const hash = sha3Hash.create();
+    hash.update(hashInput);
+    const hashDigest = hash.digest();
+    return new AuthenticationKey({ data: hashDigest });
+  }
+
+  /**
+   * Derives an AuthenticationKey from the provided public key using a specified derivation scheme.
+   *
+   * @deprecated Use `fromPublicKey` instead.
+   * @param args - The arguments for deriving the authentication key.
+   * @param args.publicKey - The public key used for the derivation.
+   * @param args.scheme - The scheme to use for deriving the authentication key.
+   * @group Implementation
+   * @category Serialization
+   */
+  public static fromPublicKeyAndScheme(args: { publicKey: AccountPublicKey; scheme: AuthenticationKeyScheme }) {
+    const { publicKey } = args;
+    return publicKey.authKey();
+  }
+
+  /**
+   * Converts a PublicKey to an AuthenticationKey using the derivation scheme inferred from the provided PublicKey instance.
+   *
+   * @param args - The arguments for the function.
+   * @param args.publicKey - The PublicKey to be converted.
+   * @returns AuthenticationKey - The derived AuthenticationKey.
+   * @group Implementation
+   * @category Serialization
+   */
+  static fromPublicKey(args: { publicKey: AccountPublicKey }): AuthenticationKey {
+    const { publicKey } = args;
+    return publicKey.authKey();
+  }
+
+  /**
+   * Derives an account address from an AuthenticationKey by translating the AuthenticationKey bytes directly to an AccountAddress.
+   *
+   * @returns AccountAddress - The derived account address.
+   * @group Implementation
+   * @category Serialization
+   */
+  derivedAddress(): AccountAddress {
+    return new AccountAddress(this.data.toUint8Array());
+  }
+}

package/src/core/common.ts

@@ -0,0 +1,60 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * This error is used to explain why parsing failed.
+ * @group Implementation
+ * @category Serialization
+ */
+export class ParsingError<T> extends Error {
+  /**
+   * This provides a programmatic way to access why parsing failed. Downstream devs
+   * might want to use this to build their own error messages if the default error
+   * messages are not suitable for their use case. This should be an enum.
+   * @group Implementation
+   * @category Serialization
+   */
+  public invalidReason: T;
+
+  /**
+   * Creates an instance of the error with a specified message and invalid reason.
+   *
+   * @param message The error message that describes the issue.
+   * @param invalidReason The reason why the input is considered invalid.
+   * @group Implementation
+   * @category Serialization
+   */
+  constructor(message: string, invalidReason: T) {
+    super(message);
+    this.invalidReason = invalidReason;
+  }
+}
+
+/**
+ * Whereas ParsingError is thrown when parsing fails, e.g. in a fromString function,
+ * this type is returned from "defensive" functions like isValid.
+ * @group Implementation
+ * @category Serialization
+ */
+export type ParsingResult<T> = {
+  /**
+   * True if valid, false otherwise.
+   * @group Implementation
+   * @category Serialization
+   */
+  valid: boolean;
+
+  /**
+   * If valid is false, this will be a code explaining why parsing failed.
+   * @group Implementation
+   * @category Serialization
+   */
+  invalidReason?: T;
+
+  /**
+   * If valid is false, this will be a string explaining why parsing failed.
+   * @group Implementation
+   * @category Serialization
+   */
+  invalidReasonMessage?: string;
+};

package/src/core/crypto/abstraction.ts

@@ -0,0 +1,52 @@
+import { Deserializer, Serializer } from "../../bcs";
+import { HexInput } from "../../types";
+import { AccountAddress } from "../accountAddress";
+import { AuthenticationKey } from "../authenticationKey";
+import { Hex } from "../hex";
+import { AccountPublicKey, VerifySignatureArgs, VerifySignatureAsyncArgs } from "./publicKey";
+import { Signature } from "./signature";
+
+export class AbstractSignature extends Signature {
+  readonly value: Uint8Array;
+
+  constructor(value: HexInput) {
+    super();
+    this.value = Hex.fromHexInput(value).toUint8Array();
+  }
+
+  serialize(serializer: Serializer): void {
+    serializer.serializeBytes(this.value);
+  }
+
+  static deserialize(deserializer: Deserializer): AbstractSignature {
+    return new AbstractSignature(deserializer.deserializeBytes());
+  }
+}
+
+export class AbstractPublicKey extends AccountPublicKey {
+  readonly accountAddress: AccountAddress;
+
+  constructor(accountAddress: AccountAddress) {
+    super();
+    this.accountAddress = accountAddress;
+  }
+
+  authKey(): AuthenticationKey {
+    return new AuthenticationKey({ data: this.accountAddress.toUint8Array() });
+  }
+
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  verifySignature(args: VerifySignatureArgs): boolean {
+    throw new Error("This function is not implemented for AbstractPublicKey.");
+  }
+
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  async verifySignatureAsync(args: VerifySignatureAsyncArgs): Promise<boolean> {
+    throw new Error("This function is not implemented for AbstractPublicKey.");
+  }
+
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  serialize(serializer: Serializer): void {
+    throw new Error("This function is not implemented for AbstractPublicKey.");
+  }
+}

package/src/core/crypto/deserializationUtils.ts

@@ -0,0 +1,106 @@
+import {
+  AnyPublicKey,
+  Ed25519PublicKey,
+  MultiKey,
+  KeylessPublicKey,
+  MultiEd25519PublicKey,
+  FederatedKeylessPublicKey,
+  Secp256k1PublicKey,
+  Signature,
+  PublicKey,
+  Ed25519Signature,
+  Secp256k1Signature,
+  KeylessSignature,
+  AnySignature,
+  MultiEd25519Signature,
+  MultiKeySignature,
+} from "..";
+import { Deserializer } from "../../bcs/deserializer";
+import { HexInput } from "../../types";
+
+const MULTIPLE_DESERIALIZATIONS_ERROR_MSG = "Multiple possible deserializations found";
+
+/**
+ * Deserializes a public key from a hex string.
+ * Attempts to deserialize using various public key types in sequence until one succeeds.
+ *
+ * @param publicKey - The hex string representation of the public key to deserialize
+ * @returns The deserialized public key
+ * @throws Error if deserialization fails for all supported key types or if multiple deserializations are found
+ */
+export function deserializePublicKey(publicKey: HexInput): PublicKey {
+  const publicKeyTypes = [
+    Ed25519PublicKey,
+    AnyPublicKey,
+    MultiEd25519PublicKey,
+    MultiKey,
+    KeylessPublicKey,
+    FederatedKeylessPublicKey,
+    Secp256k1PublicKey,
+  ];
+
+  let result: PublicKey | undefined;
+  for (const KeyType of publicKeyTypes) {
+    try {
+      const deserializer = Deserializer.fromHex(publicKey);
+      const key = KeyType.deserialize(deserializer);
+      deserializer.assertFinished();
+      if (result) {
+        throw new Error(`${MULTIPLE_DESERIALIZATIONS_ERROR_MSG}: ${publicKey}`);
+      }
+      result = key;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes(MULTIPLE_DESERIALIZATIONS_ERROR_MSG)) {
+        throw error;
+      }
+    }
+  }
+
+  if (!result) {
+    throw new Error(`Failed to deserialize public key: ${publicKey}`);
+  }
+
+  return result;
+}
+
+/**
+ * Deserializes a signature from a hex string.
+ * Attempts to deserialize using various signature types in sequence until one succeeds.
+ *
+ * @param signature - The hex string representation of the signature to deserialize
+ * @returns The deserialized signature
+ * @throws Error if deserialization fails for all supported signature types or if multiple deserializations are found
+ */
+export function deserializeSignature(signature: HexInput): Signature {
+  const signatureTypes = [
+    Ed25519Signature,
+    AnySignature,
+    MultiEd25519Signature,
+    MultiKeySignature,
+    KeylessSignature,
+    Secp256k1Signature,
+  ];
+
+  let result: Signature | undefined;
+  for (const SignatureType of signatureTypes) {
+    try {
+      const deserializer = Deserializer.fromHex(signature);
+      const sig = SignatureType.deserialize(deserializer);
+      deserializer.assertFinished();
+      if (result) {
+        throw new Error(`${MULTIPLE_DESERIALIZATIONS_ERROR_MSG}: ${signature}`);
+      }
+      result = sig;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes(MULTIPLE_DESERIALIZATIONS_ERROR_MSG)) {
+        throw error;
+      }
+    }
+  }
+
+  if (!result) {
+    throw new Error(`Failed to deserialize signature: ${signature}`);
+  }
+
+  return result;
+}