@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dc68f39

package/dist/crypto/ecies/constants.d.cts

@@ -1,122 +0,0 @@
-/**
- * ECIES Constants and Format Specification
- *
- * These constants define the eccrypto-compatible ECIES format used throughout the SDK.
- * Maintaining these exact values ensures backward compatibility with data encrypted
- * using the original eccrypto library.
- */
-/**
- * Elliptic curve parameters
- */
-declare const CURVE: {
-    /** The elliptic curve used (secp256k1 - same as Bitcoin/Ethereum) */
-    readonly name: "secp256k1";
-    /** Private key length in bytes */
-    readonly PRIVATE_KEY_LENGTH: 32;
-    /** Compressed public key length in bytes (0x02 or 0x03 prefix + 32 bytes) */
-    readonly COMPRESSED_PUBLIC_KEY_LENGTH: 33;
-    /** Uncompressed public key length in bytes (0x04 prefix + 64 bytes) */
-    readonly UNCOMPRESSED_PUBLIC_KEY_LENGTH: 65;
-    /** ECDH shared secret X coordinate length */
-    readonly SHARED_SECRET_LENGTH: 32;
-    /** Public key prefixes */
-    readonly PREFIX: {
-        /** Uncompressed public key prefix */
-        readonly UNCOMPRESSED: 4;
-        /** Compressed public key prefix for even Y */
-        readonly COMPRESSED_EVEN: 2;
-        /** Compressed public key prefix for odd Y */
-        readonly COMPRESSED_ODD: 3;
-    };
-    /** X coordinate starts at byte 1 (after prefix) */
-    readonly X_COORDINATE_OFFSET: 1;
-    /** X coordinate ends at byte 33 (1 + 32) */
-    readonly X_COORDINATE_END: 33;
-};
-/**
- * Symmetric encryption parameters (AES-256-CBC)
- */
-declare const CIPHER: {
-    /** Cipher algorithm - must match eccrypto */
-    readonly algorithm: "aes-256-cbc";
-    /** AES key length in bytes */
-    readonly KEY_LENGTH: 32;
-    /** Initialization vector length in bytes */
-    readonly IV_LENGTH: 16;
-    /** Block size for AES */
-    readonly BLOCK_SIZE: 16;
-};
-/**
- * Key derivation function parameters
- */
-declare const KDF: {
-    /** Hash algorithm for key derivation - must match eccrypto */
-    readonly algorithm: "sha512";
-    /** Output length of SHA-512 in bytes */
-    readonly OUTPUT_LENGTH: 64;
-    /** Encryption key slice (first 32 bytes of KDF output) */
-    readonly ENCRYPTION_KEY_OFFSET: 0;
-    readonly ENCRYPTION_KEY_LENGTH: 32;
-    /** MAC key slice (last 32 bytes of KDF output) */
-    readonly MAC_KEY_OFFSET: 32;
-    readonly MAC_KEY_LENGTH: 32;
-};
-/**
- * Message authentication code parameters
- */
-declare const MAC: {
-    /** MAC algorithm - must match eccrypto */
-    readonly algorithm: "sha256";
-    /** HMAC-SHA256 output length in bytes */
-    readonly LENGTH: 32;
-};
-/**
- * ECIES encrypted data format offsets and lengths
- * Format: [iv(16)][ephemPublicKey(65)][ciphertext(variable)][mac(32)]
- */
-declare const FORMAT: {
-    /** Offsets for each component in serialized format */
-    readonly IV_OFFSET: 0;
-    readonly IV_LENGTH: 16;
-    /** Ephemeral public key (always uncompressed in eccrypto format) */
-    readonly EPHEMERAL_KEY_OFFSET: 16;
-    readonly EPHEMERAL_KEY_LENGTH: 65;
-    /** Ciphertext starts after IV and ephemeral key */
-    readonly CIPHERTEXT_OFFSET: number;
-    /** MAC is always the last 32 bytes */
-    readonly MAC_LENGTH: 32;
-    /** Minimum size of encrypted data (IV + ephemKey + MAC, no ciphertext) */
-    readonly MIN_ENCRYPTED_LENGTH: number;
-    /**
-     * Helper to calculate total length of encrypted data
-     *
-     * @param ciphertextLength - Length of the ciphertext portion
-     * @returns Total length including all components
-     */
-    readonly getTotalLength: (ciphertextLength: number) => number;
-};
-/**
- * Security constants for data clearing
- */
-declare const SECURITY: {
-    /** Overwrite patterns for secure data clearing */
-    readonly CLEAR_PATTERNS: {
-        readonly ZEROS: 0;
-        readonly ONES: 255;
-        /** Pattern multiplier for third pass */
-        readonly PATTERN_MULTIPLIER: 7;
-        /** Pattern offset for third pass */
-        readonly PATTERN_OFFSET: 13;
-    };
-};
-/**
- * Validation helpers
- */
-declare const VALIDATION: {
-    readonly isValidPrivateKey: (key: Uint8Array) => boolean;
-    readonly isValidPublicKey: (key: Uint8Array) => boolean;
-    readonly isCompressedPublicKey: (key: Uint8Array) => boolean;
-    readonly isUncompressedPublicKey: (key: Uint8Array) => boolean;
-};
-
-export { CIPHER, CURVE, FORMAT, KDF, MAC, SECURITY, VALIDATION };

