@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.1.0

package/dist/platform/browser.d.ts

@@ -0,0 +1,291 @@
+/**
+ * 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. Supports
+ * both standard eccrypto and custom ECIES implementations based on feature flags.
+ *
+ * @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 either eccrypto-js or a custom ECIES implementation.
+ * Uses Uint8Array and viem utilities for browser compatibility.
+ *
+ * @internal
+ */
+declare class BrowserCryptoAdapter implements VanaCryptoAdapter {
+    private customEciesProvider;
+    private customWalletService;
+    /**
+     * 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. The adapter automatically selects
+ * appropriate cryptographic implementations based on feature flags.
+ *
+ * @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 {};