@sip-protocol/sdk 0.1.0 → 0.1.4

package/src/secure-memory.ts

@@ -0,0 +1,147 @@
+/**
+ * Secure Memory Utilities
+ *
+ * Provides best-effort secure memory handling for cryptographic secrets
+ * in JavaScript environments.
+ *
+ * ## What This Provides
+ * - **Explicit Cleanup**: Deterministic overwriting of sensitive buffers
+ * - **Defense in Depth**: Overwrite with random data, then zero
+ * - **API for Safe Patterns**: Helper functions for scoped secret usage
+ *
+ * ## IMPORTANT: Limitations of JavaScript Memory Cleanup
+ *
+ * JavaScript does NOT provide true secure memory guarantees. These utilities
+ * offer BEST-EFFORT cleanup only. Be aware of these fundamental limitations:
+ *
+ * 1. **Garbage Collection**: The GC may have already copied the original
+ *    data to other memory locations before you call secureWipe().
+ *
+ * 2. **JIT Compilation**: Modern JS engines may optimize away "dead" writes
+ *    or create copies in compiled code paths.
+ *
+ * 3. **Memory Swapping**: The OS may swap memory pages to disk before cleanup,
+ *    leaving secrets in swap files or hibernation images.
+ *
+ * 4. **String Interning**: If secrets pass through strings, they may be
+ *    interned and retained in the string pool.
+ *
+ * ## Recommendations for High-Security Applications
+ *
+ * For applications requiring strong memory protection:
+ * - Use hardware security modules (HSMs) for key storage
+ * - Use hardware wallets (Ledger, Trezor) for signing operations
+ * - Consider native bindings with secure memory allocators
+ * - Run in isolated environments with encrypted swap disabled
+ *
+ * This module is appropriate for:
+ * - Reducing attack surface (makes casual inspection harder)
+ * - Defense in depth (multiple security layers)
+ * - Compliance with best practices (demonstrable cleanup efforts)
+ *
+ * @see docs/security/KNOWN_LIMITATIONS.md
+ */
+
+import { randomBytes } from '@noble/hashes/utils'
+
+/**
+ * Securely wipe a buffer containing sensitive data
+ *
+ * This performs a defense-in-depth wipe:
+ * 1. Overwrite with random data (defeats simple memory scrapers)
+ * 2. Zero the buffer (standard cleanup)
+ *
+ * Note: Due to JavaScript's garbage collection and potential JIT
+ * optimizations, this cannot guarantee complete erasure. However,
+ * it provides significant improvement over leaving secrets in memory.
+ *
+ * @param buffer - The buffer to wipe (modified in place)
+ *
+ * @example
+ * ```typescript
+ * const secretKey = randomBytes(32)
+ * // ... use the key ...
+ * secureWipe(secretKey) // Clean up when done
+ * ```
+ */
+export function secureWipe(buffer: Uint8Array): void {
+  if (!buffer || buffer.length === 0) {
+    return
+  }
+
+  // Step 1: Overwrite with random data
+  // This defeats simple memory scrapers looking for zeroed patterns
+  const random = randomBytes(buffer.length)
+  buffer.set(random)
+
+  // Step 2: Zero the buffer
+  // Standard cleanup - makes the data unreadable
+  buffer.fill(0)
+}
+
+/**
+ * Execute a function with a secret buffer and ensure cleanup
+ *
+ * Provides a safer pattern for using secrets - the buffer is
+ * automatically wiped after the function completes (or throws).
+ *
+ * @param createSecret - Function to create the secret buffer
+ * @param useSecret - Function that uses the secret
+ * @returns The result of useSecret
+ *
+ * @example
+ * ```typescript
+ * const signature = await withSecureBuffer(
+ *   () => generatePrivateKey(),
+ *   async (privateKey) => {
+ *     return signMessage(message, privateKey)
+ *   }
+ * )
+ * // privateKey is automatically wiped after signing
+ * ```
+ */
+export async function withSecureBuffer<T>(
+  createSecret: () => Uint8Array,
+  useSecret: (secret: Uint8Array) => T | Promise<T>,
+): Promise<T> {
+  const secret = createSecret()
+  try {
+    return await useSecret(secret)
+  } finally {
+    secureWipe(secret)
+  }
+}
+
+/**
+ * Synchronous version of withSecureBuffer
+ *
+ * @param createSecret - Function to create the secret buffer
+ * @param useSecret - Function that uses the secret (sync)
+ * @returns The result of useSecret
+ */
+export function withSecureBufferSync<T>(
+  createSecret: () => Uint8Array,
+  useSecret: (secret: Uint8Array) => T,
+): T {
+  const secret = createSecret()
+  try {
+    return useSecret(secret)
+  } finally {
+    secureWipe(secret)
+  }
+}
+
+/**
+ * Wipe multiple buffers at once
+ *
+ * Convenience function for cleaning up multiple secrets.
+ *
+ * @param buffers - Array of buffers to wipe
+ */
+export function secureWipeAll(...buffers: (Uint8Array | undefined | null)[]): void {
+  for (const buffer of buffers) {
+    if (buffer) {
+      secureWipe(buffer)
+    }
+  }
+}