package/dist/crypto/ecies/index.d.cts

@@ -1 +0,0 @@
-export { ECIESEncrypted, ECIESError, ECIESOptions, ECIESProvider, deserializeECIES, isECIESEncrypted, serializeECIES } from './interface.cjs';

package/dist/crypto/ecies/interface.d.cts

@@ -1,176 +0,0 @@
-/**
- * ECIES (Elliptic Curve Integrated Encryption Scheme) Interface
- *
- * @remarks
- * Defines the contract for platform-specific ECIES implementations.
- * All implementations maintain compatibility with the eccrypto format to ensure
- * backward compatibility with existing encrypted data.
- *
- * **Format specification:**
- * `[iv (16 bytes)][ephemPublicKey (65 bytes)][ciphertext (variable)][mac (32 bytes)]`
- *
- * @category Cryptography
- */
-/**
- * Represents ECIES encrypted data in eccrypto-compatible format.
- *
- * @remarks
- * This structure maintains backward compatibility with data encrypted using
- * the legacy eccrypto library.
- */
-interface ECIESEncrypted {
-    /** Initialization vector (16 bytes) */
-    iv: Uint8Array;
-    /** Ephemeral public key (65 bytes uncompressed) */
-    ephemPublicKey: Uint8Array;
-    /** Encrypted data */
-    ciphertext: Uint8Array;
-    /** Message authentication code (32 bytes) */
-    mac: Uint8Array;
-}
-/**
- * Provides ECIES encryption and decryption operations.
- *
- * @remarks
- * Platform-specific implementations handle the underlying cryptographic primitives
- * while maintaining consistent data format across environments.
- *
- * @category Cryptography
- */
-interface ECIESProvider {
-    /**
-     * Encrypts data using ECIES with secp256k1.
-     *
-     * @param publicKey - Recipient's public key (65 bytes uncompressed or 33 bytes compressed).
-     *   Obtain via `vana.server.getIdentity(userAddress).public_key`.
-     * @param message - Data to encrypt.
-     * @returns Encrypted data structure compatible with eccrypto format.
-     * @throws {ECIESError} When public key is invalid.
-     *   Verify key format matches secp256k1 requirements.
-     *
-     * @example
-     * ```typescript
-     * const encrypted = await provider.encrypt(
-     *   hexToBytes(publicKey),
-     *   new TextEncoder().encode('sensitive data')
-     * );
-     * ```
-     */
-    encrypt(publicKey: Uint8Array, message: Uint8Array): Promise<ECIESEncrypted>;
-    /**
-     * Decrypts ECIES encrypted data.
-     *
-     * @param privateKey - Recipient's private key (32 bytes).
-     * @param encrypted - Encrypted data structure from `encrypt()` or legacy eccrypto.
-     * @returns Decrypted message as Uint8Array.
-     * @throws {ECIESError} When MAC verification fails.
-     *   Ensure the private key matches the public key used for encryption.
-     *
-     * @example
-     * ```typescript
-     * const decrypted = await provider.decrypt(
-     *   hexToBytes(privateKey),
-     *   encrypted
-     * );
-     * const message = new TextDecoder().decode(decrypted);
-     * ```
-     */
-    decrypt(privateKey: Uint8Array, encrypted: ECIESEncrypted): Promise<Uint8Array>;
-    /**
-     * Normalizes a public key to uncompressed format (65 bytes with 0x04 prefix).
-     *
-     * @remarks
-     * Strict policy: Only accepts properly formatted compressed (33 bytes) or
-     * uncompressed (65 bytes) public keys. Does not accept 64-byte raw coordinates
-     * to ensure data integrity and prevent masking of malformed inputs.
-     *
-     * @param publicKey - Public key in compressed or uncompressed format
-     * @returns Normalized uncompressed public key (65 bytes with 0x04 prefix)
-     * @throws {Error} When public key format is invalid, including raw coordinates (64 bytes)
-     * @throws {Error} When decompression of compressed key fails
-     *
-     * @example
-     * ```typescript
-     * // Compressed key (33 bytes)
-     * const compressed = new Uint8Array(33);
-     * compressed[0] = 0x02;
-     * const uncompressed = provider.normalizeToUncompressed(compressed);
-     * console.log(uncompressed.length); // 65
-     * console.log(uncompressed[0]); // 0x04
-     *
-     * // Already uncompressed (65 bytes)
-     * const already = provider.normalizeToUncompressed(uncompressedKey);
-     * console.log(already === uncompressedKey); // true (returns same reference)
-     *
-     * // Raw coordinates rejected (64 bytes)
-     * const raw = new Uint8Array(64);
-     * provider.normalizeToUncompressed(raw); // Throws error
-     * ```
-     */
-    normalizeToUncompressed(publicKey: Uint8Array): Uint8Array;
-}
-/**
- * Configures ECIES operation behavior.
- */
-interface ECIESOptions {
-    /** Use compressed public keys (33 bytes) instead of uncompressed (65 bytes) */
-    useCompressed?: boolean;
-}
-/**
- * Represents failures in ECIES cryptographic operations.
- *
- * @remarks
- * Provides specific error codes to help identify and recover from
- * different failure scenarios.
- *
- * @category Errors
- */
-declare class ECIESError extends Error {
-    readonly code: "INVALID_KEY" | "ENCRYPTION_FAILED" | "DECRYPTION_FAILED" | "MAC_MISMATCH" | "ECDH_FAILED";
-    readonly cause?: Error | undefined;
-    constructor(message: string, code: "INVALID_KEY" | "ENCRYPTION_FAILED" | "DECRYPTION_FAILED" | "MAC_MISMATCH" | "ECDH_FAILED", cause?: Error | undefined);
-}
-/**
- * Validates if an object conforms to the ECIESEncrypted structure.
- *
- * @param obj - Object to validate.
- * @returns `true` if object is a valid ECIESEncrypted structure.
- *
- * @example
- * ```typescript
- * if (isECIESEncrypted(data)) {
- *   const decrypted = await provider.decrypt(privateKey, data);
- * }
- * ```
- */
-declare function isECIESEncrypted(obj: unknown): obj is ECIESEncrypted;
-/**
- * Serializes ECIESEncrypted to hex string for storage or transmission.
- *
- * @param encrypted - Encrypted data structure from `encrypt()`.
- * @returns Hex string representation.
- *
- * @example
- * ```typescript
- * const hexString = serializeECIES(encrypted);
- * // Store hexString in database or send over network
- * ```
- */
-declare function serializeECIES(encrypted: ECIESEncrypted): string;
-/**
- * Deserializes hex string to ECIESEncrypted structure.
- *
- * @param hex - Hex string from `serializeECIES()` or storage.
- * @returns ECIESEncrypted structure ready for decryption.
- * @throws {ECIESError} When hex string format is invalid.
- *   Verify the hex string is complete and uncorrupted.
- *
- * @example
- * ```typescript
- * const encrypted = deserializeECIES(hexString);
- * const decrypted = await provider.decrypt(privateKey, encrypted);
- * ```
- */
-declare function deserializeECIES(hex: string): ECIESEncrypted;
-
-export { type ECIESEncrypted, ECIESError, type ECIESOptions, type ECIESProvider, deserializeECIES, isECIESEncrypted, serializeECIES };

