micro-key-producer/bls.d.ts

Produces secure passwords & keys for WebCrypto, SSH, PGP, SLIP10, OTP and many others

/**
 * Low-level primitive from EIP2333, generates key from bytes.
 * KeyGen from {@link https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#name-keygen | the CFRG BLS signature draft}.
 * @param ikm - secret octet string
 * @param keyInfo - additional key information
 * @returns Derived BLS secret key bytes.
 * @example
 * Feed raw input keying material into the EIP-2333 keygen primitive.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { hkdfModR } from 'micro-key-producer/bls.js';
 * hkdfModR(randomBytes(32));
 * ```
 */
export declare function hkdfModR(ikm: Uint8Array, keyInfo?: Uint8Array): Uint8Array;
/**
 * Derives the EIP-2333 master secret key from a seed.
 * @param seed - Seed bytes.
 * @returns Master secret key bytes.
 * @example
 * Start from fresh entropy and derive the BLS root secret defined by EIP-2333.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { deriveMaster } from 'micro-key-producer/bls.js';
 * const seed = randomBytes(32);
 * deriveMaster(seed);
 * ```
 */
export declare function deriveMaster(seed: Uint8Array): Uint8Array;
/**
 * Derives a hardened child secret key from a parent secret key.
 * @param parentKey - Parent secret key bytes.
 * @param index - Child index.
 * @returns Child secret key bytes.
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong parent-key length or child-index range. {@link RangeError}
 * @example
 * First derive the master key, then walk one hardened child step.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { deriveChild, deriveMaster } from 'micro-key-producer/bls.js';
 * const seed = randomBytes(32);
 * deriveChild(deriveMaster(seed), 0);
 * ```
 */
export declare function deriveChild(parentKey: Uint8Array, index: number): Uint8Array;
/**
 * Derives a key by walking an EIP-2334 path from a seed.
 * @param seed - Root seed bytes.
 * @param path - Derivation path starting with `m`.
 * @returns Derived secret key bytes.
 * @throws On wrong argument types. {@link TypeError}
 * @throws On malformed derivation paths or child-index ranges. {@link RangeError}
 * @example
 * Follow a full validator derivation path directly from the seed bytes.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { deriveSeedTree } from 'micro-key-producer/bls.js';
 * const seed = randomBytes(32);
 * deriveSeedTree(seed, 'm/12381/3600/0/0');
 * ```
 */
export declare function deriveSeedTree(seed: Uint8Array, path: string): Uint8Array;
/** Supported EIP-2334 key usages. */
export declare const EIP2334_KEY_TYPES: readonly ["withdrawal", "signing"];
/** Allowed EIP-2334 key usage names. */
export type EIP2334KeyType = (typeof EIP2334_KEY_TYPES)[number];
/**
 * Derives an EIP-2334 withdrawal or signing key.
 * @param seed - Seed bytes.
 * @param type - Requested key usage.
 * @param index - Validator account index.
 * @returns Derived private key bytes and its derivation path.
 * @throws On wrong seed, key-type, or index argument types. {@link TypeError}
 * @throws On unsupported key types or validator-index ranges. {@link RangeError}
 * @example
 * Ask for either the withdrawal or signing branch and keep the returned path string.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { deriveEIP2334Key } from 'micro-key-producer/bls.js';
 * const seed = randomBytes(32);
 * deriveEIP2334Key(seed, 'signing', 0).path;
 * ```
 */
export declare function deriveEIP2334Key(seed: Uint8Array, type: EIP2334KeyType, index: number): {
    key: Uint8Array;
    path: string;
};
/**
 * Derives signing key from withdrawal key without access to seed
 * @param withdrawalKey - result of deriveEIP2334Key(seed, 'withdrawal', index)
 * @param index - Child signing index below the withdrawal key.
 * @returns same as deriveEIP2334Key(seed, 'signing', index), but without access to seed
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong withdrawal-key length or child-index range. {@link RangeError}
 * @example
 * Show that the signing branch can be reconstructed later from the withdrawal branch.
 * ```ts
 * import { deepStrictEqual } from 'node:assert';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { deriveEIP2334Key, deriveEIP2334SigningKey } from 'micro-key-producer/bls.js';
 * const seed = randomBytes(64);
 * const signing = deriveEIP2334Key(seed, 'signing', 0);
 * const withdrawal = deriveEIP2334Key(seed, 'withdrawal', 0);
 * deepStrictEqual(deriveEIP2334SigningKey(withdrawal.key), signing.key);
 * ```
 */
