@sip-protocol/sdk 0.7.2 → 0.7.4

package/src/chains/solana/transfer.ts

@@ -9,9 +9,8 @@ import {
   PublicKey,
   Transaction,
   TransactionInstruction,
-  SystemProgram,
-  LAMPORTS_PER_SOL,
 } from '@solana/web3.js'
+import { ValidationError } from '../../errors'
 import {
   getAssociatedTokenAddress,
   createAssociatedTokenAccountInstruction,
@@ -75,6 +74,11 @@ import { bytesToHex } from '@noble/hashes/utils'
 export async function sendPrivateSPLTransfer(
   params: SolanaPrivateTransferParams
 ): Promise<SolanaPrivateTransferResult> {
+  // H-6 FIX: Comprehensive input validation
+  if (!params) {
+    throw new ValidationError('params is required', 'params')
+  }
+
   const {
     connection,
     sender,
@@ -85,10 +89,75 @@ export async function sendPrivateSPLTransfer(
     signTransaction,
   } = params
 
-  // Validate recipient meta-address is for Solana
+  // Validate connection
+  if (!connection) {
+    throw new ValidationError('connection is required', 'connection')
+  }
+
+  // Validate sender
+  if (!sender) {
+    throw new ValidationError('sender is required', 'sender')
+  }
+
+  // Validate senderTokenAccount
+  if (!senderTokenAccount) {
+    throw new ValidationError('senderTokenAccount is required', 'senderTokenAccount')
+  }
+
+  // Validate mint
+  if (!mint) {
+    throw new ValidationError('mint is required', 'mint')
+  }
+
+  // Validate signTransaction callback
+  if (typeof signTransaction !== 'function') {
+    throw new ValidationError('signTransaction must be a function', 'signTransaction')
+  }
+
+  // Validate amount
+  if (amount === undefined || amount === null) {
+    throw new ValidationError('amount is required', 'amount')
+  }
+  if (typeof amount !== 'bigint') {
+    throw new ValidationError('amount must be a bigint', 'amount')
+  }
+  if (amount <= 0n) {
+    throw new ValidationError('amount must be greater than 0', 'amount')
+  }
+  // Prevent unreasonably large amounts (> 2^64, which is the max for SPL tokens)
+  const MAX_SPL_AMOUNT = 2n ** 64n - 1n
+  if (amount > MAX_SPL_AMOUNT) {
+    throw new ValidationError(`amount exceeds maximum SPL token amount`, 'amount')
+  }
+
+  // Validate recipient meta-address
+  if (!recipientMetaAddress) {
+    throw new ValidationError('recipientMetaAddress is required', 'recipientMetaAddress')
+  }
   if (recipientMetaAddress.chain !== 'solana') {
-    throw new Error(
-      `Invalid chain: expected 'solana', got '${recipientMetaAddress.chain}'`
+    throw new ValidationError(
+      `Invalid chain: expected 'solana', got '${recipientMetaAddress.chain}'`,
+      'recipientMetaAddress.chain'
+    )
+  }
+  // Validate meta-address keys are present
+  if (!recipientMetaAddress.spendingKey) {
+    throw new ValidationError('recipientMetaAddress.spendingKey is required', 'recipientMetaAddress.spendingKey')
+  }
+  if (!recipientMetaAddress.viewingKey) {
+    throw new ValidationError('recipientMetaAddress.viewingKey is required', 'recipientMetaAddress.viewingKey')
+  }
+  // Validate key format (should be hex strings starting with 0x)
+  if (!recipientMetaAddress.spendingKey.startsWith('0x') || recipientMetaAddress.spendingKey.length !== 66) {
+    throw new ValidationError(
+      'recipientMetaAddress.spendingKey must be a 32-byte hex string (0x + 64 chars)',
+      'recipientMetaAddress.spendingKey'
+    )
+  }
+  if (!recipientMetaAddress.viewingKey.startsWith('0x') || recipientMetaAddress.viewingKey.length !== 66) {
+    throw new ValidationError(
+      'recipientMetaAddress.viewingKey must be a 32-byte hex string (0x + 64 chars)',
+      'recipientMetaAddress.viewingKey'
     )
   }
 

package/src/chains/solana/types.ts

@@ -5,8 +5,9 @@
  */
 
 import type { PublicKey, Connection, Transaction, VersionedTransaction } from '@solana/web3.js'
-import type { StealthMetaAddress, StealthAddress, HexString } from '@sip-protocol/types'
+import type { StealthMetaAddress, HexString } from '@sip-protocol/types'
 import type { SolanaCluster } from './constants'
+import type { SolanaRPCProvider } from './providers/interface'
 
 /**
  * Parameters for sending a private SPL token transfer
@@ -48,11 +49,19 @@ export interface SolanaPrivateTransferResult {
 
 /**
  * Parameters for scanning for incoming stealth payments
+ *
+ * @security This interface requires sensitive cryptographic keys.
+ * Never log, store in plain text, or transmit these keys insecurely.
  */
 export interface SolanaScanParams {
   /** Solana RPC connection */
   connection: Connection
-  /** Recipient's viewing private key (hex) */
+  /**
+   * Recipient's viewing private key (hex)
+   *
+   * @security SENSITIVE - This key enables scanning for incoming payments.
+   * Store securely (encrypted). Never log or expose in error messages.
+   */
   viewingPrivateKey: HexString
   /** Recipient's spending public key (hex) */
   spendingPublicKey: HexString
@@ -62,6 +71,24 @@ export interface SolanaScanParams {
   toSlot?: number
   /** Optional: Limit number of results */
   limit?: number
+  /**
+   * Optional: RPC provider for efficient asset queries
+   *
+   * When provided, uses provider.getAssetsByOwner() for token detection
+   * instead of parsing transaction logs. Recommended for production.
+   *
+   * @example
+   * ```typescript
+   * const helius = createProvider('helius', { apiKey: '...' })
+   * const payments = await scanForPayments({
+   *   connection,
+   *   provider: helius,
+   *   viewingPrivateKey,
+   *   spendingPublicKey,
+   * })
+   * ```
+   */
+  provider?: SolanaRPCProvider
 }
 
 /**
@@ -88,6 +115,10 @@ export interface SolanaScanResult {
 
 /**
  * Parameters for claiming a stealth payment
+ *
+ * @security This interface requires highly sensitive cryptographic keys.
+ * The spending private key can authorize fund transfers.
+ * Never log, store in plain text, or transmit these keys insecurely.
  */
 export interface SolanaClaimParams {
   /** Solana RPC connection */
@@ -96,9 +127,21 @@ export interface SolanaClaimParams {
   stealthAddress: string
   /** Ephemeral public key from the payment (base58) */
   ephemeralPublicKey: string
-  /** Recipient's viewing private key (hex) */
+  /**
+   * Recipient's viewing private key (hex)
+   *
+   * @security SENSITIVE - Required for stealth key derivation.
+   * Store securely (encrypted). Never log or expose in error messages.
+   */
   viewingPrivateKey: HexString
-  /** Recipient's spending private key (hex) */
+  /**
+   * Recipient's spending private key (hex)
+   *
+   * @security CRITICAL - This key can authorize fund transfers.
+   * Store with maximum security (hardware wallet, secure enclave, or encrypted storage).
+   * Never log, expose in errors, or transmit over network.
+   * Clear from memory after use when possible.
+   */
   spendingPrivateKey: HexString
   /** Destination address to send claimed funds (base58) */
   destinationAddress: string
@@ -135,6 +178,8 @@ export interface SolanaAnnouncement {
 /**
  * Parse announcement from memo string
  * Format: SIP:1:<ephemeral_pubkey_base58>:<view_tag_hex>
+ *
+ * M4 FIX: Validates view tag is exactly 1-2 hex characters (1 byte)
  */
 export function parseAnnouncement(memo: string): SolanaAnnouncement | null {
   if (!memo.startsWith('SIP:1:')) {
@@ -146,10 +191,35 @@ export function parseAnnouncement(memo: string): SolanaAnnouncement | null {
     return null
   }
 
+  const ephemeralPublicKey = parts[0]
+  const viewTag = parts[1]
+  const stealthAddress = parts[2]
+
+  // M4 FIX: Validate ephemeral public key (base58, 32-44 chars for Solana)
+  if (!ephemeralPublicKey || ephemeralPublicKey.length < 32 || ephemeralPublicKey.length > 44) {
+    return null
+  }
+
+  // M4 FIX: Validate view tag is 1-2 hex characters (represents 1 byte: 0-255)
+  if (!viewTag || viewTag.length > 2 || !/^[0-9a-fA-F]+$/.test(viewTag)) {
+    return null
+  }
+
+  // M4 FIX: Validate view tag numeric range (0-255)
+  const viewTagNum = parseInt(viewTag, 16)
+  if (viewTagNum < 0 || viewTagNum > 255) {
+    return null
+  }
+
+  // M4 FIX: Validate stealth address if provided
+  if (stealthAddress && (stealthAddress.length < 32 || stealthAddress.length > 44)) {
+    return null
+  }
+
   return {
-    ephemeralPublicKey: parts[0],
-    viewTag: parts[1],
-    stealthAddress: parts[2],
+    ephemeralPublicKey,
+    viewTag,
+    stealthAddress,
   }
 }
 

package/src/chains/solana/utils.ts

@@ -0,0 +1,110 @@
+/**
+ * Solana Shared Utilities
+ *
+ * Common utility functions used across scan.ts and webhook.ts.
+ * Extracted to reduce code duplication (L3 audit fix).
+ */
+
+import { SOLANA_TOKEN_MINTS } from './constants'
+
+/**
+ * Token balance entry from Solana transaction metadata
+ *
+ * Common interface for pre/post token balances used in both
+ * standard RPC and webhook transaction parsing.
+ */
+export interface TokenBalanceEntry {
+  accountIndex: number
+  mint: string
+  uiTokenAmount: {
+    amount: string
+    decimals: number
+  }
+}
+
+/**
+ * Result of parsing a token transfer from transaction balances
+ */
+export interface TokenTransferInfo {
+  /** Token mint address (base58) */
+  mint: string
+  /** Transfer amount in smallest unit */
+  amount: bigint
+}
+
+/**
+ * Get token symbol from mint address
+ *
+ * Looks up the token symbol for a known mint address in our registry.
+ * Returns undefined for unknown tokens.
+ *
+ * @param mint - SPL token mint address (base58)
+ * @returns Token symbol (e.g., 'USDC') or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * getTokenSymbol('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v')
+ * // => 'USDC'
+ *
+ * getTokenSymbol('unknown-mint-address')
+ * // => undefined
+ * ```
+ */
+export function getTokenSymbol(mint: string): string | undefined {
+  for (const [symbol, address] of Object.entries(SOLANA_TOKEN_MINTS)) {
+    if (address === mint) {
+      return symbol
+    }
+  }
+  return undefined
+}
+
+/**
+ * Parse token transfer info from pre/post balance changes
+ *
+ * Analyzes pre and post token balances to determine the transferred
+ * token and amount. Finds the first account with an increased balance.
+ *
+ * @param preBalances - Pre-transaction token balances
+ * @param postBalances - Post-transaction token balances
+ * @returns Token mint and amount transferred, or null if no transfer found
+ *
+ * @example
+ * ```typescript
+ * const transfer = parseTokenTransferFromBalances(
+ *   tx.meta.preTokenBalances,
+ *   tx.meta.postTokenBalances
+ * )
+ *
+ * if (transfer) {
+ *   console.log(`Received ${transfer.amount} of ${transfer.mint}`)
+ * }
+ * ```
+ */
+export function parseTokenTransferFromBalances(
+  preBalances: TokenBalanceEntry[] | undefined | null,
+  postBalances: TokenBalanceEntry[] | undefined | null
+): TokenTransferInfo | null {
+  if (!postBalances || !preBalances) {
+    return null
+  }
+
+  // Find token balance changes (account with increased balance)
+  for (const post of postBalances) {
+    const pre = preBalances.find(
+      (p) => p.accountIndex === post.accountIndex
+    )
+
+    const postAmount = BigInt(post.uiTokenAmount.amount)
+    const preAmount = pre ? BigInt(pre.uiTokenAmount.amount) : 0n
+
+    if (postAmount > preAmount) {
+      return {
+        mint: post.mint,
+        amount: postAmount - preAmount,
+      }
+    }
+  }
+
+  return null
+}