package/src/sip.ts

@@ -7,6 +7,7 @@
 import {
   PrivacyLevel,
   IntentStatus,
+  OneClickSwapStatus,
   type ShieldedIntent,
   type CreateIntentParams,
   type TrackedIntent,
@@ -14,6 +15,8 @@ import {
   type FulfillmentResult,
   type StealthMetaAddress,
   type ViewingKey,
+  type OneClickQuoteResponse,
+  type Asset,
 } from '@sip-protocol/types'
 import { IntentBuilder, createShieldedIntent, trackIntent, hasRequiredProofs } from './intent'
 import {
@@ -24,8 +27,9 @@ import {
 import { generateViewingKey, deriveViewingKey } from './privacy'
 import type { ChainId, HexString } from '@sip-protocol/types'
 import type { ProofProvider } from './proofs'
-import { ValidationError } from './errors'
+import { ValidationError, IntentError, ErrorCode } from './errors'
 import { isValidChainId } from './validation'
+import { NEARIntentsAdapter, type NEARIntentsAdapterConfig, type SwapRequest } from './adapters'
 
 /**
  * SIP SDK configuration
@@ -33,6 +37,11 @@ import { isValidChainId } from './validation'
 export interface SIPConfig {
   /** Network: mainnet or testnet */
   network: 'mainnet' | 'testnet'
+  /**
+   * Mode: 'demo' for mock data, 'production' for real NEAR Intents
+   * @default 'demo'
+   */
+  mode?: 'demo' | 'production'
   /** Default privacy level */
   defaultPrivacy?: PrivacyLevel
   /** RPC endpoints for chains */
@@ -54,6 +63,23 @@ export interface SIPConfig {
    * ```
    */
   proofProvider?: ProofProvider
+  /**
+   * NEAR Intents adapter configuration
+   *
+   * Required for production mode. Provides connection to 1Click API.
+   *
+   * @example
+   * ```typescript
+   * const sip = new SIP({
+   *   network: 'mainnet',
+   *   mode: 'production',
+   *   intentsAdapter: {
+   *     jwtToken: process.env.NEAR_INTENTS_JWT,
+   *   },
+   * })
+   * ```
+   */
+  intentsAdapter?: NEARIntentsAdapterConfig | NEARIntentsAdapter
 }
 
 /**
@@ -68,13 +94,25 @@ export interface WalletAdapter {
   signMessage(message: string): Promise<string>
   /** Sign a transaction */
   signTransaction(tx: unknown): Promise<unknown>
+  /** Send a transaction (optional) */
+  sendTransaction?(tx: unknown): Promise<string>
+}
+
+/**
+ * Extended quote with deposit info for production mode
+ */
+export interface ProductionQuote extends Quote {
+  /** Deposit address for input tokens (production mode only) */
+  depositAddress?: string
+  /** Raw 1Click quote response (production mode only) */
+  rawQuote?: OneClickQuoteResponse
 }
 
 /**
  * Main SIP SDK class
  */
 export class SIP {
-  private config: SIPConfig
+  private config: SIPConfig & { mode: 'demo' | 'production' }
   private wallet?: WalletAdapter
   private stealthKeys?: {
     metaAddress: StealthMetaAddress
@@ -82,6 +120,9 @@ export class SIP {
     viewingPrivateKey: HexString
   }
   private proofProvider?: ProofProvider
+  private intentsAdapter?: NEARIntentsAdapter
+  /** Cache of pending swaps by intent ID */
+  private pendingSwaps: Map<string, { depositAddress: string; quote: OneClickQuoteResponse }> = new Map()
 
   constructor(config: SIPConfig) {
     // Validate config
@@ -97,6 +138,14 @@ export class SIP {
       )
     }
 
+    if (config.mode !== undefined && config.mode !== 'demo' && config.mode !== 'production') {
+      throw new ValidationError(
+        `mode must be 'demo' or 'production'`,
+        'config.mode',
+        { received: config.mode }
+      )
+    }
+
     if (config.defaultPrivacy !== undefined) {
       const validLevels = ['transparent', 'shielded', 'compliant']
       if (!validLevels.includes(config.defaultPrivacy)) {
@@ -110,9 +159,51 @@ export class SIP {
 
     this.config = {
       ...config,
+      mode: config.mode ?? 'demo',
       defaultPrivacy: config.defaultPrivacy ?? PrivacyLevel.SHIELDED,
     }
     this.proofProvider = config.proofProvider
+
+    // Initialize intents adapter if provided
+    if (config.intentsAdapter) {
+      if (config.intentsAdapter instanceof NEARIntentsAdapter) {
+        this.intentsAdapter = config.intentsAdapter
+      } else {
+        this.intentsAdapter = new NEARIntentsAdapter(config.intentsAdapter)
+      }
+    }
+  }
+
+  /**
+   * Get the current mode
+   */
+  getMode(): 'demo' | 'production' {
+    return this.config.mode
+  }
+
+  /**
+   * Check if running in production mode with real NEAR Intents
+   */
+  isProductionMode(): boolean {
+    return this.config.mode === 'production' && !!this.intentsAdapter
+  }
+
+  /**
+   * Get the NEAR Intents adapter
+   */
+  getIntentsAdapter(): NEARIntentsAdapter | undefined {
+    return this.intentsAdapter
+  }
+
+  /**
+   * Set the NEAR Intents adapter
+   */
+  setIntentsAdapter(adapter: NEARIntentsAdapter | NEARIntentsAdapterConfig): void {
+    if (adapter instanceof NEARIntentsAdapter) {
+      this.intentsAdapter = adapter
+    } else {
+      this.intentsAdapter = new NEARIntentsAdapter(adapter)
+    }
   }
 
   /**
@@ -222,51 +313,65 @@ export class SIP {
   }
 
   /**
-   * Get quotes for an intent (mock implementation)
+   * Get quotes for an intent
+   *
+   * In production mode: fetches real quotes from NEAR 1Click API
+   * In demo mode: returns mock quotes for testing
+   *
+   * @param params - Intent parameters (CreateIntentParams for production, ShieldedIntent/CreateIntentParams for demo)
+   * @param recipientMetaAddress - Optional stealth meta-address for privacy modes
+   * @returns Array of quotes (with deposit info in production mode)
    */
-  async getQuotes(intent: ShieldedIntent): Promise<Quote[]> {
-    // Mock quotes for demo
-    const baseAmount = intent.minOutputAmount
+  async getQuotes(
+    params: CreateIntentParams | ShieldedIntent,
+    recipientMetaAddress?: StealthMetaAddress | string,
+  ): Promise<ProductionQuote[]> {
+    // Production mode - use real NEAR Intents
+    if (this.isProductionMode()) {
+      // Production mode requires CreateIntentParams with raw values
+      if (!('input' in params)) {
+        throw new ValidationError(
+          'Production mode requires CreateIntentParams with raw input/output values. ShieldedIntent does not expose raw values.',
+          'params'
+        )
+      }
+      return this.getQuotesProduction(params, recipientMetaAddress)
+    }
 
-    return [
-      {
-        quoteId: `quote-${Date.now()}-1`,
-        intentId: intent.intentId,
-        solverId: 'solver-1',
-        outputAmount: baseAmount + (baseAmount * 2n) / 100n, // +2%
-        estimatedTime: 30,
-        expiry: Math.floor(Date.now() / 1000) + 60,
-        fee: baseAmount / 200n, // 0.5%
-      },
-      {
-        quoteId: `quote-${Date.now()}-2`,
-        intentId: intent.intentId,
-        solverId: 'solver-2',
-        outputAmount: baseAmount + (baseAmount * 1n) / 100n, // +1%
-        estimatedTime: 15,
-        expiry: Math.floor(Date.now() / 1000) + 60,
-        fee: baseAmount / 100n, // 1%
-      },
-    ]
+    // Demo mode - return mock quotes
+    return this.getQuotesDemo(params)
   }
 
   /**
-   * Execute an intent with a selected quote (mock implementation)
+   * Execute an intent with a selected quote
+   *
+   * In production mode: initiates real swap via NEAR 1Click API
+   * In demo mode: returns mock result
+   *
+   * @param intent - The intent to execute
+   * @param quote - Selected quote from getQuotes()
+   * @param options - Execution options
+   * @returns Fulfillment result with transaction hash (when available)
    */
   async execute(
     intent: TrackedIntent,
-    quote: Quote,
+    quote: Quote | ProductionQuote,
+    options?: {
+      /** Callback when deposit is required */
+      onDepositRequired?: (depositAddress: string, amount: string) => Promise<string>
+      /** Callback for status updates */
+      onStatusUpdate?: (status: OneClickSwapStatus) => void
+      /** Timeout for waiting (ms) */
+      timeout?: number
+    },
   ): Promise<FulfillmentResult> {
-    // Mock execution
-    await new Promise((resolve) => setTimeout(resolve, 2000))
-
-    return {
-      intentId: intent.intentId,
-      status: IntentStatus.FULFILLED,
-      outputAmount: quote.outputAmount,
-      txHash: intent.privacyLevel === PrivacyLevel.TRANSPARENT ? `0x${Date.now().toString(16)}` : undefined,
-      fulfilledAt: Math.floor(Date.now() / 1000),
+    // Production mode - use real NEAR Intents
+    if (this.isProductionMode()) {
+      return this.executeProduction(intent, quote as ProductionQuote, options)
     }
+
+    // Demo mode - return mock result
+    return this.executeDemo(intent, quote)
   }
 
   /**
@@ -289,6 +394,245 @@ export class SIP {
   getNetwork(): 'mainnet' | 'testnet' {
     return this.config.network
   }
+
+  // ─── Production Mode Implementation ─────────────────────────────────────────
+
+  private async getQuotesProduction(
+    params: CreateIntentParams,
+    recipientMetaAddress?: StealthMetaAddress | string,
+  ): Promise<ProductionQuote[]> {
+    if (!this.intentsAdapter) {
+      throw new ValidationError(
+        'NEAR Intents adapter not configured. Set intentsAdapter in config for production mode.',
+        'intentsAdapter'
+      )
+    }
+
+    // For privacy modes, require stealth meta-address
+    const metaAddr = recipientMetaAddress ?? (
+      params.privacy !== PrivacyLevel.TRANSPARENT
+        ? this.stealthKeys?.metaAddress
+        : undefined
+    )
+
+    if (params.privacy !== PrivacyLevel.TRANSPARENT && !metaAddr) {
+      throw new ValidationError(
+        'Stealth meta-address required for privacy modes. Call generateStealthKeys() or provide recipientMetaAddress.',
+        'recipientMetaAddress'
+      )
+    }
+
+    // Generate a request ID for tracking
+    const requestId = `quote-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+    // Build swap request from CreateIntentParams
+    const swapRequest: SwapRequest = {
+      requestId,
+      privacyLevel: params.privacy,
+      inputAsset: params.input.asset,
+      outputAsset: params.output.asset,
+      inputAmount: params.input.amount,
+      minOutputAmount: params.output.minAmount,
+    }
+
+    try {
+      // Get quote from 1Click API
+      const prepared = await this.intentsAdapter.prepareSwap(
+        swapRequest,
+        metaAddr,
+        this.wallet?.address,
+      )
+      const rawQuote = await this.intentsAdapter.getQuote(prepared)
+
+      // Cache for execute()
+      this.pendingSwaps.set(requestId, {
+        depositAddress: rawQuote.depositAddress,
+        quote: rawQuote,
+      })
+
+      // Convert to SIP Quote format
+      const quote: ProductionQuote = {
+        quoteId: rawQuote.quoteId,
+        intentId: requestId,
+        solverId: 'near-1click',
+        outputAmount: BigInt(rawQuote.amountOut),
+        estimatedTime: rawQuote.timeEstimate,
+        expiry: Math.floor(new Date(rawQuote.deadline).getTime() / 1000),
+        fee: this.calculateFee(params.input.amount, BigInt(rawQuote.amountIn)),
+        depositAddress: rawQuote.depositAddress,
+        rawQuote,
+      }
+
+      return [quote]
+    } catch (error) {
+      // If production fails, don't fall back to demo - let the error propagate
+      throw error
+    }
+  }
+
+  private async executeProduction(
+    intent: TrackedIntent,
+    quote: ProductionQuote,
+    options?: {
+      onDepositRequired?: (depositAddress: string, amount: string) => Promise<string>
+      onStatusUpdate?: (status: OneClickSwapStatus) => void
+      timeout?: number
+    },
+  ): Promise<FulfillmentResult> {
+    if (!this.intentsAdapter) {
+      throw new ValidationError(
+        'NEAR Intents adapter not configured',
+        'intentsAdapter'
+      )
+    }
+
+    // Get deposit info from quote or cache
+    const pendingSwap = this.pendingSwaps.get(quote.intentId)
+    const depositAddress = quote.depositAddress ?? pendingSwap?.depositAddress
+    const rawQuote = quote.rawQuote ?? pendingSwap?.quote
+
+    if (!depositAddress || !rawQuote) {
+      throw new IntentError(
+        'No deposit address found. Call getQuotes() first.',
+        ErrorCode.INTENT_NOT_FOUND,
+        { intentId: intent.intentId }
+      )
+    }
+
+    // If wallet can send transactions and callback provided, handle deposit
+    let depositTxHash: string | undefined
+    if (options?.onDepositRequired) {
+      depositTxHash = await options.onDepositRequired(depositAddress, rawQuote.amountIn)
+
+      // Validate txHash format before proceeding
+      if (!depositTxHash || !this.isValidTxHash(depositTxHash)) {
+        throw new ValidationError(
+          'Invalid deposit transaction hash. Expected 0x-prefixed hex string (32-66 bytes).',
+          'depositTxHash',
+          { received: depositTxHash }
+        )
+      }
+
+      // Notify 1Click of deposit
+      await this.intentsAdapter.notifyDeposit(
+        depositAddress,
+        depositTxHash,
+      )
+    }
+
+    // Wait for completion
+    const finalStatus = await this.intentsAdapter.waitForCompletion(
+      depositAddress,
+      {
+        timeout: options?.timeout ?? 300000, // 5 minutes default
+        onStatus: (status) => options?.onStatusUpdate?.(status.status),
+      },
+    )
+
+    // Clean up cache
+    this.pendingSwaps.delete(quote.intentId)
+
+    // Convert to FulfillmentResult
+    const isSuccess = finalStatus.status === OneClickSwapStatus.SUCCESS
+    return {
+      intentId: intent.intentId,
+      status: isSuccess ? IntentStatus.FULFILLED : IntentStatus.FAILED,
+      outputAmount: quote.outputAmount,
+      txHash: finalStatus.settlementTxHash ?? depositTxHash,
+      fulfilledAt: Math.floor(Date.now() / 1000),
+      error: finalStatus.error,
+    }
+  }
+
+  private calculateFee(inputAmount: bigint, quotedInput: bigint): bigint {
+    // Fee is the difference between what we sent and what was quoted
+    if (quotedInput > inputAmount) {
+      return quotedInput - inputAmount
+    }
+    // Estimate 0.5% fee if we can't calculate
+    return inputAmount / 200n
+  }
+
+  /**
+   * Validate transaction hash format
+   *
+   * Accepts:
+   * - Ethereum-style: 0x + 64 hex chars (32 bytes)
+   * - Solana-style: base58 encoded (44-88 chars)
+   * - NEAR-style: base58 or hex with varying lengths
+   */
+  private isValidTxHash(txHash: string): boolean {
+    if (!txHash || typeof txHash !== 'string') {
+      return false
+    }
+
+    // Check for 0x-prefixed hex (Ethereum, etc.)
+    if (txHash.startsWith('0x')) {
+      const hex = txHash.slice(2)
+      // Valid hex, 32-66 bytes (64-132 chars)
+      return /^[0-9a-fA-F]{64,132}$/.test(hex)
+    }
+
+    // Base58 (Solana, NEAR)
+    if (/^[1-9A-HJ-NP-Za-km-z]{32,88}$/.test(txHash)) {
+      return true
+    }
+
+    return false
+  }
+
+  // ─── Demo Mode Implementation ───────────────────────────────────────────────
+
+  private async getQuotesDemo(params: CreateIntentParams | ShieldedIntent): Promise<ProductionQuote[]> {
+    // Extract base amount depending on type
+    const baseAmount = 'input' in params
+      ? params.output.minAmount  // CreateIntentParams
+      : params.minOutputAmount   // ShieldedIntent
+
+    // Generate intentId if not present
+    const intentId = 'intentId' in params
+      ? params.intentId
+      : `demo-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+    return [
+      {
+        quoteId: `quote-${Date.now()}-1`,
+        intentId,
+        solverId: 'demo-solver-1',
+        outputAmount: baseAmount + (baseAmount * 2n) / 100n, // +2%
+        estimatedTime: 30,
+        expiry: Math.floor(Date.now() / 1000) + 60,
+        fee: baseAmount / 200n, // 0.5%
+      },
+      {
+        quoteId: `quote-${Date.now()}-2`,
+        intentId,
+        solverId: 'demo-solver-2',
+        outputAmount: baseAmount + (baseAmount * 1n) / 100n, // +1%
+        estimatedTime: 15,
+        expiry: Math.floor(Date.now() / 1000) + 60,
+        fee: baseAmount / 100n, // 1%
+      },
+    ]
+  }
+
+  private async executeDemo(
+    intent: TrackedIntent,
+    quote: Quote,
+  ): Promise<FulfillmentResult> {
+    // Simulate execution delay
+    await new Promise((resolve) => setTimeout(resolve, 2000))
+
+    return {
+      intentId: intent.intentId,
+      status: IntentStatus.FULFILLED,
+      outputAmount: quote.outputAmount,
+      txHash: intent.privacyLevel === PrivacyLevel.TRANSPARENT
+        ? `0x${Date.now().toString(16)}`
+        : undefined,
+      fulfilledAt: Math.floor(Date.now() / 1000),
+    }
+  }
 }
 
 /**
@@ -297,3 +641,21 @@ export class SIP {
 export function createSIP(network: 'mainnet' | 'testnet' = 'testnet'): SIP {
   return new SIP({ network })
 }
+
+/**
+ * Create a new SIP instance configured for production
+ */
+export function createProductionSIP(config: {
+  network: 'mainnet' | 'testnet'
+  jwtToken?: string
+  proofProvider?: ProofProvider
+}): SIP {
+  return new SIP({
+    network: config.network,
+    mode: 'production',
+    proofProvider: config.proofProvider,
+    intentsAdapter: {
+      jwtToken: config.jwtToken,
+    },
+  })
+}