diff --git a/.changeset/happy-hornets-turn.md b/.changeset/happy-hornets-turn.md new file mode 100644 index 0000000000..9a21e0adfb --- /dev/null +++ b/.changeset/happy-hornets-turn.md @@ -0,0 +1,5 @@ +--- +"@kadena/hd-wallet": patch +--- + +Expose api doc diff --git a/packages/libs/hd-wallet/etc/hd-wallet.api.md b/packages/libs/hd-wallet/etc/hd-wallet.api.md new file mode 100644 index 0000000000..2fefcd159b --- /dev/null +++ b/packages/libs/hd-wallet/etc/hd-wallet.api.md @@ -0,0 +1,68 @@ +## API Report File for "@kadena/hd-wallet" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +import { EncryptedString as EncryptedString_2 } from '../utils/kadenaEncryption.js'; + +// @public (undocumented) +export type EncryptedString = string & { + _brand: 'EncryptedString'; +}; + +// Warning: (ae-forgotten-export) The symbol "BinaryLike" needs to be exported by the entry point index.d.ts +// +// @public +export function kadenaChangePassword(password: BinaryLike, encryptedData: BinaryLike, newPassword: string): Promise; + +// @public +export function kadenaDecrypt(password: BinaryLike, encryptedData: BinaryLike): Promise; + +// @public +export function kadenaEncrypt(password: BinaryLike, message: BinaryLike, encode?: TEncode): Promise; + +// @public (undocumented) +export function kadenaGenKeypairFromSeed(password: BinaryLike, seed: EncryptedString, index: number, derivationPathTemplate?: string): Promise<[string, EncryptedString]>; + +// @public (undocumented) +export function kadenaGenKeypairFromSeed(password: BinaryLike, seed: EncryptedString, indexRange: [number, number], derivationPathTemplate?: string): Promise>; + +// @public +export function kadenaGenMnemonic(): string; + +// @public (undocumented) +export function kadenaGetPublic(password: BinaryLike, seed: BinaryLike, index: number, derivationPathTemplate?: string): Promise; + +// @public (undocumented) +export function kadenaGetPublic(password: BinaryLike, seed: BinaryLike, indexRange: [number, number], derivationPathTemplate?: string): Promise; + +// @public +export function kadenaKeyPairsFromRandom(count?: number): { + publicKey: string; + secretKey: string; +}[]; + +// @public +export function kadenaMnemonicToSeed(password: BinaryLike, mnemonic: string, encode?: TEncode): Promise; + +// Warning: (ae-forgotten-export) The symbol "ISignatureWithPublicKey" needs to be exported by the entry point index.d.ts +// +// @public +export function kadenaSignWithKeyPair(password: BinaryLike, publicKey: string, encryptedPrivateKey: EncryptedString): (hash: string) => Promise; + +// @public +export function kadenaSignWithSeed(password: BinaryLike, seed: BinaryLike, index: number, derivationPathTemplate?: string): (hash: string) => Promise; + +// @public +export function kadenaSignWithSeed(password: BinaryLike, seed: BinaryLike, indexRange: number[], derivationPathTemplate?: string): (hash: string) => Promise; + +// @public +export function kadenaVerify(message: BinaryLike, publicKey: string, signature: string): boolean; + +// @public (undocumented) +export const randomBytes: (size: number) => Uint8Array; + +// (No @packageDocumentation comment for this package) + +``` diff --git a/packages/libs/hd-wallet/package.json b/packages/libs/hd-wallet/package.json index 40a3ae6904..d459fa262f 100644 --- a/packages/libs/hd-wallet/package.json +++ b/packages/libs/hd-wallet/package.json @@ -37,7 +37,7 @@ "chainweaver" ], "scripts": { - "build": "tsc -p tsconfig.cjs.json && tsc && api-extractor run || true && cpy ./src/chainweaver/vendor/**/* ./lib/cjs/chainweaver/vendor/ && cpy ./src/chainweaver/vendor/**/* ./lib/esm/chainweaver/vendor/ && cp ./package.cjs.json ./lib/cjs/package.json", + "build": "tsc -p tsconfig.cjs.json && tsc && api-extractor run && cpy ./src/chainweaver/vendor/**/* ./lib/cjs/chainweaver/vendor/ && cpy ./src/chainweaver/vendor/**/* ./lib/esm/chainweaver/vendor/ && cp ./package.cjs.json ./lib/cjs/package.json", "format": "pnpm run --sequential /^format:.*/", "format:lint": "pnpm run lint:src --fix", "format:md": "remark README.md -o --use @kadena-dev/markdown", diff --git a/packages/libs/hd-wallet/src/SLIP10/kadenaGenKeypairFromSeed.ts b/packages/libs/hd-wallet/src/SLIP10/kadenaGenKeypairFromSeed.ts index 1530b59672..1d1c30c0ba 100644 --- a/packages/libs/hd-wallet/src/SLIP10/kadenaGenKeypairFromSeed.ts +++ b/packages/libs/hd-wallet/src/SLIP10/kadenaGenKeypairFromSeed.ts @@ -30,11 +30,11 @@ async function genKeypairFromSeed( /** * - * @param password - * @param seed - * @param index - * @param derivationPathTemplate - * @alpha + * @param password - password for decrypting the seed + * @param seed - encrypted seed to generate keypair + * @param index - index to generate keypair + * @param derivationPathTemplate - derivation path template + * @public */ export function kadenaGenKeypairFromSeed( password: BinaryLike, @@ -43,6 +43,14 @@ export function kadenaGenKeypairFromSeed( derivationPathTemplate?: string, ): Promise<[string, EncryptedString]>; +/** + * + * @param password - password for decrypting the seed + * @param seed - encrypted seed to generate keypair + * @param indexRange - range of indices to generate keypair + * @param derivationPathTemplate - derivation path template + * @public + */ export function kadenaGenKeypairFromSeed( password: BinaryLike, seed: EncryptedString, diff --git a/packages/libs/hd-wallet/src/SLIP10/kadenaGetPublic.ts b/packages/libs/hd-wallet/src/SLIP10/kadenaGetPublic.ts index 390ee10c0b..67f09cecc6 100644 --- a/packages/libs/hd-wallet/src/SLIP10/kadenaGetPublic.ts +++ b/packages/libs/hd-wallet/src/SLIP10/kadenaGetPublic.ts @@ -22,6 +22,14 @@ function genPublicKeyFromSeed( return publicKey; } +/** + * + * @param password - password for decrypting the seed + * @param seed - encrypted seed to generate keypair + * @param index - index to generate public key + * @param derivationPathTemplate - derivation path template + * @public + */ export function kadenaGetPublic( password: BinaryLike, seed: BinaryLike, @@ -29,6 +37,14 @@ export function kadenaGetPublic( derivationPathTemplate?: string, ): Promise; +/** + * + * @param password - password for decrypting the seed + * @param seed - encrypted seed to generate keypair + * @param indexRange - range of indices to generate public keys + * @param derivationPathTemplate - derivation path template + * @public + */ export function kadenaGetPublic( password: BinaryLike, seed: BinaryLike, diff --git a/packages/libs/hd-wallet/src/SLIP10/kadenaKeyPairsFromRandom.ts b/packages/libs/hd-wallet/src/SLIP10/kadenaKeyPairsFromRandom.ts index 1e42a84203..bc82fa01ac 100644 --- a/packages/libs/hd-wallet/src/SLIP10/kadenaKeyPairsFromRandom.ts +++ b/packages/libs/hd-wallet/src/SLIP10/kadenaKeyPairsFromRandom.ts @@ -3,8 +3,9 @@ import { deriveKeyPair } from './utils/sign.js'; /** * Generates random key pairs without updating the internal state. * - * @param {number} [count=1] - The number of key pairs to generate. - * @returns {{ publicKey: string; secretKey: string }[]} An array of generated key pairs. + * @param count - The number of key pairs to generate default is `1`. + * @returns An array of generated key pairs. + * @public */ export function kadenaKeyPairsFromRandom( count: number = 1, diff --git a/packages/libs/hd-wallet/src/SLIP10/kadenaMnemonic.ts b/packages/libs/hd-wallet/src/SLIP10/kadenaMnemonic.ts index 70fa82f5bb..ca019e5b29 100644 --- a/packages/libs/hd-wallet/src/SLIP10/kadenaMnemonic.ts +++ b/packages/libs/hd-wallet/src/SLIP10/kadenaMnemonic.ts @@ -5,8 +5,9 @@ import { kadenaEncrypt } from '../utils/kadenaEncryption.js'; /** * Generates a mnemonic phrase using the BIP39 protocol with a specified wordlist. * - * @returns {string} A valid BIP39 mnemonic phrase. - * @throws {Error} If the generated mnemonic is invalid. + * @returns A valid BIP39 mnemonic phrase. + * @throws If the generated mnemonic is invalid. + * @public */ export function kadenaGenMnemonic(): string { return bip39.generateMnemonic(wordlist); @@ -15,10 +16,11 @@ export function kadenaGenMnemonic(): string { /** * Convert a given mnemonic phrase into a seed buffer. * - * @param {string} mnemonic - A mnemonic seed phrase to be converted into a seed buffer. - * @param {string} [password] - Optional password for encrypting the seed. - * @throws {Error} Throws an error if the provided mnemonic is not valid. - * @returns {Promise<{ seedBuffer: Uint8Array, seed: string }>} - Returns the seed buffer and processed seed. + * @param mnemonic - A mnemonic seed phrase to be converted into a seed buffer. + * @param password - Optional password for encrypting the seed. + * @throws Throws an error if the provided mnemonic is not valid. + * @returns Returns the seed buffer and processed seed. + * @public */ export async function kadenaMnemonicToSeed< TEncode extends 'base64' | 'buffer' = 'base64', diff --git a/packages/libs/hd-wallet/src/SLIP10/kadenaSign.ts b/packages/libs/hd-wallet/src/SLIP10/kadenaSign.ts index 018e5251ec..374dae5001 100644 --- a/packages/libs/hd-wallet/src/SLIP10/kadenaSign.ts +++ b/packages/libs/hd-wallet/src/SLIP10/kadenaSign.ts @@ -9,9 +9,10 @@ import { signWithKeyPair, signWithSeed } from './utils/sign.js'; /** * Signs a Kadena transaction with a given public and private key pair. * - * @param {string} publicKey - The public key to be used for signing the transaction. - * @param {string} encryptedPrivateKey - The private key to be used for signing the transaction. - * @returns {Function} A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures. + * @param publicKey - The public key to be used for signing the transaction. + * @param encryptedPrivateKey - The private key to be used for signing the transaction. + * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures. + * @public */ export function kadenaSignWithKeyPair( password: BinaryLike, @@ -31,6 +32,14 @@ export function kadenaSignWithKeyPair( )(hash); } +/** + * Signs a Kadena transaction with a seed and index. + * + * @param seed - The encrypted seed used to derive key pairs for signing. + * @param index - The index number used to select the correct key pair from the derived set. + * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures. + * @public + */ export function kadenaSignWithSeed( password: BinaryLike, seed: BinaryLike, @@ -38,19 +47,27 @@ export function kadenaSignWithSeed( derivationPathTemplate?: string, ): (hash: string) => Promise; +/** + * Signs a Kadena transaction with a seed and index. + * + * @param seed - The encrypted seed used to derive key pairs for signing. + * @param indexRange - The index range used to select the correct key pair from the derived set. + * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures. + * @public + */ export function kadenaSignWithSeed( password: BinaryLike, seed: BinaryLike, - index: number[], + indexRange: number[], derivationPathTemplate?: string, ): (hash: string) => Promise; /** * Signs a Kadena transaction with a seed and index. * - * @param {Uint8Array} seed - The seed array used to derive key pairs for signing. - * @param {number} index - The index number used to select the correct key pair from the derived set. - * @returns {Function} A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures. + * @param seed - The seed array used to derive key pairs for signing. + * @param index - The index number used to select the correct key pair from the derived set. + * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures. */ export function kadenaSignWithSeed( password: BinaryLike, @@ -88,10 +105,11 @@ export function kadenaSignWithSeed( /** * Verifies the signature for a message against a given public key using the Kadena signature verification convention. * - * @param {string} message - The message in string format to be verified. - * @param {string} publicKey - The public key in hexadecimal string format to verify the signature against. - * @param {string} signature - The signature in hexadecimal string format to be verified. - * @returns {boolean} - Returns true if verification succeeded or false if it failed. + * @param message - The message in string format to be verified. + * @param publicKey - The public key in hexadecimal string format to verify the signature against. + * @param signature - The signature in hexadecimal string format to be verified. + * @returns Returns true if verification succeeded or false if it failed. + * @public */ export function kadenaVerify( message: BinaryLike, diff --git a/packages/libs/hd-wallet/src/SLIP10/utils/sign.ts b/packages/libs/hd-wallet/src/SLIP10/utils/sign.ts index 5562c443fb..1b77c3e283 100644 --- a/packages/libs/hd-wallet/src/SLIP10/utils/sign.ts +++ b/packages/libs/hd-wallet/src/SLIP10/utils/sign.ts @@ -9,10 +9,11 @@ export interface ISignatureWithPublicKey { } /** - * Derive a key pair using a seed and an index. - * @param {Uint8Array} seed - The seed for key derivation. - * @param {number} index - The index for key derivation. - * @returns {{ privateKey: string; publicKey: string }} - Returns the derived private and public keys. + * Derive a key pair using a seed and an index. the seed need to be decrypted before using this function. + * @param seed - The seed for key derivation. + * @param index - The index for key derivation. + * @returns Returns the derived private and public keys. + * @internal */ export const deriveKeyPair = ( seed: Uint8Array, diff --git a/packages/libs/hd-wallet/src/utils/crypto.ts b/packages/libs/hd-wallet/src/utils/crypto.ts index 680314327d..6c1d99bc7e 100644 --- a/packages/libs/hd-wallet/src/utils/crypto.ts +++ b/packages/libs/hd-wallet/src/utils/crypto.ts @@ -1,5 +1,11 @@ export type BinaryLike = string | ArrayBuffer | Uint8Array; +/** + * + * @param size - size of random bytes + * @returns Uint8Array of random bytes + * @public + */ export const randomBytes = (size: number) => crypto.getRandomValues(new Uint8Array(size)); diff --git a/packages/libs/hd-wallet/src/utils/kadenaEncryption.ts b/packages/libs/hd-wallet/src/utils/kadenaEncryption.ts index 8682f92902..751276f3fa 100644 --- a/packages/libs/hd-wallet/src/utils/kadenaEncryption.ts +++ b/packages/libs/hd-wallet/src/utils/kadenaEncryption.ts @@ -1,13 +1,17 @@ import type { BinaryLike } from './crypto.js'; import { decrypt, encrypt, randomBytes } from './crypto.js'; +/** + * @public + */ export type EncryptedString = string & { _brand: 'EncryptedString' }; /** * Encrypts the message with a password . - * @param {BinaryLike} message - The message to be encrypted. - * @param {BinaryLike} password - password used for encryption. - * @returns {string} The encrypted string + * @param message - The message to be encrypted. + * @param password - password used for encryption. + * @returns The encrypted string + * @public */ export async function kadenaEncrypt< TEncode extends 'base64' | 'buffer' = 'base64', @@ -41,11 +45,11 @@ export async function kadenaEncrypt< * This function is a wrapper for the internal decryption logic, intended * for public-facing API usage where the private key encryption follows * - * @param {string} encryptedData - The encrypted data as a Base64 encoded string. - * @param {BinaryLike} password - The password used to encrypt the private key. - * @returns {Uint8Array} The decrypted private key. - * @throws {Error} Throws an error if decryption fails. - * @alpha + * @param encryptedData - The encrypted data as a Base64 encoded string. + * @param password - The password used to encrypt the private key. + * @returns The decrypted private key. + * @throws Throws an error if decryption fails. + * @public */ export async function kadenaDecrypt( password: BinaryLike, @@ -78,11 +82,12 @@ export async function kadenaDecrypt( /** * Changes the password of an encrypted data. * - * @param {string} privateKey - The encrypted private key as a Base64 encoded string. - * @param {BinaryLike} password - The current password used to encrypt the private key. - * @param {string} newPassword - The new password to encrypt the private key with. - * @returns {string} - The newly encrypted private key as a Base64 encoded string. - * @throws {Error} - Throws an error if the old password is empty, new password is incorrect empty passwords are empty, or if encryption with the new password fails. + * @param privateKey - The encrypted private key as a Base64 encoded string. + * @param password - The current password used to encrypt the private key. + * @param newPassword - The new password to encrypt the private key with. + * @returns The newly encrypted private key as a Base64 encoded string. + * @throws Throws an error if the old password is empty, new password is incorrect empty passwords are empty, or if encryption with the new password fails. + * @public */ export async function kadenaChangePassword( password: BinaryLike,