sol-trade-sdk 0.1.0

package/src/security/secure-key.ts

@@ -0,0 +1,303 @@
+/**
+ * Secure key storage and management for Sol Trade SDK
+ *
+ * Implements secure memory handling for private keys with:
+ * - Memory encryption at rest
+ * - Secure zeroing after use
+ * - Context manager for automatic cleanup
+ */
+
+import { Keypair, PublicKey } from '@solana/web3.js';
+import * as crypto from 'crypto';
+import * as nacl from 'tweetnacl';
+
+/**
+ * Error thrown when secure key operation fails
+ */
+export class SecureKeyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SecureKeyError';
+  }
+}
+
+/**
+ * Error thrown when trying to access a cleared key
+ */
+export class KeyNotAvailableError extends SecureKeyError {
+  constructor(message: string = 'Key not available') {
+    super(message);
+    this.name = 'KeyNotAvailableError';
+  }
+}
+
+/**
+ * Metadata about a stored key
+ */
+export interface KeyMetadata {
+  pubkey: string;
+  createdAt: number;
+  lastAccessed?: number;
+  accessCount: number;
+}
+
+/**
+ * Secure storage for Solana private keys.
+ *
+ * Features:
+ * - Keys are encrypted in memory when not in use
+ * - Automatic secure zeroing of key material
+ * - Context manager support for temporary key access
+ */
+export class SecureKeyStorage {
+  private encryptedKey: Buffer | null = null;
+  private salt: Buffer | null = null;
+  private pubkey: string | null = null;
+  private isUnlocked: boolean = false;
+  private unlockedKey: Buffer | null = null;
+  private metadata: KeyMetadata | null = null;
+  private passwordProtected: boolean = false;
+
+  private constructor() {}
+
+  /**
+   * Create secure storage from a Keypair.
+   */
+  static fromKeypair(keypair: Keypair, password?: string): SecureKeyStorage {
+    const storage = new SecureKeyStorage();
+    storage.pubkey = keypair.publicKey.toBase58();
+
+    // Get secret key bytes
+    const secretBytes = Buffer.from(keypair.secretKey);
+
+    try {
+      if (password) {
+        storage.passwordProtected = true;
+        storage.salt = crypto.randomBytes(16);
+        storage.encryptedKey = storage.encryptWithPassword(
+          secretBytes,
+          password,
+          storage.salt
+        );
+      } else {
+        // Simple XOR encryption with random key (better than plaintext)
+        storage.salt = crypto.randomBytes(64);
+        storage.encryptedKey = storage.xorEncrypt(secretBytes, storage.salt);
+      }
+
+      storage.metadata = {
+        pubkey: storage.pubkey,
+        createdAt: Date.now(),
+        accessCount: 0,
+      };
+    } finally {
+      // Always clear the secret bytes from memory
+      storage.secureZero(secretBytes);
+    }
+
+    return storage;
+  }
+
+  /**
+   * Create secure storage from a seed.
+   */
+  static fromSeed(seed: Uint8Array, password?: string): SecureKeyStorage {
+    if (seed.length !== 32) {
+      throw new SecureKeyError(`Seed must be 32 bytes, got ${seed.length}`);
+    }
+
+    const keypair = Keypair.fromSeed(seed);
+    try {
+      return SecureKeyStorage.fromKeypair(keypair, password);
+    } finally {
+      // Clear seed from memory
+      SecureKeyStorage.secureZero(Buffer.from(seed));
+    }
+  }
+
+  /**
+   * Create secure storage from a mnemonic phrase.
+   */
+  static fromMnemonic(mnemonic: string, password?: string): SecureKeyStorage {
+    // Simplified implementation - in production use proper BIP39 derivation
+    const seed = crypto
+      .pbkdf2Sync(mnemonic, 'mnemonic', 2048, 32, 'sha512');
+    const keypair = Keypair.fromSeed(seed);
+    try {
+      return SecureKeyStorage.fromKeypair(keypair, password);
+    } finally {
+      SecureKeyStorage.secureZero(seed);
+    }
+  }
+
+  private encryptWithPassword(data: Buffer, password: string, salt: Buffer): Buffer {
+    const key = crypto.pbkdf2Sync(password, salt, 100000, 32, 'sha256');
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([iv, authTag, encrypted]);
+  }
+
+  private decryptWithPassword(encryptedData: Buffer, password: string, salt: Buffer): Buffer {
+    const key = crypto.pbkdf2Sync(password, salt, 100000, 32, 'sha256');
+    const iv = encryptedData.slice(0, 16);
+    const authTag = encryptedData.slice(16, 32);
+    const encrypted = encryptedData.slice(32);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+  }
+
+  private xorEncrypt(data: Buffer, key: Buffer): Buffer {
+    const result = Buffer.alloc(data.length);
+    for (let i = 0; i < data.length; i++) {
+      const dataByte = data[i] ?? 0;
+      const keyByte = key[i % key.length] ?? 0;
+      result[i] = dataByte ^ keyByte;
+    }
+    return result;
+  }
+
+  /**
+   * Securely zero out sensitive data from memory
+   */
+  private static secureZero(data: Buffer): void {
+    // Overwrite with zeros
+    data.fill(0);
+    // Overwrite with ones
+    data.fill(0xff);
+    // Overwrite with random
+    crypto.randomFillSync(data);
+    // Final zero
+    data.fill(0);
+  }
+
+  private secureZero(data: Buffer): void {
+    SecureKeyStorage.secureZero(data);
+  }
+
+  /**
+   * Temporarily access the keypair.
+   * Key is automatically cleared after callback completes.
+   */
+  async withKeypair<T>(
+    callback: (keypair: Keypair) => Promise<T>,
+    password?: string
+  ): Promise<T> {
+    if (!this.encryptedKey) {
+      throw new KeyNotAvailableError('No key stored');
+    }
+
+    if (this.passwordProtected && !password) {
+      throw new SecureKeyError('Password required to unlock');
+    }
+
+    let decrypted: Buffer | null = null;
+
+    try {
+      // Decrypt the key
+      if (this.passwordProtected && this.salt) {
+        decrypted = this.decryptWithPassword(this.encryptedKey, password!, this.salt);
+      } else if (this.salt) {
+        decrypted = this.xorEncrypt(this.encryptedKey, this.salt);
+      } else {
+        throw new SecureKeyError('Invalid storage state');
+      }
+
+      // Create keypair from decrypted bytes
+      const keypair = Keypair.fromSeed(decrypted.slice(0, 32));
+
+      // Update metadata
+      if (this.metadata) {
+        this.metadata.lastAccessed = Date.now();
+        this.metadata.accessCount++;
+      }
+
+      this.isUnlocked = true;
+      this.unlockedKey = decrypted;
+
+      return await callback(keypair);
+    } finally {
+      // Always cleanup
+      this.isUnlocked = false;
+      if (this.unlockedKey) {
+        this.secureZero(this.unlockedKey);
+        this.unlockedKey = null;
+      }
+      if (decrypted) {
+        this.secureZero(decrypted);
+      }
+    }
+  }
+
+  /**
+   * Sign a message without exposing the keypair.
+   */
+  async signMessage(message: Buffer | Uint8Array, password?: string): Promise<Buffer> {
+    return this.withKeypair(async (keypair) => {
+      const signature = nacl.sign.detached(Buffer.from(message), keypair.secretKey);
+      return Buffer.from(signature);
+    }, password);
+  }
+
+  /**
+   * Get the public key (safe to access)
+   */
+  getPublicKey(): string {
+    return this.pubkey || '';
+  }
+
+  /**
+   * Check if storage requires password
+   */
+  get isPasswordProtected(): boolean {
+    return this.passwordProtected;
+  }
+
+  /**
+   * Get key metadata
+   */
+  getMetadata(): KeyMetadata | null {
+    return this.metadata;
+  }
+
+  /**
+   * Permanently clear all key material
+   */
+  clear(): void {
+    if (this.encryptedKey) {
+      this.secureZero(this.encryptedKey);
+      this.encryptedKey = null;
+    }
+    if (this.salt) {
+      this.secureZero(this.salt);
+      this.salt = null;
+    }
+    if (this.unlockedKey) {
+      this.secureZero(this.unlockedKey);
+      this.unlockedKey = null;
+    }
+    this.pubkey = null;
+    this.metadata = null;
+  }
+}
+
+/**
+ * Convenience function for quick signing
+ */
+export async function signWithKeypair(
+  keypair: Keypair,
+  message: Buffer | Uint8Array,
+  clearAfter: boolean = false
+): Promise<Buffer> {
+  const signature = nacl.sign.detached(Buffer.from(message), keypair.secretKey);
+
+  if (clearAfter) {
+    // Attempt to clear sensitive data
+    const secret = Buffer.from(keypair.secretKey);
+    SecureKeyStorage['secureZero'](secret);
+  }
+
+  return Buffer.from(signature);
+}

