@opendatalabs/vana-sdk/dist/crypto/ecies/base.d.ts

A TypeScript library for interacting with Vana Network smart contracts.

import type { ECIESProvider, ECIESEncrypted } from "./interface";
/**
 * Provides shared ECIES encryption logic across platforms using Uint8Array.
 *
 * @remarks
 * Platform implementations extend this class and provide crypto primitives.
 * The base class handles the ECIES protocol flow while maintaining
 * compatibility with the eccrypto data format.
 *
 * **Implementation details:**
 * - KDF: SHA-512(shared_secret) → encKey (32B) || macKey (32B)
 * - Cipher: AES-256-CBC with random 16-byte IV
 * - MAC: HMAC-SHA256(macKey, iv || ephemPublicKey || ciphertext)
 *
 * @category Cryptography
 */
export declare abstract class BaseECIESUint8 implements ECIESProvider {
    private static readonly validatedKeys;
    /**
     * Generates cryptographically secure random bytes.
     *
     * @param length - Number of random bytes to generate.
     * @returns Random bytes array.
     */
    protected abstract generateRandomBytes(length: number): Uint8Array;
    /**
     * Verifies a private key is valid for secp256k1.
     *
     * @param privateKey - Private key to verify (32 bytes).
     * @returns `true` if valid private key.
     */
    protected abstract verifyPrivateKey(privateKey: Uint8Array): boolean;
    /**
     * Creates a public key from a private key.
     *
     * @param privateKey - Source private key (32 bytes).
     * @param compressed - Generate compressed (33B) or uncompressed (65B) format.
     * @returns Public key or `null` if creation failed.
     */
    protected abstract createPublicKey(privateKey: Uint8Array, compressed: boolean): Uint8Array | null;
    /**
     * Validates a public key on the secp256k1 curve.
     *
     * @param publicKey - Public key to validate.
     * @returns `true` if valid public key.
     */
    protected abstract validatePublicKey(publicKey: Uint8Array): boolean;
    /**
     * Decompresses a compressed public key.
     *
     * @param publicKey - Compressed public key (33 bytes).
     * @returns Uncompressed public key (65 bytes) or `null` if decompression failed.
     */
    protected abstract decompressPublicKey(publicKey: Uint8Array): Uint8Array | null;
    /**
     * Performs ECDH key agreement.
     *
     * @param publicKey - Other party's public key.
     * @param privateKey - Your private key.
     * @returns Raw X coordinate of shared point (32 bytes).
     */
    protected abstract performECDH(publicKey: Uint8Array, privateKey: Uint8Array): Uint8Array;
    /**
     * Computes SHA-512 hash.
     *
     * @param data - Data to hash.
     * @returns SHA-512 hash (64 bytes).
     */
    protected abstract sha512(data: Uint8Array): Uint8Array;
    /**
     * Computes HMAC-SHA256 authentication tag.
     *
     * @param key - HMAC key.
     * @param data - Data to authenticate.
     * @returns HMAC-SHA256 (32 bytes).
     */
    protected abstract hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
    /**
     * Encrypts data using AES-256-CBC.
     *
     * @param key - Encryption key (32 bytes).
     * @param iv - Initialization vector (16 bytes).
     * @param plaintext - Data to encrypt.
     * @returns Ciphertext with PKCS#7 padding.
     */
    protected abstract aesEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
    /**
     * Decrypts data using AES-256-CBC.
     *
     * @param key - Decryption key (32 bytes).
     * @param iv - Initialization vector (16 bytes).
     * @param ciphertext - Data to decrypt.
     * @returns Plaintext with padding removed.
     */
    protected abstract aesDecrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
    /**
     * Normalizes a public key to uncompressed format.
     *
     * @param publicKey - Public key in any format.
     * @returns Uncompressed public key (65 bytes).
     * @throws {ECIESError} If key format is invalid.
     */
    protected normalizePublicKey(publicKey: Uint8Array): Uint8Array;
    /**
     * Normalizes a public key to uncompressed format (65 bytes with 0x04 prefix).
     * Must be implemented by derived classes to handle platform-specific operations.
     *
     * @param publicKey - The public key to normalize
     * @returns The normalized uncompressed public key
     */
    abstract normalizeToUncompressed(publicKey: Uint8Array): Uint8Array;
    /**
     * Encrypts data using ECIES.
     *
     * @param publicKey - The recipient's public key (compressed or uncompressed)
     * @param message - The data to encrypt
     * @returns Promise resolving to encrypted data structure
     */
    encrypt(publicKey: Uint8Array, message: Uint8Array): Promise<ECIESEncrypted>;
    /**
     * Decrypts ECIES encrypted data.
     *
     * @param privateKey - The recipient's private key (32 bytes)
     * @param encrypted - The encrypted data structure from encrypt()
     * @returns Promise resolving to the original plaintext
     */
    decrypt(privateKey: Uint8Array, encrypted: ECIESEncrypted): Promise<Uint8Array>;
    /**
     * Clears sensitive data from memory using multi-pass overwrite.
     *
     * @remarks
     * Uses multiple passes with different patterns to make it harder
     * for JIT compilers to optimize away the operation. While not
     * guaranteed in JavaScript, this is a best-effort approach to
     * clear sensitive data from memory.
     *
     * @param buffer - The buffer to clear
     */
    protected clearBuffer(buffer: Uint8Array): void;
}