export declare function deriveEIP2334SigningKey(withdrawalKey: Uint8Array, index?: number): Uint8Array;
declare function normalizePassword(s: string): string;
declare const KDFS: {
    scrypt: {
        dklen: number;
        n: number;
        r: number;
        p: number;
    };
    pbkdf2: {
        dklen: number;
        c: number;
        prf: string;
    };
};
type KDFParams<T extends KDFType> = (typeof KDFS)[T];
type KDFType = keyof typeof KDFS;
/** EIP-2335 keystore JSON object. */
export type Keystore<T extends KDFType> = {
    /** Schema version. Always `4` for BLS keystores. */
    version: number;
    /** Optional human-readable description of the protected secret. */
    description?: string;
    /** Optional hex-encoded public key for validating the decrypted secret. */
    pubkey?: string;
    /** EIP-2334 derivation path or an empty string for non-derived secrets. */
    path: string;
    /** RFC 4122 v4 UUID for the keystore object. */
    uuid: string;
    /** Cipher, checksum, and KDF configuration with their serialized payloads. */
    crypto: {
        /** Key-derivation function and its serialized parameters. */
        kdf: {
            function: T;
            params: KDFParams<T> & {
                salt: string;
            };
            message: '';
        };
        /** Checksum algorithm and checksum payload used to verify decryption. */
        checksum: {
            function: 'sha256';
            params: {};
            message: string;
        };
        /** Cipher algorithm, IV, and encrypted secret payload. */
        cipher: {
            function: 'aes-128-ctr';
            params: {
                iv: string;
            };
            message: string;
        };
    };
};
declare function deriveEIP2335Key(password: string, salt: Uint8Array, kdf: KDFType): Uint8Array;
/**
 * Decrypts EIP2335 Keystore
 * NOTE: it validates publicKey if present (which mean you can use it from store if decryption is success)
 * @param store - js object
 * @param password - Password used by the keystore KDF.
 * @returns decrypted secret and optionally path
 * @throws If the keystore uses an unsupported KDF or fails checksum/public-key validation. {@link Error}
 * @example
 * Decrypt the keystore back into the original secret bytes.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { EIP2335Keystore, decryptEIP2335Keystore } from 'micro-key-producer/bls.js';
 * const ctx = new EIP2335Keystore('password', 'pbkdf2', randomBytes);
 * const store = ctx.create(randomBytes(32));
 * decryptEIP2335Keystore(store, 'password');
 * ctx.clean();
 * ```
 */
export declare function decryptEIP2335Keystore<T extends KDFType>(store: Keystore<T>, password: string): Uint8Array;
/**
 * Secure random-byte generator.
 * @param bytes - Number of random bytes to produce.
 * @returns Cryptographically secure random bytes.
 */
export type RandFn = (bytes: number) => Uint8Array;
/**
 * Class for generation multiple keystores with same password
 * @param password - Password used by the keystore KDF.
 * @param kdf - Key-derivation function name.
 * @param _random - Optional secure random-byte generator.
 * @example
 * Reuse one keystore context when exporting multiple derived validators with the same password.
 * ```ts
 * import { randomBytes } from '@noble/hashes/utils.js';
 * import { EIP2335Keystore } from 'micro-key-producer/bls.js';
 * const ctx = new EIP2335Keystore('password', 'pbkdf2', randomBytes);
 * const seed = randomBytes(32);
 * const stores = [0, 1].map((i) => ctx.createDerivedEIP2334(seed, 'signing', i));
 * ctx.clean();
 * ```
 */
export declare class EIP2335Keystore<T extends KDFType> {
    private destroyed;
    private readonly kdf;
    private readonly randomBytes;
    private readonly key;
    private readonly salt;
    /**
     * Creates context for EIP2335 Keystore generation
     * @param password - password
     * @param kdf - scrypt | pbkdf2
     * @param _random - Optional secure random-byte generator.
     */
    constructor(password: string, kdf: T, _random?: RandFn);
    /**
     * Creates keystore in EIP2335 format.
     * @param secret - some secret value to encrypt (usually private keys)
     * @param path - optional derivation path if secret
     * @param description - optional description of secret
     * @param pubkey - optional public key. Required if secret is private key.
     */
    create(secret: Uint8Array, path?: string, // EIP2335 allows storing not derived keys
    description?: string, pubkey?: Uint8Array): Keystore<T>;
    /**
     * Creates keystore for derived private key (based on EIP2334 seed and index)
     * @param seed - EIP2334 seed to derive from
     * @param keyType - EIP2334 key type (withdrawal/signing)
     * @param index - account index
     * @param description - optional keystore description
     */
    createDerivedEIP2334(seed: Uint8Array, keyType: EIP2334KeyType, index: number, description?: string): Keystore<T>;
    /**
     * Clean internal key material
     */
    clean(): void;
}
/**
 * Exports multiple keystore from derived seed
 * @param password - password for file encryption
 * @param kdf - scrypt | pbkdf2
 * @param seed - result of mnemonicToSeed()
 * @param keyType - signing | withdrawal
 * @param indexes - array of account indeces
 * @returns Derived keystore list for the requested indexes.
 * @throws If any requested key index is outside the supported range. {@link Error}
 * @example
 * Export several validator keystores from one mnemonic-derived seed.
 * ```ts
 * import { mnemonicToSeedSync } from '@scure/bip39';
 * import { createDerivedEIP2334Keystores } from 'micro-key-producer/bls.js';
 * const mnemonic = 'letter advice cage absurd amount doctor acoustic avoid letter advice cage above';
 * const seed = mnemonicToSeedSync(mnemonic, '');
 * createDerivedEIP2334Keystores('password', 'pbkdf2', seed, 'signing', [0, 1, 2, 3]);
 * ```
 */
export declare function createDerivedEIP2334Keystores<T extends KDFType>(password: string, kdf: T, seed: Uint8Array, keyType: EIP2334KeyType, indexes: number[]): Keystore<T>[];
export declare const _TEST: {
    normalizePassword: typeof normalizePassword;
    deriveEIP2335Key: typeof deriveEIP2335Key;
};
export {};
//# sourceMappingURL=bls.d.ts.map