@moveindustries/ts-sdk 5.1.4

package/src/core/crypto/federatedKeyless.ts

@@ -0,0 +1,169 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { Signature } from "..";
+import type { MovementConfig } from "../../api";
+import { Deserializer, Serializer } from "../../bcs";
+import { AnyPublicKeyVariant, HexInput, SigningScheme } from "../../types";
+import { AccountAddress, AccountAddressInput } from "../accountAddress";
+import { AuthenticationKey } from "../authenticationKey";
+import {
+  KeylessConfiguration,
+  KeylessPublicKey,
+  KeylessSignature,
+  MoveJWK,
+  verifyKeylessSignature,
+  verifyKeylessSignatureWithJwkAndConfig,
+} from "./keyless";
+import { AccountPublicKey, PublicKey } from "./publicKey";
+
+/**
+ * Represents the FederatedKeylessPublicKey public key
+ *
+ * These keys use an on-chain address as a source of truth for the JWK used to verify signatures.
+ *
+ * FederatedKeylessPublicKey authentication key is represented in the SDK as `AnyPublicKey`.
+ * @group Implementation
+ * @category Serialization
+ */
+export class FederatedKeylessPublicKey extends AccountPublicKey {
+  /**
+   * The address that contains the JWK set to be used for verification.
+   * @group Implementation
+   * @category Serialization
+   */
+  readonly jwkAddress: AccountAddress;
+
+  /**
+   * The inner public key which contains the standard Keyless public key.
+   * @group Implementation
+   * @category Serialization
+   */
+  readonly keylessPublicKey: KeylessPublicKey;
+
+  constructor(jwkAddress: AccountAddressInput, keylessPublicKey: KeylessPublicKey) {
+    super();
+    this.jwkAddress = AccountAddress.from(jwkAddress);
+    this.keylessPublicKey = keylessPublicKey;
+  }
+
+  /**
+   * Get the authentication key for the federated keyless public key
+   *
+   * @returns AuthenticationKey
+   * @group Implementation
+   * @category Serialization
+   */
+  authKey(): AuthenticationKey {
+    const serializer = new Serializer();
+    serializer.serializeU32AsUleb128(AnyPublicKeyVariant.FederatedKeyless);
+    serializer.serializeFixedBytes(this.bcsToBytes());
+    return AuthenticationKey.fromSchemeAndBytes({
+      scheme: SigningScheme.SingleKey,
+      input: serializer.toUint8Array(),
+    });
+  }
+
+  /**
+   * Verifies a signed data with a public key
+   *
+   * @param args.message message
+   * @param args.signature The signature
+   * @param args.jwk - The JWK to use for verification.
+   * @param args.keylessConfig - The keyless configuration to use for verification.
+   * @returns true if the signature is valid
+   * @group Implementation
+   * @category Serialization
+   */
+  verifySignature(args: {
+    message: HexInput;
+    signature: Signature;
+    jwk: MoveJWK;
+    keylessConfig: KeylessConfiguration;
+  }): boolean {
+    try {
+      verifyKeylessSignatureWithJwkAndConfig({ ...args, publicKey: this });
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  serialize(serializer: Serializer): void {
+    this.jwkAddress.serialize(serializer);
+    this.keylessPublicKey.serialize(serializer);
+  }
+
+  static deserialize(deserializer: Deserializer): FederatedKeylessPublicKey {
+    const jwkAddress = AccountAddress.deserialize(deserializer);
+    const keylessPublicKey = KeylessPublicKey.deserialize(deserializer);
+    return new FederatedKeylessPublicKey(jwkAddress, keylessPublicKey);
+  }
+
+  static isPublicKey(publicKey: PublicKey): publicKey is FederatedKeylessPublicKey {
+    return publicKey instanceof FederatedKeylessPublicKey;
+  }
+
+  /**
+   * Verifies a keyless signature for a given message.  It will fetch the keyless configuration and the JWK to
+   * use for verification from the appropriate network as defined by the movementConfig.
+   *
+   * @param args.movementConfig The aptos config to use for fetching the keyless configuration.
+   * @param args.message The message to verify the signature against.
+   * @param args.signature The signature to verify.
+   * @param args.options.throwErrorWithReason Whether to throw an error with the reason for the failure instead of returning false.
+   * @returns true if the signature is valid
+   */
+  async verifySignatureAsync(args: {
+    movementConfig: MovementConfig;
+    message: HexInput;
+    signature: KeylessSignature;
+    options?: { throwErrorWithReason?: boolean };
+  }): Promise<boolean> {
+    return verifyKeylessSignature({
+      ...args,
+      publicKey: this,
+    });
+  }
+
+  /**
+   * Creates a FederatedKeylessPublicKey from the JWT components plus pepper
+   *
+   * @param args.iss the iss of the identity
+   * @param args.uidKey the key to use to get the uidVal in the JWT token
+   * @param args.uidVal the value of the uidKey in the JWT token
+   * @param args.aud the client ID of the application
+   * @param args.pepper The pepper used to maintain privacy of the account
+   * @returns FederatedKeylessPublicKey
+   * @group Implementation
+   * @category Serialization
+   */
+  static create(args: {
+    iss: string;
+    uidKey: string;
+    uidVal: string;
+    aud: string;
+    pepper: HexInput;
+    jwkAddress: AccountAddressInput;
+  }): FederatedKeylessPublicKey {
+    return new FederatedKeylessPublicKey(args.jwkAddress, KeylessPublicKey.create(args));
+  }
+
+  static fromJwtAndPepper(args: {
+    jwt: string;
+    pepper: HexInput;
+    jwkAddress: AccountAddressInput;
+    uidKey?: string;
+  }): FederatedKeylessPublicKey {
+    return new FederatedKeylessPublicKey(args.jwkAddress, KeylessPublicKey.fromJwtAndPepper(args));
+  }
+
+  static isInstance(publicKey: PublicKey) {
+    return (
+      "jwkAddress" in publicKey &&
+      publicKey.jwkAddress instanceof AccountAddress &&
+      "keylessPublicKey" in publicKey &&
+      publicKey.keylessPublicKey instanceof KeylessPublicKey
+    );
+  }
+}

package/src/core/crypto/hdKey.ts

@@ -0,0 +1,136 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+import { hmac } from "@noble/hashes/hmac";
+import { sha512 } from "@noble/hashes/sha512";
+import * as bip39 from "@scure/bip39";
+
+/**
+ * Contains the derived cryptographic key as a Uint8Array.
+ * @group Implementation
+ * @category Serialization
+ */
+export type DerivedKeys = {
+  key: Uint8Array;
+  chainCode: Uint8Array;
+};
+
+/**
+ * Movement derive path is 637
+ * @group Implementation
+ * @category Serialization
+ */
+export const MOVEMENT_HARDENED_REGEX = /^m\/44'\/637'\/[0-9]+'\/[0-9]+'\/[0-9]+'?$/;
+
+/**
+ * @group Implementation
+ * @category Serialization
+ */
+export const MOVEMENT_BIP44_REGEX = /^m\/44'\/637'\/[0-9]+'\/[0-9]+\/[0-9]+$/;
+
+/**
+ * Supported key types and their associated seeds.
+ * @group Implementation
+ * @category Serialization
+ */
+export enum KeyType {
+  ED25519 = "ed25519 seed",
+}
+
+/**
+ * @group Implementation
+ * @category Serialization
+ */
+export const HARDENED_OFFSET = 0x80000000;
+
+/**
+ * Validate a BIP-44 derivation path string to ensure it meets the required format.
+ * This function checks if the provided path adheres to the BIP-44 standard for Secp256k1.
+ * Parse and validate a path that is compliant to BIP-44 in form m/44'/637'/{account_index}'/{change_index}/{address_index}
+ * for Secp256k1
+ *
+ * Note that for Secp256k1, the last two components must be non-hardened.
+ *
+ * @param path - The path string to validate (e.g. `m/44'/637'/0'/0/0`).
+ * @group Implementation
+ * @category Serialization
+ */
+export function isValidBIP44Path(path: string): boolean {
+  return MOVEMENT_BIP44_REGEX.test(path);
+}
+
+/**
+ * Movement derive path is 637
+ *
+ * Parse and validate a path that is compliant to SLIP-0010 and BIP-44
+ * in form m/44'/637'/{account_index}'/{change_index}'/{address_index}'.
+ * See SLIP-0010 {@link https://github.com/satoshilabs/slips/blob/master/slip-0044.md}
+ * See BIP-44 {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
+ *
+ * Note that for Ed25519, all components must be hardened.
+ * This is because non-hardened [PK] derivation would not work due to Ed25519's lack of a key homomorphism.
+ * Specifically, you cannot derive the PK associated with derivation path a/b/c given the PK of a/b.
+ * This is because the PK in Ed25519 is, more or less, computed as 𝑔𝐻(𝑠𝑘),
+ * with the hash function breaking the homomorphism.
+ *
+ * @param path - The derivation path string to validate (e.g. `m/44'/637'/0'/0'/0'`).
+ * @group Implementation
+ * @category Serialization
+ */
+export function isValidHardenedPath(path: string): boolean {
+  return MOVEMENT_HARDENED_REGEX.test(path);
+}
+
+/**
+ * @group Implementation
+ * @category Serialization
+ */
+export const deriveKey = (hashSeed: Uint8Array | string, data: Uint8Array | string): DerivedKeys => {
+  const digest = hmac.create(sha512, hashSeed).update(data).digest();
+  return {
+    key: digest.slice(0, 32),
+    chainCode: digest.slice(32),
+  };
+};
+
+/**
+ * Derive a child key from the private key
+ * @param key
+ * @param chainCode
+ * @param index
+ * @group Implementation
+ * @category Serialization
+ */
+export const CKDPriv = ({ key, chainCode }: DerivedKeys, index: number): DerivedKeys => {
+  const buffer = new ArrayBuffer(4);
+  new DataView(buffer).setUint32(0, index);
+  const indexBytes = new Uint8Array(buffer);
+  const zero = new Uint8Array([0]);
+  const data = new Uint8Array([...zero, ...key, ...indexBytes]);
+  return deriveKey(chainCode, data);
+};
+
+const removeApostrophes = (val: string): string => val.replace(/'/g, "");
+
+/**
+ * Splits derive path into segments
+ * @param path
+ * @group Implementation
+ * @category Serialization
+ */
+export const splitPath = (path: string): Array<string> => path.split("/").slice(1).map(removeApostrophes);
+
+/**
+ * Normalizes the mnemonic by removing extra whitespace and making it lowercase
+ * @param mnemonic the mnemonic seed phrase
+ * @group Implementation
+ * @category Serialization
+ */
+export const mnemonicToSeed = (mnemonic: string): Uint8Array => {
+  const normalizedMnemonic = mnemonic
+    .trim()
+    .split(/\s+/)
+    .map((part) => part.toLowerCase())
+    .join(" ");
+  return bip39.mnemonicToSeedSync(normalizedMnemonic);
+};

package/src/core/crypto/index.ts

@@ -0,0 +1,21 @@
+// Copyright © Move Industries
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./abstraction";
+export * from "./deserializationUtils";
+export * from "./ed25519";
+export * from "./ephemeral";
+export * from "./federatedKeyless";
+export * from "./hdKey";
+export * from "./keyless";
+export * from "./multiEd25519";
+export * from "./multiKey";
+export * from "./poseidon";
+export * from "./privateKey";
+export * from "./publicKey";
+export * from "./secp256k1";
+export * from "./secp256r1";
+export * from "./signature";
+export * from "./singleKey";
+export * from "./types";
+