@sip-protocol/sdk 0.7.2 → 0.7.4

package/src/privacy-logger.ts

@@ -0,0 +1,191 @@
+/**
+ * Privacy-Aware Logger
+ *
+ * Provides logging utilities that automatically redact sensitive information
+ * like wallet addresses and transaction amounts to prevent privacy leaks
+ * through log aggregators or error reporting tools.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
+
+export interface PrivacyLoggerConfig {
+  prefix?: string
+  level?: LogLevel
+  productionMode?: boolean
+  output?: (level: LogLevel, message: string) => void
+  silent?: boolean
+}
+
+export interface SensitiveData {
+  address?: string
+  from?: string
+  to?: string
+  owner?: string
+  amount?: bigint | number | string
+  signature?: string
+  txHash?: string
+  [key: string]: unknown
+}
+
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+}
+
+const ADDRESS_FIELDS = new Set([
+  'address', 'from', 'to', 'owner', 'sender', 'recipient', 'wallet', 'publicKey', 'pubkey',
+])
+
+const TX_FIELDS = new Set([
+  'signature', 'txHash', 'txSignature', 'transactionHash', 'computationId',
+])
+
+export function redactAddress(address: string, chars: number = 4): string {
+  if (!address || typeof address !== 'string') return '[invalid]'
+  if (address.length <= chars * 2 + 3) return address
+  return `${address.slice(0, chars)}...${address.slice(-chars)}`
+}
+
+export function redactSignature(signature: string, chars: number = 6): string {
+  if (!signature || typeof signature !== 'string') return '[invalid]'
+  if (signature.length <= chars * 2 + 3) return signature
+  return `${signature.slice(0, chars)}...${signature.slice(-chars)}`
+}
+
+export function maskAmount(
+  amount: bigint | number | string,
+  decimals: number = 9,
+  symbol: string = ''
+): string {
+  let value: number
+  if (typeof amount === 'bigint') {
+    value = Number(amount) / 10 ** decimals
+  } else if (typeof amount === 'string') {
+    value = parseFloat(amount)
+    if (isNaN(value)) return '[hidden]'
+  } else {
+    value = amount / 10 ** decimals
+  }
+
+  let range: string
+  if (value <= 0) range = '0'
+  else if (value < 0.01) range = '<0.01'
+  else if (value < 0.1) range = '0.01-0.1'
+  else if (value < 1) range = '0.1-1'
+  else if (value < 10) range = '1-10'
+  else if (value < 100) range = '10-100'
+  else if (value < 1000) range = '100-1K'
+  else if (value < 10000) range = '1K-10K'
+  else if (value < 100000) range = '10K-100K'
+  else range = '>100K'
+
+  return symbol ? `${range} ${symbol}` : range
+}
+
+export function redactSensitiveData(
+  data: SensitiveData,
+  productionMode: boolean = false
+): Record<string, string | undefined> {
+  const result: Record<string, string | undefined> = {}
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined || value === null) {
+      result[key] = undefined
+      continue
+    }
+    if (ADDRESS_FIELDS.has(key) && typeof value === 'string') {
+      result[key] = redactAddress(value)
+      continue
+    }
+    if (TX_FIELDS.has(key) && typeof value === 'string') {
+      result[key] = redactSignature(value)
+      continue
+    }
+    if (key === 'amount' || key.toLowerCase().includes('amount')) {
+      if (typeof value === 'bigint' || typeof value === 'number' || typeof value === 'string') {
+        result[key] = productionMode ? '[hidden]' : maskAmount(value)
+      }
+      continue
+    }
+    if (typeof value === 'string') result[key] = value
+    else if (typeof value === 'number' || typeof value === 'bigint') result[key] = value.toString()
+    else if (typeof value === 'boolean') result[key] = value.toString()
+    else result[key] = '[object]'
+  }
+  return result
+}
+
+export class PrivacyLogger {
+  private config: Required<PrivacyLoggerConfig>
+
+  constructor(config: PrivacyLoggerConfig = {}) {
+    this.config = {
+      prefix: config.prefix ?? '',
+      level: config.level ?? 'info',
+      productionMode: config.productionMode ?? false,
+      silent: config.silent ?? false,
+      output: config.output ?? this.defaultOutput.bind(this),
+    }
+  }
+
+  private defaultOutput(level: LogLevel, message: string): void {
+    switch (level) {
+      case 'debug': console.debug(message); break
+      case 'info': console.info(message); break
+      case 'warn': console.warn(message); break
+      case 'error': console.error(message); break
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    if (this.config.silent) return false
+    return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[this.config.level]
+  }
+
+  private formatMessage(message: string, data?: SensitiveData): string {
+    const prefix = this.config.prefix ? `${this.config.prefix} ` : ''
+    if (!data || Object.keys(data).length === 0) return `${prefix}${message}`
+    const redacted = redactSensitiveData(data, this.config.productionMode)
+    const dataStr = Object.entries(redacted)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(' ')
+    return `${prefix}${message} ${dataStr}`
+  }
+
+  debug(message: string, data?: SensitiveData): void {
+    if (this.shouldLog('debug')) this.config.output('debug', this.formatMessage(message, data))
+  }
+
+  info(message: string, data?: SensitiveData): void {
+    if (this.shouldLog('info')) this.config.output('info', this.formatMessage(message, data))
+  }
+
+  warn(message: string, data?: SensitiveData): void {
+    if (this.shouldLog('warn')) this.config.output('warn', this.formatMessage(message, data))
+  }
+
+  error(message: string, data?: SensitiveData): void {
+    if (this.shouldLog('error')) this.config.output('error', this.formatMessage(message, data))
+  }
+
+  configure(config: Partial<PrivacyLoggerConfig>): void {
+    this.config = { ...this.config, ...config }
+  }
+
+  child(prefix: string): PrivacyLogger {
+    const childPrefix = this.config.prefix ? `${this.config.prefix}${prefix}` : prefix
+    return new PrivacyLogger({ ...this.config, prefix: childPrefix })
+  }
+}
+
+export const privacyLogger = new PrivacyLogger({ prefix: '[SIP]', level: 'warn' })
+
+export function createPrivacyLogger(
+  moduleName: string,
+  config: Partial<PrivacyLoggerConfig> = {}
+): PrivacyLogger {
+  return new PrivacyLogger({ prefix: `[${moduleName}]`, level: 'warn', ...config })
+}

package/src/production-safety.ts

@@ -0,0 +1,373 @@
+/**
+ * Production Safety Checks
+ *
+ * Runtime validation to detect development-only configurations in production.
+ * Prevents accidental localhost URLs, default credentials, and other dev-only
+ * settings from being used in production deployments.
+ *
+ * @example
+ * ```typescript
+ * import { validateProductionConfig, isProductionEnvironment } from '@sip-protocol/sdk'
+ *
+ * // Check if running in production
+ * if (isProductionEnvironment()) {
+ *   // Validate config throws if localhost URLs detected
+ *   validateProductionConfig({
+ *     rpcEndpoint: process.env.RPC_ENDPOINT,
+ *     apiUrl: process.env.API_URL,
+ *   })
+ * }
+ *
+ * // Or use assertNoLocalhost for individual URLs
+ * const endpoint = assertNoLocalhost(
+ *   process.env.RPC_ENDPOINT || 'http://localhost:8899',
+ *   'RPC_ENDPOINT'
+ * )
+ * ```
+ */
+
+// ─── Constants ──────────────────────────────────────────────────────────────────
+
+/**
+ * Patterns that indicate localhost/development URLs
+ */
+const LOCALHOST_PATTERNS = [
+  /^https?:\/\/localhost(:\d+)?/i,
+  /^https?:\/\/127\.0\.0\.1(:\d+)?/i,
+  /^https?:\/\/0\.0\.0\.0(:\d+)?/i,
+  /^https?:\/\/\[::1\](:\d+)?/i,
+  /^https?:\/\/host\.docker\.internal(:\d+)?/i,
+]
+
+/**
+ * Environment variable that can override localhost safety checks
+ */
+const ALLOW_LOCALHOST_ENV = 'SIP_ALLOW_LOCALHOST_IN_PROD'
+
+// ─── Environment Detection ──────────────────────────────────────────────────────
+
+/**
+ * Check if running in a production environment
+ *
+ * Production is detected when:
+ * - NODE_ENV === 'production'
+ * - SIP_ENV === 'production'
+ *
+ * @returns true if production environment detected
+ *
+ * @example
+ * ```typescript
+ * if (isProductionEnvironment()) {
+ *   console.log('Running in production mode')
+ * }
+ * ```
+ */
+export function isProductionEnvironment(): boolean {
+  if (typeof process === 'undefined' || !process.env) {
+    // Browser without process - check window location
+    if (typeof window !== 'undefined' && window.location) {
+      const hostname = window.location.hostname
+      // Not localhost = likely production
+      return !isLocalhostUrl(`https://${hostname}`)
+    }
+    return false
+  }
+
+  const nodeEnv = process.env.NODE_ENV?.toLowerCase()
+  const sipEnv = process.env.SIP_ENV?.toLowerCase()
+
+  return nodeEnv === 'production' || sipEnv === 'production'
+}
+
+/**
+ * Check if localhost URLs are explicitly allowed in production
+ *
+ * @returns true if SIP_ALLOW_LOCALHOST_IN_PROD=true
+ */
+export function isLocalhostAllowed(): boolean {
+  if (typeof process === 'undefined' || !process.env) {
+    return false
+  }
+  return process.env[ALLOW_LOCALHOST_ENV] === 'true'
+}
+
+// ─── URL Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if a URL points to localhost
+ *
+ * @param url - URL to check
+ * @returns true if URL is localhost
+ *
+ * @example
+ * ```typescript
+ * isLocalhostUrl('http://localhost:8899')  // true
+ * isLocalhostUrl('https://api.mainnet.solana.com')  // false
+ * ```
+ */
+export function isLocalhostUrl(url: string): boolean {
+  return LOCALHOST_PATTERNS.some((pattern) => pattern.test(url))
+}
+
+/**
+ * Result from validateProductionConfig
+ */
+export interface ProductionConfigValidationResult {
+  valid: boolean
+  errors: ProductionConfigError[]
+  warnings: ProductionConfigWarning[]
+}
+
+/**
+ * Error found during production config validation
+ */
+export interface ProductionConfigError {
+  key: string
+  value: string
+  message: string
+}
+
+/**
+ * Warning found during production config validation
+ */
+export interface ProductionConfigWarning {
+  key: string
+  message: string
+}
+
+/**
+ * Error thrown when production validation fails
+ */
+export class ProductionSafetyError extends Error {
+  constructor(
+    message: string,
+    public readonly errors: ProductionConfigError[]
+  ) {
+    super(message)
+    this.name = 'ProductionSafetyError'
+  }
+}
+
+/**
+ * Validate configuration for production safety
+ *
+ * In production mode:
+ * - Throws if any URL value contains localhost
+ * - Can be bypassed with SIP_ALLOW_LOCALHOST_IN_PROD=true
+ *
+ * In non-production mode:
+ * - Returns validation result without throwing
+ * - Logs warnings for localhost URLs
+ *
+ * @param config - Configuration object to validate (key-value pairs)
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ * @throws ProductionSafetyError if production mode and localhost URLs found
+ *
+ * @example
+ * ```typescript
+ * // Validates all URL-like values in config
+ * validateProductionConfig({
+ *   rpcEndpoint: 'http://localhost:8899',  // Error in production
+ *   apiUrl: 'https://api.example.com',     // OK
+ *   name: 'my-app',                        // Ignored (not a URL)
+ * })
+ * ```
+ */
+export function validateProductionConfig(
+  config: Record<string, unknown>,
+  options: {
+    /** Only validate these keys (defaults to all string values that look like URLs) */
+    keys?: string[]
+    /** Throw in production even if localhost allowed (for critical configs) */
+    strict?: boolean
+  } = {}
+): ProductionConfigValidationResult {
+  const isProduction = isProductionEnvironment()
+  const localhostAllowed = isLocalhostAllowed()
+  const errors: ProductionConfigError[] = []
+  const warnings: ProductionConfigWarning[] = []
+
+  // Determine which keys to validate
+  const keysToValidate = options.keys ?? Object.keys(config)
+
+  for (const key of keysToValidate) {
+    const value = config[key]
+
+    // Skip non-string values
+    if (typeof value !== 'string') {
+      continue
+    }
+
+    // Skip values that don't look like URLs
+    if (!value.startsWith('http://') && !value.startsWith('https://')) {
+      continue
+    }
+
+    // Check for localhost
+    if (isLocalhostUrl(value)) {
+      if (isProduction && !localhostAllowed) {
+        errors.push({
+          key,
+          value: maskSensitiveUrl(value),
+          message: `Localhost URL detected in production for '${key}'. Set a production URL or ${ALLOW_LOCALHOST_ENV}=true to override.`,
+        })
+      } else if (isProduction && localhostAllowed && options.strict) {
+        errors.push({
+          key,
+          value: maskSensitiveUrl(value),
+          message: `Localhost URL not allowed for '${key}' even with ${ALLOW_LOCALHOST_ENV}=true (strict mode).`,
+        })
+      } else if (isProduction) {
+        warnings.push({
+          key,
+          message: `Using localhost URL for '${key}' in production (allowed via ${ALLOW_LOCALHOST_ENV})`,
+        })
+      }
+    }
+  }
+
+  const result: ProductionConfigValidationResult = {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+
+  // Throw in production if errors found
+  if (!result.valid && isProduction) {
+    const errorMessages = errors.map((e) => `  - ${e.key}: ${e.message}`).join('\n')
+    throw new ProductionSafetyError(
+      `Production safety check failed:\n${errorMessages}`,
+      errors
+    )
+  }
+
+  return result
+}
+
+/**
+ * Assert that a URL is not localhost in production
+ *
+ * Convenience function for validating individual URLs.
+ *
+ * @param url - URL to validate
+ * @param name - Name of the config key (for error messages)
+ * @returns The URL if valid
+ * @throws ProductionSafetyError if localhost in production
+ *
+ * @example
+ * ```typescript
+ * // Throws in production if localhost
+ * const endpoint = assertNoLocalhost(
+ *   process.env.RPC_ENDPOINT || 'http://localhost:8899',
+ *   'RPC_ENDPOINT'
+ * )
+ * ```
+ */
+export function assertNoLocalhost(url: string, name: string): string {
+  validateProductionConfig({ [name]: url }, { keys: [name] })
+  return url
+}
+
+/**
+ * Get a URL with production fallback
+ *
+ * In production:
+ * - If primary is localhost, throws error
+ * - Returns primary if valid
+ *
+ * In development:
+ * - Returns primary (even if localhost)
+ *
+ * @param primary - Primary URL (may be localhost in dev)
+ * @param name - Name of the config key
+ * @returns Valid URL for the current environment
+ *
+ * @example
+ * ```typescript
+ * const rpcEndpoint = getProductionUrl(
+ *   process.env.RPC_ENDPOINT || 'http://localhost:8899',
+ *   'RPC_ENDPOINT'
+ * )
+ * ```
+ */
+export function getProductionUrl(primary: string, name: string): string {
+  if (isProductionEnvironment() && isLocalhostUrl(primary) && !isLocalhostAllowed()) {
+    throw new ProductionSafetyError(
+      `No production URL configured for '${name}'. Current value: ${maskSensitiveUrl(primary)}`,
+      [{ key: name, value: maskSensitiveUrl(primary), message: 'Localhost URL in production' }]
+    )
+  }
+  return primary
+}
+
+// ─── Utility Functions ──────────────────────────────────────────────────────────
+
+/**
+ * Mask sensitive parts of a URL for safe logging
+ *
+ * @param url - URL to mask
+ * @returns URL with credentials and API keys masked
+ */
+function maskSensitiveUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+
+    // Mask credentials
+    if (parsed.username || parsed.password) {
+      parsed.username = '***'
+      parsed.password = ''
+    }
+
+    // Mask API keys in query params
+    const sensitiveParams = ['api-key', 'apikey', 'key', 'token', 'secret']
+    for (const param of sensitiveParams) {
+      if (parsed.searchParams.has(param)) {
+        parsed.searchParams.set(param, '***')
+      }
+    }
+
+    return parsed.toString()
+  } catch {
+    // If URL parsing fails, return as-is (it's likely just localhost anyway)
+    return url
+  }
+}
+
+/**
+ * Create a production-safe configuration helper
+ *
+ * Returns a function that validates URLs and provides defaults.
+ *
+ * @param defaults - Default values for non-production environments
+ * @returns Configuration getter function
+ *
+ * @example
+ * ```typescript
+ * const getConfig = createProductionConfig({
+ *   rpcEndpoint: 'http://localhost:8899',
+ *   apiUrl: 'http://localhost:3000',
+ * })
+ *
+ * // In dev: returns localhost
+ * // In prod: throws if env vars not set
+ * const rpc = getConfig('rpcEndpoint', process.env.RPC_ENDPOINT)
+ * ```
+ */
+export function createProductionConfig<T extends Record<string, string>>(
+  defaults: T
+): <K extends keyof T>(key: K, envValue?: string) => string {
+  return <K extends keyof T>(key: K, envValue?: string): string => {
+    const value = envValue ?? defaults[key]
+
+    if (isProductionEnvironment() && (!envValue || isLocalhostUrl(value)) && !isLocalhostAllowed()) {
+      throw new ProductionSafetyError(
+        `Production configuration required for '${String(key)}'. ` +
+        `Set the environment variable or ${ALLOW_LOCALHOST_ENV}=true to use defaults.`,
+        [{ key: String(key), value: maskSensitiveUrl(value), message: 'Missing production configuration' }]
+      )
+    }
+
+    return value
+  }
+}