package/src/security/validators.ts

@@ -0,0 +1,281 @@
+/**
+ * Input validators for Sol Trade SDK
+ *
+ * Provides secure input validation for:
+ * - RPC URLs
+ * - Program IDs
+ * - Amounts
+ * - Slippage values
+ */
+
+import { PublicKey } from '@solana/web3.js';
+
+/**
+ * Error thrown when input validation fails
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Known legitimate Solana program IDs
+ */
+export const KNOWN_PROGRAM_IDS: Record<string, string[]> = {
+  // PumpFun
+  pumpfun: ['6EF8rrecthR5Dkzon8Nwu78hRvfCKopJFfWcCzNfXt3D'],
+  // PumpSwap
+  pumpswap: ['pAMMBay6oceH9fJKBRdGP4LmVn7LKwEqT7dPWn1oLKs'],
+  // Raydium
+  raydium: [
+    'CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK', // CPMM
+    '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8', // AMM V4
+  ],
+  // Meteora
+  meteora: ['MERLuDFBMmsHnsBPZw2sDQZHvXFM4sPkHePSuUZnPdK'], // DAMM V2
+  // Bonk
+  bonk: ['bLGPY3zYMBUfok1bMna4jrHGG3QdhSCuLZxUx2fMMLo'],
+  // System programs
+  system: [
+    '11111111111111111111111111111111', // System Program
+    'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', // Token Program
+    'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb', // Token-2022
+    'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL', // Associated Token
+  ],
+};
+
+// Base58 character set
+const BASE58_CHARS = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const BASE58_REGEX = /^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/;
+
+// Private IP patterns
+const PRIVATE_IP_PATTERNS = [
+  /^127\./,
+  /^10\./,
+  /^172\.(1[6-9]|2[0-9]|3[01])\./,
+  /^192\.168\./,
+  /^0\./,
+  /^localhost$/i,
+];
+
+/**
+ * Validate RPC URL format and security.
+ */
+export function validateRpcUrl(url: string, allowHttp: boolean = false): string {
+  if (!url) {
+    throw new ValidationError('RPC URL cannot be empty');
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new ValidationError(`Invalid URL format: ${url}`);
+  }
+
+  // Check scheme
+  if (!['https:', 'http:'].includes(parsed.protocol)) {
+    throw new ValidationError(`Invalid URL scheme: ${parsed.protocol}. Must be http or https`);
+  }
+
+  if (parsed.protocol === 'http:' && !allowHttp) {
+    throw new ValidationError(
+      'HTTP RPC URLs are insecure. Use HTTPS or set allowHttp=true if you understand the risks'
+    );
+  }
+
+  // Check hostname
+  const hostname = parsed.hostname.toLowerCase();
+
+  // Block localhost and private IPs in production
+  for (const pattern of PRIVATE_IP_PATTERNS) {
+    if (pattern.test(hostname)) {
+      throw new ValidationError(
+        `Private IP/localhost RPC URLs are not allowed for security: ${hostname}`
+      );
+    }
+  }
+
+  // Check port
+  if (parsed.port) {
+    const port = parseInt(parsed.port, 10);
+    if (port < 1 || port > 65535) {
+      throw new ValidationError(`Invalid port number: ${port}`);
+    }
+  }
+
+  // Reconstruct clean URL
+  let cleanUrl = `${parsed.protocol}//${parsed.hostname}`;
+  if (parsed.port) {
+    cleanUrl += `:${parsed.port}`;
+  }
+  if (parsed.pathname && parsed.pathname !== '/') {
+    cleanUrl += parsed.pathname;
+  }
+
+  return cleanUrl;
+}
+
+/**
+ * Validate a Solana program ID.
+ */
+export function validateProgramId(programId: string, expectedProgram?: string): string {
+  if (!programId) {
+    throw new ValidationError('Program ID cannot be empty');
+  }
+
+  // Check base58 format
+  if (!BASE58_REGEX.test(programId)) {
+    throw new ValidationError(`Invalid base58 characters in program ID: ${programId}`);
+  }
+
+  // Check length
+  if (programId.length < 32 || programId.length > 48) {
+    throw new ValidationError(`Invalid program ID length: ${programId.length} (expected 32-48)`);
+  }
+
+  // Verify against known program IDs if expected
+  if (expectedProgram) {
+    const expectedIds = KNOWN_PROGRAM_IDS[expectedProgram.toLowerCase()];
+    if (expectedIds && !expectedIds.includes(programId)) {
+      throw new ValidationError(
+        `Program ID ${programId} does not match known ${expectedProgram} program IDs. ` +
+          `Expected one of: ${expectedIds.slice(0, 3).join(', ')}`
+      );
+    }
+  }
+
+  return programId;
+}
+
+/**
+ * Validate an amount value.
+ */
+export function validateAmount(
+  amount: number | bigint,
+  name: string = 'amount',
+  allowZero: boolean = false
+): bigint {
+  const bigAmount = typeof amount === 'bigint' ? amount : BigInt(amount);
+
+  if (bigAmount < BigInt(0)) {
+    throw new ValidationError(`${name} cannot be negative: ${amount}`);
+  }
+
+  if (bigAmount === BigInt(0) && !allowZero) {
+    throw new ValidationError(`${name} cannot be zero`);
+  }
+
+  // Check for reasonable upper bound
+  const maxSafe = BigInt('9223372036854775807'); // Max i64
+  if (bigAmount > maxSafe) {
+    throw new ValidationError(`${name} exceeds maximum safe value: ${amount} > ${maxSafe}`);
+  }
+
+  return bigAmount;
+}
+
+/**
+ * Validate slippage in basis points.
+ */
+export function validateSlippage(slippageBasisPoints: number): number {
+  if (!Number.isInteger(slippageBasisPoints)) {
+    throw new ValidationError(`Slippage must be an integer, got ${typeof slippageBasisPoints}`);
+  }
+
+  if (slippageBasisPoints < 0) {
+    throw new ValidationError(`Slippage cannot be negative: ${slippageBasisPoints}`);
+  }
+
+  if (slippageBasisPoints > 10000) {
+    throw new ValidationError(
+      `Slippage cannot exceed 10000 basis points (100%), got ${slippageBasisPoints}`
+    );
+  }
+
+  // Warn on high slippage
+  if (slippageBasisPoints > 1000) {
+    console.warn(
+      `High slippage detected: ${slippageBasisPoints} bp (${slippageBasisPoints / 100}%). ` +
+        'This may result in significant price impact.'
+    );
+  }
+
+  return slippageBasisPoints;
+}
+
+/**
+ * Validate a Solana public key.
+ */
+export function validatePubkey(pubkey: string | PublicKey, name: string = 'pubkey'): PublicKey {
+  if (!pubkey) {
+    throw new ValidationError(`${name} cannot be empty`);
+  }
+
+  const pubkeyStr = typeof pubkey === 'string' ? pubkey : pubkey.toBase58();
+
+  // Check base58 format
+  if (!BASE58_REGEX.test(pubkeyStr)) {
+    throw new ValidationError(`Invalid base58 characters in ${name}: ${pubkeyStr}`);
+  }
+
+  // Check length
+  if (pubkeyStr.length < 32 || pubkeyStr.length > 48) {
+    throw new ValidationError(`Invalid ${name} length: ${pubkeyStr.length} (expected 32-48)`);
+  }
+
+  try {
+    return new PublicKey(pubkeyStr);
+  } catch (error) {
+    throw new ValidationError(`Invalid ${name}: ${pubkeyStr} - ${error}`);
+  }
+}
+
+/**
+ * Validate a trading pair.
+ */
+export function validateMintPair(inputMint: string, outputMint: string): void {
+  validatePubkey(inputMint, 'input_mint');
+  validatePubkey(outputMint, 'output_mint');
+
+  if (inputMint === outputMint) {
+    throw new ValidationError('Input and output mint cannot be the same');
+  }
+}
+
+/**
+ * Validate transaction size.
+ */
+export function validateTransactionSize(transactionBytes: Buffer | Uint8Array, maxSize: number = 1232): void {
+  if (!(transactionBytes instanceof Buffer) && !(transactionBytes instanceof Uint8Array)) {
+    throw new ValidationError(`Transaction must be bytes, got ${typeof transactionBytes}`);
+  }
+
+  if (transactionBytes.length > maxSize) {
+    throw new ValidationError(
+      `Transaction size ${transactionBytes.length} exceeds maximum ${maxSize} bytes`
+    );
+  }
+}
+
+/**
+ * Validate a signature string.
+ */
+export function validateSignature(signature: string): string {
+  if (!signature) {
+    throw new ValidationError('Signature cannot be empty');
+  }
+
+  // Signatures are 64 bytes = ~88 base58 chars
+  if (!BASE58_REGEX.test(signature)) {
+    throw new ValidationError(`Invalid base58 characters in signature: ${signature}`);
+  }
+
+  if (signature.length < 80 || signature.length > 96) {
+    throw new ValidationError(`Invalid signature length: ${signature.length}`);
+  }
+
+  return signature;
+}