@opendatalabs/vana-sdk 0.1.0-alpha.fd33fc9 → 2.0.0

package/dist/platform/browser.d.ts

@@ -1,34 +1,184 @@
 /**
- * Browser implementation of the Vana Platform Adapter using Uint8Array
+ * Provides browser-specific implementations of platform abstraction interfaces.
  *
- * This implementation uses browser-compatible libraries and native APIs
- * without requiring Buffer or other Node.js polyfills.
+ * @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";
 /**
- * Browser implementation of crypto operations using Uint8Array
- * Supports both eccrypto-js (default) and custom ECIES implementation
+ * 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>;
 }
 /**
- * Browser implementation of PGP operations
+ * 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;
@@ -39,27 +189,97 @@ declare class BrowserPGPAdapter implements VanaPGPAdapter {
     }>;
 }
 /**
- * Browser implementation of HTTP operations using Fetch API
+ * 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>;
 }
 /**
- * Browser implementation of caching using sessionStorage for security
- * SessionStorage is cleared when the tab closes, making it more secure for signature caching
+ * 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;
 }
 /**
- * Browser implementation of the Vana Platform Adapter
+ * 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
+ * ```
  *
- * This adapter provides all platform-specific functionality for browser environments
- * without requiring any Node.js polyfills.
+ * @category Platform
  */
 export declare class BrowserPlatformAdapter implements VanaPlatformAdapter {
     readonly crypto: BrowserCryptoAdapter;

package/dist/platform/browser.js

@@ -15,6 +15,17 @@ class BrowserCryptoAdapter {
   customWalletService = new WalletKeyEncryptionService({
     eciesProvider: this.customEciesProvider
   });
+  /**
+   * 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
+   */
   async encryptWithPublicKey(data, publicKeyHex) {
     try {
       if (features.useCustomECIES) {
@@ -35,7 +46,10 @@ class BrowserCryptoAdapter {
         const eccryptojs = await getEccryptoJS();
         const cleanKey = publicKeyHex.startsWith("0x") ? publicKeyHex.slice(2) : publicKeyHex;
         const publicKeyBytes = Buffer.from(cleanKey, "hex");
-        const publicKeyBuffer = publicKeyBytes.length === 64 ? Buffer.concat([Buffer.from([4]), publicKeyBytes]) : publicKeyBytes;
+        const uncompressed = this.customEciesProvider.normalizeToUncompressed(
+          new Uint8Array(publicKeyBytes)
+        );
+        const publicKeyBuffer = Buffer.from(uncompressed);
         const message = Buffer.from(data, "utf8");
         const encrypted = await eccryptojs.encrypt(publicKeyBuffer, message);
         const result = Buffer.concat([
@@ -50,6 +64,17 @@ class BrowserCryptoAdapter {
       throw wrapCryptoError("encryptWithPublicKey", error);
     }
   }
+  /**
+   * 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
+   */
   async decryptWithPrivateKey(encryptedData, privateKeyHex) {
     try {
       if (features.useCustomECIES) {
@@ -80,6 +105,17 @@ class BrowserCryptoAdapter {
       throw wrapCryptoError("decryptWithPrivateKey", error);
     }
   }
+  /**
+   * 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
+   */
   async encryptWithWalletPublicKey(data, publicKey) {
     try {
       if (features.useCustomECIES) {
@@ -91,7 +127,10 @@ class BrowserCryptoAdapter {
         const eccryptojs = await getEccryptoJS();
         const cleanKey = publicKey.startsWith("0x") ? publicKey.slice(2) : publicKey;
         const publicKeyBytes = Buffer.from(cleanKey, "hex");
-        const publicKeyBuffer = publicKeyBytes.length === 64 ? Buffer.concat([Buffer.from([4]), publicKeyBytes]) : publicKeyBytes;
+        const uncompressed = this.customEciesProvider.normalizeToUncompressed(
+          new Uint8Array(publicKeyBytes)
+        );
+        const publicKeyBuffer = Buffer.from(uncompressed);
         const message = Buffer.from(data, "utf8");
         const encrypted = await eccryptojs.encrypt(publicKeyBuffer, message);
         const result = Buffer.concat([
@@ -106,6 +145,17 @@ class BrowserCryptoAdapter {
       throw wrapCryptoError("encryptWithWalletPublicKey", error);
     }
   }
+  /**
+   * 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
+   */
   async decryptWithWalletPrivateKey(encryptedData, privateKey) {
     try {
       if (features.useCustomECIES) {
@@ -130,6 +180,15 @@ class BrowserCryptoAdapter {
       throw wrapCryptoError("decryptWithWalletPrivateKey", error);
     }
   }
+  /**
+   * 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
+   */
   async generateKeyPair() {
     try {
       if (features.useCustomECIES) {
@@ -152,6 +211,21 @@ class BrowserCryptoAdapter {
       throw wrapCryptoError("generateKeyPair", error);
     }
   }
+  /**
+   * 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
+   */
   async encryptWithPassword(data, password) {
     try {
       const openpgp = await getOpenPGP();
@@ -166,6 +240,17 @@ class BrowserCryptoAdapter {
       throw wrapCryptoError("encryptWithPassword", error);
     }
   }
+  /**
+   * 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
+   */
   async decryptWithPassword(encryptedData, password) {
     try {
       const openpgp = await getOpenPGP();
@@ -184,6 +269,17 @@ class BrowserCryptoAdapter {
   }
 }
 class BrowserPGPAdapter {
+  /**
+   * 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
+   */
   async encrypt(data, publicKeyArmored) {
     try {
       const openpgp = await getOpenPGP();
@@ -200,6 +296,17 @@ class BrowserPGPAdapter {
       throw new Error(`PGP encryption failed: ${String(error)}`);
     }
   }
+  /**
+   * 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
+   */
   async decrypt(encryptedData, privateKeyArmored) {
     try {
       const openpgp = await getOpenPGP();
@@ -218,6 +325,20 @@ class BrowserPGPAdapter {
       throw new Error(`PGP decryption failed: ${String(error)}`);
     }
   }
+  /**
+   * 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
+   */
   async generateKeyPair(options) {
     try {
       const openpgp = await getOpenPGP();
@@ -230,12 +351,28 @@ class BrowserPGPAdapter {
   }
 }
 class BrowserHttpAdapter {
+  /**
+   * 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
+   */
   async fetch(url, options) {
     return fetch(url, options);
   }
 }
 class BrowserCacheAdapter {
   prefix = "vana_cache_";
+  /**
+   * 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) {
     try {
       if (typeof sessionStorage === "undefined") {
@@ -246,6 +383,14 @@ class BrowserCacheAdapter {
       return 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, value) {
     try {
       if (typeof sessionStorage === "undefined") {
@@ -255,6 +400,12 @@ class BrowserCacheAdapter {
     } catch {
     }
   }
+  /**
+   * Removes a specific key from the cache.
+   *
+   * @param key - The cache key to remove.
+   *   Only removes the prefixed key.
+   */
   delete(key) {
     try {
       if (typeof sessionStorage === "undefined") {
@@ -264,6 +415,13 @@ class BrowserCacheAdapter {
     } catch {
     }
   }
+  /**
+   * Clears all Vana-prefixed cache entries.
+   *
+   * @remarks
+   * Only removes entries with the 'vana_cache_' prefix,
+   * preserving other sessionStorage data.
+   */
   clear() {
     try {
       if (typeof sessionStorage === "undefined") {