@opendatalabs/vana-sdk
Version:
A TypeScript library for interacting with Vana Network smart contracts.
292 lines (291 loc) • 10.2 kB
TypeScript
/**
* Provides browser-specific implementations of platform abstraction interfaces.
*
* @remarks
* This module implements all platform-specific operations for browser environments,
* using native Web APIs and browser-compatible libraries. It avoids Node.js-specific
* dependencies like Buffer, using Uint8Array and viem utilities instead. Uses a
* custom ECIES implementation with @noble/secp256k1 for pure JavaScript crypto.
*
* @example
* ```typescript
* // Use the browser platform adapter
* import { BrowserPlatformAdapter } from '@vana-sdk/platform/browser';
*
* const adapter = new BrowserPlatformAdapter();
*
* // Encrypt data with public key
* const encrypted = await adapter.crypto.encryptWithPublicKey(
* 'sensitive data',
* '0x04...' // Public key hex
* );
*
* // Use sessionStorage-backed cache
* adapter.cache.set('temp_key', 'cached_value');
* ```
*
* @category Platform
* @module platform/browser
*/
import type { VanaPlatformAdapter, VanaCryptoAdapter, VanaPGPAdapter, VanaHttpAdapter, VanaCacheAdapter } from "./interface";
/**
* Implements cryptographic operations for browser environments.
*
* @remarks
* Provides ECIES encryption/decryption, key generation, and password-based
* encryption using a custom ECIES implementation with @noble/secp256k1.
* Uses Uint8Array and viem utilities for browser compatibility.
*
* @internal
*/
declare class BrowserCryptoAdapter implements VanaCryptoAdapter {
private eciesProvider;
private walletService;
/**
* Encrypts data using ECIES with a public key.
*
* @param data - The plaintext string to encrypt.
* Typically user data or sensitive information.
* @param publicKeyHex - The recipient's public key in hex format.
* Can include or omit the '0x' prefix.
* @returns Encrypted data as a hex string without '0x' prefix
*
* @throws {Error} If encryption fails or public key is invalid
*/
encryptWithPublicKey(data: string, publicKeyHex: string): Promise<string>;
/**
* Decrypts ECIES-encrypted data using a private key.
*
* @param encryptedData - Hex string containing encrypted data.
* Can include or omit the '0x' prefix.
* @param privateKeyHex - The private key in hex format.
* Must correspond to the public key used for encryption.
* @returns The decrypted plaintext string
*
* @throws {Error} If decryption fails or MAC verification fails
*/
decryptWithPrivateKey(encryptedData: string, privateKeyHex: string): Promise<string>;
/**
* Encrypts data using a wallet's public key.
*
* @param data - The plaintext string to encrypt.
* Typically permission data or DLP metadata.
* @param publicKey - The wallet's public key.
* Automatically handles compressed/uncompressed formats.
* @returns Encrypted data as a hex string
*
* @throws {Error} If encryption fails or key processing fails
*/
encryptWithWalletPublicKey(data: string, publicKey: string): Promise<string>;
/**
* Decrypts data using a wallet's private key.
*
* @param encryptedData - Hex string containing encrypted data.
* Must be encrypted with corresponding wallet public key.
* @param privateKey - The wallet's private key.
* Obtain from wallet connection (handle with care).
* @returns The decrypted plaintext string
*
* @throws {Error} If decryption fails or key is invalid
*/
decryptWithWalletPrivateKey(encryptedData: string, privateKey: string): Promise<string>;
/**
* Generates a new secp256k1 key pair for ECIES operations.
*
* @returns Object containing hex-encoded public and private keys
* @returns returns.privateKey - Private key in hex format without '0x'
* @returns returns.publicKey - Compressed public key in hex format without '0x'
*
* @throws {Error} If key generation fails
*/
generateKeyPair(): Promise<{
privateKey: string;
publicKey: string;
}>;
/**
* Encrypts binary data using password-based encryption.
*
* @param data - Binary data to encrypt.
* Typically file contents or serialized objects.
* @param password - Password for encryption.
* Often derived from wallet signatures.
* @returns Encrypted data as Uint8Array
*
* @remarks
* Uses OpenPGP for password-based encryption with automatic
* salt generation for security.
*
* @throws {Error} If encryption fails
*/
encryptWithPassword(data: Uint8Array, password: string): Promise<Uint8Array>;
/**
* Decrypts password-encrypted binary data.
*
* @param encryptedData - Password-encrypted data as Uint8Array.
* Must be encrypted with the same password.
* @param password - Password for decryption.
* Must match the encryption password.
* @returns Decrypted data as Uint8Array
*
* @throws {Error} If decryption fails or password is incorrect
*/
decryptWithPassword(encryptedData: Uint8Array, password: string): Promise<Uint8Array>;
}
/**
* Implements PGP operations for browser environments.
*
* @remarks
* Provides PGP encryption, decryption, and key generation using the OpenPGP.js
* library with browser-optimized configuration.
*
* @internal
*/
declare class BrowserPGPAdapter implements VanaPGPAdapter {
/**
* Encrypts data using PGP public key encryption.
*
* @param data - The plaintext string to encrypt.
* Typically messages or structured data.
* @param publicKeyArmored - ASCII-armored PGP public key.
* Obtain from PGP key generation or key servers.
* @returns ASCII-armored encrypted message
*
* @throws {Error} If encryption fails or public key is invalid
*/
encrypt(data: string, publicKeyArmored: string): Promise<string>;
/**
* Decrypts PGP-encrypted data using a private key.
*
* @param encryptedData - ASCII-armored encrypted message.
* Must be encrypted with corresponding public key.
* @param privateKeyArmored - ASCII-armored PGP private key.
* Must correspond to the public key used for encryption.
* @returns The decrypted plaintext string
*
* @throws {Error} If decryption fails or private key is invalid
*/
decrypt(encryptedData: string, privateKeyArmored: string): Promise<string>;
/**
* Generates a new PGP key pair.
*
* @param options - Key generation options
* @param options.name - Name for the key identity.
* Defaults to 'Vana User'.
* @param options.email - Email for the key identity.
* Defaults to 'user@vana.com'.
* @param options.passphrase - Passphrase to protect the private key.
* If not provided, key is unprotected.
* @returns ASCII-armored public and private keys
*
* @throws {Error} If key generation fails
*/
generateKeyPair(options?: {
name?: string;
email?: string;
passphrase?: string;
}): Promise<{
publicKey: string;
privateKey: string;
}>;
}
/**
* Implements HTTP operations for browser environments.
*
* @remarks
* Uses the native Fetch API available in all modern browsers.
*
* @internal
*/
declare class BrowserHttpAdapter implements VanaHttpAdapter {
/**
* Performs an HTTP request using the Fetch API.
*
* @param url - The URL to fetch.
* Must be a valid HTTP/HTTPS URL.
* @param options - Standard fetch options.
* See MDN fetch documentation for details.
* @returns Standard fetch Response object
*/
fetch(url: string, options?: RequestInit): Promise<Response>;
}
/**
* Implements secure caching for browser environments.
*
* @remarks
* Uses sessionStorage for temporary caching that's automatically cleared
* when the browser tab closes. This provides better security for sensitive
* data like signatures compared to localStorage. All keys are prefixed to
* avoid conflicts with other applications.
*
* @internal
*/
declare class BrowserCacheAdapter implements VanaCacheAdapter {
private readonly prefix;
/**
* Retrieves a cached value by key.
*
* @param key - The cache key to look up.
* Automatically prefixed to avoid conflicts.
* @returns The cached value or null if not found
*/
get(key: string): string | null;
/**
* Stores a value in sessionStorage.
*
* @param key - The cache key.
* Automatically prefixed with 'vana_cache_'.
* @param value - The value to cache.
* Will be cleared when tab closes.
*/
set(key: string, value: string): void;
/**
* Removes a specific key from the cache.
*
* @param key - The cache key to remove.
* Only removes the prefixed key.
*/
delete(key: string): void;
/**
* Clears all Vana-prefixed cache entries.
*
* @remarks
* Only removes entries with the 'vana_cache_' prefix,
* preserving other sessionStorage data.
*/
clear(): void;
}
/**
* Provides complete platform abstraction for browser environments.
*
* @remarks
* This adapter aggregates all browser-specific implementations of platform
* operations. It uses native Web APIs where possible and browser-compatible
* libraries for crypto and PGP operations using a custom ECIES implementation
* with @noble/secp256k1 for pure JavaScript cryptography.
*
* @example
* ```typescript
* // Create a browser adapter instance
* const adapter = new BrowserPlatformAdapter();
*
* // All platform operations are available
* const encrypted = await adapter.crypto.encryptWithPublicKey(
* 'secret',
* publicKey
* );
*
* const response = await adapter.http.fetch('/api/data');
*
* adapter.cache.set('key', 'value'); // Uses sessionStorage
* ```
*
* @category Platform
*/
export declare class BrowserPlatformAdapter implements VanaPlatformAdapter {
readonly crypto: BrowserCryptoAdapter;
readonly pgp: BrowserPGPAdapter;
readonly http: BrowserHttpAdapter;
readonly cache: BrowserCacheAdapter;
readonly platform: "browser";
}
export {};