wallet-storage-client/out/src/sdk/PrivilegedKeyManager.d.ts

Client only Wallet Storage

import { PrivateKey, CreateHmacArgs, CreateHmacResult, CreateSignatureArgs, CreateSignatureResult, GetPublicKeyArgs, PubKeyHex, RevealCounterpartyKeyLinkageArgs, RevealCounterpartyKeyLinkageResult, RevealSpecificKeyLinkageArgs, RevealSpecificKeyLinkageResult, VerifyHmacArgs, VerifyHmacResult, VerifySignatureArgs, VerifySignatureResult, WalletDecryptArgs, WalletDecryptResult, WalletEncryptArgs, WalletEncryptResult } from '@bsv/sdk';
/**
 * PrivilegedKeyManager
 *
 * This class manages a privileged (i.e., very sensitive) private key, obtained from
 * an external function (`keyGetter`), which might be backed by HSMs, secure enclaves,
 * or other secure storage. The manager retains the key in memory only for a limited
 * duration (`retentionPeriod`), uses XOR-based chunk-splitting obfuscation, and
 * includes decoy data to raise the difficulty of discovering the real key in memory.
 *
 * IMPORTANT: While these measures raise the bar for attackers, JavaScript environments
 * do not provide perfect in-memory secrecy.
 */
export declare class PrivilegedKeyManager {
    /**
     * Function that will retrieve the PrivateKey from a secure environment,
     * e.g., an HSM or secure enclave. The reason for key usage is passed in
     * to help with user consent, auditing, and access policy checks.
     */
    private keyGetter;
    /**
     * Time (in ms) for which the obfuscated key remains in memory
     * before being automatically destroyed.
     */
    private retentionPeriod;
    /**
     * A list of dynamically generated property names used to store
     * real key chunks (XORed with random pads).
     */
    private chunkPropNames;
    /**
     * A list of dynamically generated property names used to store
     * the random pads that correspond to the real key chunks.
     */
    private chunkPadPropNames;
    /**
     * A list of decoy property names that will be removed
     * when the real key is destroyed.
     */
    private decoyPropNamesDestroy;
    /**
     * A list of decoy property names that remain in memory
     * even after the real key is destroyed (just to cause confusion).
     */
    private decoyPropNamesRemain;
    /**
     * Handle to the timer that will remove the key from memory
     * after the retention period. If the key is refreshed again
     * within that period, the timer is cleared and re-set.
     */
    private destroyTimer;
    /**
     * Number of chunks to split the 32-byte key into.
     * Adjust to increase or decrease obfuscation complexity.
     */
    private readonly CHUNK_COUNT;
    /**
     * @param keyGetter - Asynchronous function that retrieves the PrivateKey from a secure environment.
     * @param retentionPeriod - Time in milliseconds to retain the obfuscated key in memory before zeroizing.
     */
    constructor(keyGetter: (reason: string) => Promise<PrivateKey>, retentionPeriod?: number);
    /**
     * Safely destroys the in-memory obfuscated key material by zeroizing
     * and deleting related fields. Also destroys some (but not all) decoy
     * properties to further confuse an attacker.
     */
    destroyKey(): void;
    /**
     * Re/sets the destruction timer that removes the key from memory
     * after `retentionPeriod` ms. If a timer is already running, it
     * is cleared and re-set. This ensures the key remains in memory
     * for exactly the desired window after its most recent acquisition.
     */
    private scheduleKeyDestruction;
    /**
     * XOR-based obfuscation on a per-chunk basis.
     * This function takes two equal-length byte arrays
     * and returns the XOR combination.
     */
    private xorBytes;
    /**
     * Splits the 32-byte key into `this.CHUNK_COUNT` smaller chunks
     * (mostly equal length; the last chunk picks up leftover bytes
     * if 32 is not evenly divisible).
     */
    private splitKeyIntoChunks;
    /**
     * Reassembles the chunks from the dynamic properties, XORs them
     * with their corresponding pads, and returns a single 32-byte
     * Uint8Array representing the raw key.
     */
    private reassembleKeyFromChunks;
    /**
     * Generates a random property name to store key chunks or decoy data.
     */
    private generateRandomPropName;
    /**
     * Forces a PrivateKey to be represented as exactly 32 bytes, left-padding
     * with zeros if its numeric value has fewer than 32 bytes.
     */
    private get32ByteRepresentation;
    /**
     * Returns the privileged key needed to perform cryptographic operations.
     * Uses in-memory chunk-based obfuscation if the key was already fetched.
     * Otherwise, it calls out to `keyGetter`, splits the 32-byte representation
     * of the key, XORs each chunk with a random pad, and stores them under
     * dynamic property names. Also populates new decoy properties.
     *
     * @param reason - The reason for why the key is needed, passed to keyGetter.
     * @returns The PrivateKey object needed for cryptographic operations.
     */
    private getPrivilegedKey;
    getPublicKey(args: GetPublicKeyArgs): Promise<{
        publicKey: PubKeyHex;
    }>;
    revealCounterpartyKeyLinkage(args: RevealCounterpartyKeyLinkageArgs): Promise<RevealCounterpartyKeyLinkageResult>;
    revealSpecificKeyLinkage(args: RevealSpecificKeyLinkageArgs): Promise<RevealSpecificKeyLinkageResult>;
    encrypt(args: WalletEncryptArgs): Promise<WalletEncryptResult>;
    decrypt(args: WalletDecryptArgs): Promise<WalletDecryptResult>;
    createHmac(args: CreateHmacArgs): Promise<CreateHmacResult>;
    verifyHmac(args: VerifyHmacArgs): Promise<VerifyHmacResult>;
    createSignature(args: CreateSignatureArgs): Promise<CreateSignatureResult>;
    verifySignature(args: VerifySignatureArgs): Promise<VerifySignatureResult>;
}
//# sourceMappingURL=PrivilegedKeyManager.d.ts.map