package/dist/crypto/ecies/node.d.cts

@@ -1,50 +0,0 @@
-import { BaseECIESUint8 } from './base.cjs';
-import './interface.cjs';
-
-/**
- * Node.js implementation of ECIES using native secp256k1 for performance
- *
- * @remarks
- * Uses native secp256k1 bindings for all elliptic curve operations.
- * Uses Node.js crypto module for hashing and AES operations.
- * Provides Uint8Array-only interface with no Buffer exposure.
- */
-
-/**
- * Node.js-specific ECIES provider using native secp256k1
- *
- * @remarks
- * This implementation:
- * - Uses native secp256k1 for all EC operations (optimal performance)
- * - Uses Node.js crypto for SHA-512, HMAC, and AES operations
- * - Internally works with Uint8Array
- * - Only uses Buffer at crypto API boundaries
- */
-declare class NodeECIESUint8Provider extends BaseECIESUint8 {
-    private readonly identityHashFn;
-    protected generateRandomBytes(length: number): Uint8Array;
-    protected verifyPrivateKey(privateKey: Uint8Array): boolean;
-    protected createPublicKey(privateKey: Uint8Array, compressed: boolean): Uint8Array | null;
-    protected validatePublicKey(publicKey: Uint8Array): boolean;
-    protected decompressPublicKey(publicKey: Uint8Array): Uint8Array | null;
-    protected performECDH(publicKey: Uint8Array, privateKey: Uint8Array): Uint8Array;
-    protected sha512(data: Uint8Array): Uint8Array;
-    protected hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
-    protected aesEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
-    protected aesDecrypt(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
-    /**
-     * Normalizes a public key to uncompressed format (65 bytes with 0x04 prefix).
-     * Handles compressed (33 bytes) and uncompressed (65 bytes) formats only.
-     *
-     * @remarks
-     * Strict policy: Does not accept 64-byte raw coordinates to avoid masking
-     * malformed data. Callers must provide properly formatted keys.
-     *
-     * @param publicKey - The public key to normalize (33 or 65 bytes)
-     * @returns The normalized uncompressed public key (65 bytes)
-     * @throws {Error} When public key format is invalid or decompression fails
-     */
-    normalizeToUncompressed(publicKey: Uint8Array): Uint8Array;
-}
-
-export { NodeECIESUint8Provider };

package/dist/crypto/ecies/utils.d.cts

@@ -1,67 +0,0 @@
-/**
- * Utility functions for ECIES operations
- *
- * Provides conversion utilities between different data formats
- * to bridge platform-specific implementations.
- */
-/**
- * Converts a hex string to Uint8Array
- *
- * @param hex - Hex string to convert
- * @returns Uint8Array representation of the hex string
- */
-declare function hexToBytes(hex: string): Uint8Array;
-/**
- * Converts Uint8Array to hex string
- *
- * @param bytes - Bytes to convert to hex
- * @returns Hex string representation
- */
-declare function bytesToHex(bytes: Uint8Array): string;
-/**
- * Converts a string to Uint8Array using UTF-8 encoding
- *
- * @param str - String to convert
- * @returns UTF-8 encoded bytes
- */
-declare function stringToBytes(str: string): Uint8Array;
-/**
- * Converts Uint8Array to string using UTF-8 decoding
- *
- * @param bytes - Bytes to decode
- * @returns Decoded UTF-8 string
- */
-declare function bytesToString(bytes: Uint8Array): string;
-/**
- * Concatenates multiple Uint8Arrays into one
- *
- * @param arrays - Arrays to concatenate
- * @returns Concatenated Uint8Array
- */
-declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;
-/**
- * Checks if two Uint8Arrays are equal in constant time
- *
- * @param a - First array to compare
- * @param b - Second array to compare
- * @returns `true` if arrays are equal
- */
-declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
-/**
- * Converts Buffer to Uint8Array (for Node.js compatibility layer)
- * In browser, this is a no-op if already Uint8Array
- *
- * @param buffer - Buffer or Uint8Array to convert
- * @returns Uint8Array representation
- */
-declare function bufferToBytes(buffer: Buffer | Uint8Array): Uint8Array;
-/**
- * Converts Uint8Array to Buffer (for Node.js compatibility layer)
- * Only available in Node.js environment
- *
- * @param bytes - Uint8Array to convert to Buffer
- * @returns Buffer representation
- */
-declare function bytesToBuffer(bytes: Uint8Array): Buffer;
-
-export { bufferToBytes, bytesToBuffer, bytesToHex, bytesToString, concatBytes, constantTimeEqual, hexToBytes, stringToBytes };

package/dist/crypto/services/WalletKeyEncryptionService.d.cts

@@ -1,92 +0,0 @@
-import { ECIESProvider, ECIESEncrypted } from '../ecies/interface.cjs';
-
-/**
- * Service for wallet key encryption and decryption operations.
- *
- * @remarks
- * This service separates business logic (wallet key processing) from crypto primitives
- * (ECIES operations). It handles key normalization, data conversion, and format transformation
- * while delegating actual cryptographic operations to the provided ECIES provider.
- *
- * @category Cryptography
- * @internal
- */
-
-interface WalletKeyEncryptionServiceConfig {
-    /** ECIES provider for encryption/decryption */
-    eciesProvider: ECIESProvider;
-}
-/**
- * Service for wallet key encryption and decryption operations
- *
- * @remarks
- * This service encapsulates the business logic for wallet key operations,
- * delegating actual cryptographic operations to the provided ECIES provider.
- * It handles key normalization, data conversion, and format transformation.
- *
- * @internal
- */
-declare class WalletKeyEncryptionService {
-    private readonly eciesProvider;
-    constructor(config: WalletKeyEncryptionServiceConfig);
-    /**
-     * Encrypts data using a wallet's public key.
-     *
-     * @param data - The plaintext message to encrypt for the wallet owner.
-     * @param publicKey - The recipient wallet's public key for encryption.
-     * @returns A promise that resolves to the encrypted data as a hex string.
-     * @throws {Error} When encryption fails due to invalid key format.
-     *
-     * @example
-     * ```typescript
-     * const encrypted = await processor.encryptWithWalletPublicKey(
-     *   "Secret message",
-     *   "0x04..." // 65-byte uncompressed public key
-     * );
-     * console.log(`Encrypted: ${encrypted}`);
-     * ```
-     */
-    encryptWithWalletPublicKey(data: string, publicKey: string | Uint8Array): Promise<string>;
-    /**
-     * Decrypts data using a wallet's private key.
-     *
-     * @param encryptedData - The hex-encoded encrypted data to decrypt.
-     * @param privateKey - The wallet's private key for decryption.
-     * @returns A promise that resolves to the decrypted plaintext message.
-     * @throws {Error} When decryption fails due to invalid data or key format.
-     *
-     * @example
-     * ```typescript
-     * const decrypted = await processor.decryptWithWalletPrivateKey(
-     *   encryptedHexString,
-     *   "0x..." // 32-byte private key
-     * );
-     * console.log(`Decrypted: ${decrypted}`);
-     * ```
-     */
-    decryptWithWalletPrivateKey(encryptedData: string, privateKey: string | Uint8Array): Promise<string>;
-    /**
-     * Encrypts a Uint8Array with a wallet public key
-     *
-     * @param data - Binary data to encrypt
-     * @param publicKey - Public key as hex string or Uint8Array
-     * @returns Encrypted data structure
-     */
-    encryptBinary(data: Uint8Array, publicKey: string | Uint8Array): Promise<ECIESEncrypted>;
-    /**
-     * Decrypts to a Uint8Array with a wallet private key
-     *
-     * @param encrypted - Encrypted data structure
-     * @param privateKey - Private key as hex string or Uint8Array
-     * @returns Decrypted binary data
-     */
-    decryptBinary(encrypted: ECIESEncrypted, privateKey: string | Uint8Array): Promise<Uint8Array>;
-    /**
-     * Gets the underlying ECIES provider
-     *
-     * @returns The ECIES provider instance
-     */
-    getECIESProvider(): ECIESProvider;
-}
-
-export { WalletKeyEncryptionService, type WalletKeyEncryptionServiceConfig };

package/dist/diagnostics.d.cts

@@ -1,26 +0,0 @@
-/**
- * Provides diagnostic warnings for SDK configuration and environment issues.
- *
- * @remarks
- * Warnings are deduplicated by message and can be silenced via
- * the VANA_SDK_SILENCE_WARNINGS environment variable.
- *
- * @category Diagnostics
- */
-/**
- * Emits a warning message once per unique message content.
- *
- * @remarks
- * Warnings are automatically prefixed with "[vana-sdk]" and deduplicated.
- * Set `VANA_SDK_SILENCE_WARNINGS=1` to disable all warnings.
- *
- * @param msg - Warning message components to display.
- *
- * @example
- * ```typescript
- * warnOnce("AES-256-CBC not available.", "ECIES will fail.");
- * ```
- */
-declare function warnOnce(...msg: unknown[]): void;
-
-export { warnOnce };