@opendatalabs/vana-sdk/dist/platform/interface.cjs.map

A TypeScript library for interacting with Vana Network smart contracts.

{"version":3,"sources":["../../src/platform/interface.ts"],"sourcesContent":["/**\n * Defines platform abstraction interfaces for environment-specific implementations.\n *\n * @remarks\n * This module provides the contract for platform-specific operations, allowing\n * the SDK to work seamlessly across Node.js and browser environments. Platform\n * adapters handle all environment-specific dependencies including cryptography,\n * HTTP requests, caching, and PGP operations.\n *\n * The SDK automatically selects the appropriate adapter based on the runtime\n * environment. Custom implementations can be provided for specialized use cases.\n *\n * **Implementation Context:**\n * - Node.js: Uses native crypto modules, in-memory cache, and full OpenPGP support\n * - Browser: Uses Web Crypto API, sessionStorage cache, and browser-compatible libraries\n * - SSR: Automatically selects appropriate implementation based on runtime detection\n *\n * @example\n * ```typescript\n * // Custom platform adapter implementation\n * class CustomPlatformAdapter implements VanaPlatformAdapter {\n *   crypto = new CustomCryptoAdapter();\n *   pgp = new CustomPGPAdapter();\n *   http = new CustomHttpAdapter();\n *   cache = new CustomCacheAdapter();\n *   platform = 'browser' as const;\n * }\n *\n * // Use with SDK\n * const client = createClient({\n *   platformAdapter: new CustomPlatformAdapter()\n * });\n * ```\n *\n * @category Platform\n * @module platform/interface\n */\n\n/**\n * Identifies the runtime platform for adapter selection.\n *\n * @remarks\n * Used for debugging, telemetry, and conditional logic based on\n * the execution environment.\n *\n * @category Platform\n */\nexport type PlatformType = \"node\" | \"browser\";\n\n/**\n * Provides platform-specific cryptographic operations.\n *\n * @remarks\n * Implements ECIES encryption/decryption, key generation, and password-based\n * encryption using platform-appropriate libraries. Node.js uses Buffer-based\n * libraries while browser uses Uint8Array and Web Crypto where possible.\n *\n * @category Platform\n */\nexport interface VanaCryptoAdapter {\n  /**\n   * Encrypts data with a public key using ECIES.\n   *\n   * @remarks\n   * Uses Elliptic Curve Integrated Encryption Scheme (ECIES) for\n   * asymmetric encryption. The implementation varies by platform but\n   * maintains compatible output format.\n   *\n   * @param data - The plaintext data to encrypt.\n   *   Typically user data or encryption keys.\n   * @param publicKey - The recipient's public key in hex format.\n   *   Can be compressed or uncompressed secp256k1 key.\n   * @returns Hex-encoded encrypted data containing IV, ephemeral key, ciphertext, and MAC\n   *\n   * @example\n   * ```typescript\n   * const encrypted = await adapter.crypto.encryptWithPublicKey(\n   *   'sensitive data',\n   *   '04abcd...' // 65-byte uncompressed public key\n   * );\n   * ```\n   */\n  encryptWithPublicKey(data: string, publicKey: string): Promise<string>;\n\n  /**\n   * Decrypts ECIES-encrypted data with a private key.\n   *\n   * @param encryptedData - Hex-encoded encrypted data.\n   *   Must contain IV, ephemeral key, ciphertext, and MAC.\n   * @param privateKey - The private key in hex format.\n   *   Must correspond to the public key used for encryption.\n   * @returns The decrypted plaintext string\n   *\n   * @throws {Error} If decryption or MAC verification fails\n   */\n  decryptWithPrivateKey(\n    encryptedData: string,\n    privateKey: string,\n  ): Promise<string>;\n\n  /**\n   * Generates a new secp256k1 key pair.\n   *\n   * @returns Object with hex-encoded keys\n   * @returns returns.publicKey - Compressed public key in hex\n   * @returns returns.privateKey - Private key in hex\n   *\n   * @example\n   * ```typescript\n   * const { publicKey, privateKey } = await adapter.crypto.generateKeyPair();\n   * console.log('Public key:', publicKey); // 33 bytes compressed\n   * ```\n   */\n  generateKeyPair(): Promise<{ publicKey: string; privateKey: string }>;\n\n  /**\n   * Encrypts data with an Ethereum wallet's public key.\n   *\n   * @remarks\n   * Specifically designed for wallet-based encryption where the public\n   * key comes from an Ethereum wallet. Handles key format conversion\n   * and uses ECIES for encryption.\n   *\n   * @param data - The plaintext data to encrypt.\n   *   Typically permission grants or metadata.\n   * @param publicKey - The wallet's public key.\n   *   Accepts compressed/uncompressed, with/without 0x prefix.\n   * @returns Hex-encoded encrypted data\n   *\n   * @example\n   * ```typescript\n   * const encrypted = await adapter.crypto.encryptWithWalletPublicKey(\n   *   JSON.stringify({ permission: 'read' }),\n   *   walletPublicKey\n   * );\n   * ```\n   */\n  encryptWithWalletPublicKey(data: string, publicKey: string): Promise<string>;\n\n  /**\n   * Decrypts data with an Ethereum wallet's private key.\n   *\n   * @param encryptedData - Hex-encoded encrypted data.\n   *   Must be encrypted with corresponding wallet public key.\n   * @param privateKey - The wallet's private key.\n   *   Handle with extreme care - never log or store.\n   * @returns The decrypted plaintext string\n   *\n   * @throws {Error} If decryption fails or key is invalid\n   */\n  decryptWithWalletPrivateKey(\n    encryptedData: string,\n    privateKey: string,\n  ): Promise<string>;\n\n  /**\n   * Encrypts binary data with password-based encryption.\n   *\n   * @remarks\n   * Uses OpenPGP password-based encryption with automatic salt\n   * generation. Often used with wallet signatures as passwords for\n   * deterministic key derivation.\n   *\n   * @param data - Binary data to encrypt.\n   *   Typically file contents or serialized data.\n   * @param password - Password for encryption.\n   *   Often derived from wallet signatures.\n   * @returns Encrypted data as Uint8Array\n   *\n   * @example\n   * ```typescript\n   * const fileData = new Uint8Array([1, 2, 3, 4]);\n   * const encrypted = await adapter.crypto.encryptWithPassword(\n   *   fileData,\n   *   walletSignature\n   * );\n   * ```\n   */\n  encryptWithPassword(data: Uint8Array, password: string): Promise<Uint8Array>;\n\n  /**\n   * Decrypts password-encrypted binary data.\n   *\n   * @param encryptedData - Password-encrypted data.\n   *   Must be encrypted with the same password.\n   * @param password - Password for decryption.\n   *   Must match the encryption password exactly.\n   * @returns Decrypted data as Uint8Array\n   *\n   * @throws {Error} If decryption fails or password is incorrect\n   */\n  decryptWithPassword(\n    encryptedData: Uint8Array,\n    password: string,\n  ): Promise<Uint8Array>;\n}\n\n/**\n * Provides platform-specific PGP operations.\n *\n * @remarks\n * Implements PGP encryption, decryption, and key generation using\n * OpenPGP.js with platform-appropriate configuration. Node.js uses\n * optimizations like zlib compression.\n *\n * @category Platform\n */\nexport interface VanaPGPAdapter {\n  /**\n   * Encrypts data using PGP public key encryption.\n   *\n   * @param data - The plaintext data to encrypt.\n   *   Typically messages or structured data.\n   * @param publicKey - ASCII-armored PGP public key.\n   *   Obtain from generateKeyPair or key servers.\n   * @returns ASCII-armored encrypted message\n   *\n   * @example\n   * ```typescript\n   * const encrypted = await adapter.pgp.encrypt(\n   *   'secret message',\n   *   armoredPublicKey\n   * );\n   * ```\n   */\n  encrypt(data: string, publicKey: string): Promise<string>;\n\n  /**\n   * Decrypts PGP-encrypted data.\n   *\n   * @param encryptedData - ASCII-armored encrypted message.\n   *   Must be encrypted with corresponding public key.\n   * @param privateKey - ASCII-armored PGP private key.\n   *   May be passphrase-protected.\n   * @returns The decrypted plaintext string\n   *\n   * @throws {Error} If decryption fails or key is invalid\n   */\n  decrypt(encryptedData: string, privateKey: string): Promise<string>;\n\n  /**\n   * Generates a new PGP key pair.\n   *\n   * @param options - Key generation configuration\n   * @param options.name - Identity name.\n   *   Defaults to 'Vana User'.\n   * @param options.email - Identity email.\n   *   Defaults to 'user@vana.com'.\n   * @param options.passphrase - Private key passphrase.\n   *   If omitted, private key is unprotected.\n   * @returns ASCII-armored public and private keys\n   *\n   * @example\n   * ```typescript\n   * const { publicKey, privateKey } = await adapter.pgp.generateKeyPair({\n   *   name: 'Alice Smith',\n   *   email: 'alice@example.com',\n   *   passphrase: 'secure-passphrase'\n   * });\n   * ```\n   */\n  generateKeyPair(options?: {\n    name?: string;\n    email?: string;\n    passphrase?: string;\n  }): Promise<{ publicKey: string; privateKey: string }>;\n}\n\n/**\n * Provides platform-specific HTTP operations.\n *\n * @remarks\n * Wraps the fetch API to ensure consistent behavior across\n * Node.js and browser environments.\n *\n * @category Platform\n */\nexport interface VanaHttpAdapter {\n  /**\n   * Performs an HTTP request.\n   *\n   * @param url - The URL to request.\n   *   Must be a valid HTTP/HTTPS URL.\n   * @param options - Standard fetch RequestInit options.\n   *   See MDN documentation for details.\n   * @returns Standard fetch Response object\n   *\n   * @example\n   * ```typescript\n   * const response = await adapter.http.fetch(\n   *   'https://api.vana.com/data',\n   *   { method: 'GET', headers: { 'Authorization': 'Bearer token' } }\n   * );\n   * ```\n   */\n  fetch(url: string, options?: RequestInit): Promise<Response>;\n}\n\n/**\n * Provides platform-specific caching operations.\n *\n * @remarks\n * Implements simple key-value caching with platform-appropriate storage.\n * Node.js uses in-memory Map with TTL, browser uses sessionStorage for\n * security (cleared on tab close).\n *\n * @category Platform\n */\nexport interface VanaCacheAdapter {\n  /**\n   * Retrieves a cached value.\n   *\n   * @param key - The cache key.\n   *   Should be unique per operation.\n   * @returns The cached value or null if not found/expired\n   *\n   * @example\n   * ```typescript\n   * const cachedSignature = adapter.cache.get('sig_0x123...');\n   * if (cachedSignature) {\n   *   return cachedSignature;\n   * }\n   * ```\n   */\n  get(key: string): string | null;\n\n  /**\n   * Stores a value in the cache.\n   *\n   * @param key - The cache key.\n   *   Should be unique and descriptive.\n   * @param value - The value to cache.\n   *   Typically signatures or computed results.\n   *\n   * @remarks\n   * Node.js: Cached for 2 hours with TTL\n   * Browser: Cached until tab closes (sessionStorage)\n   */\n  set(key: string, value: string): void;\n\n  /**\n   * Removes a cached value.\n   *\n   * @param key - The cache key to remove.\n   *   Use when cached data becomes invalid.\n   */\n  delete(key: string): void;\n\n  /**\n   * Clears all cached values.\n   *\n   * @remarks\n   * Use with caution as this removes all performance optimizations.\n   * Browser implementation only clears Vana-prefixed keys.\n   */\n  clear(): void;\n}\n\n/**\n * Aggregates all platform-specific adapters into a single interface.\n *\n * @remarks\n * This is the main interface for platform abstraction. Implementations\n * must provide all required adapters while maintaining consistent behavior\n * and data formats across platforms.\n *\n * **Implementation Guidelines:**\n * 1. All methods must maintain consistent behavior across platforms\n * 2. Error types and messages should be unified\n * 3. Data formats (encoding, serialization) must be identical\n * 4. Performance characteristics can vary but API must be consistent\n *\n * @example\n * ```typescript\n * // Custom implementation for specialized environment\n * class EdgePlatformAdapter implements VanaPlatformAdapter {\n *   crypto = new EdgeCryptoAdapter();\n *   pgp = new EdgePGPAdapter();\n *   http = new EdgeHttpAdapter();\n *   cache = new EdgeCacheAdapter();\n *   platform = 'browser' as const; // Edge is browser-like\n * }\n *\n * // Use with SDK\n * const client = createClient({\n *   platformAdapter: new EdgePlatformAdapter()\n * });\n * ```\n *\n * @category Platform\n */\nexport interface VanaPlatformAdapter {\n  /**\n   * Provides cryptographic operations.\n   *\n   * @remarks\n   * Handles ECIES, wallet encryption, and password-based encryption.\n   */\n  crypto: VanaCryptoAdapter;\n\n  /**\n   * Provides PGP operations.\n   *\n   * @remarks\n   * Handles PGP encryption, decryption, and key generation.\n   */\n  pgp: VanaPGPAdapter;\n\n  /**\n   * Provides HTTP operations.\n   *\n   * @remarks\n   * Wraps fetch API for consistent cross-platform behavior.\n   */\n  http: VanaHttpAdapter;\n\n  /**\n   * Provides caching operations.\n   *\n   * @remarks\n   * Platform-appropriate storage for temporary data.\n   */\n  cache: VanaCacheAdapter;\n\n  /**\n   * Identifies the platform type.\n   *\n   * @remarks\n   * Used for debugging, telemetry, and conditional logic.\n   * Must be 'node' or 'browser'.\n   */\n  readonly platform: PlatformType;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}