@sip-protocol/sdk 0.1.0

package/src/privacy.ts

@@ -0,0 +1,382 @@
+/**
+ * Privacy level handling for SIP Protocol
+ *
+ * Provides authenticated encryption using XChaCha20-Poly1305 for viewing key
+ * selective disclosure. This allows transaction details to be encrypted and
+ * later revealed to auditors holding the viewing key.
+ *
+ * ## Security Properties
+ * - **Confidentiality**: Only viewing key holders can decrypt
+ * - **Integrity**: Authentication tag prevents tampering
+ * - **Nonce-misuse resistance**: XChaCha20 uses 24-byte nonces
+ */
+
+import type {
+  PrivacyLevel,
+  ViewingKey,
+  EncryptedTransaction,
+  HexString,
+  Hash,
+} from '@sip-protocol/types'
+import { sha256 } from '@noble/hashes/sha256'
+import { sha512 } from '@noble/hashes/sha512'
+import { hmac } from '@noble/hashes/hmac'
+import { hkdf } from '@noble/hashes/hkdf'
+import { bytesToHex, hexToBytes, randomBytes, utf8ToBytes } from '@noble/hashes/utils'
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js'
+import { ValidationError, CryptoError, ErrorCode } from './errors'
+
+/**
+ * Maximum size for decrypted transaction data (1MB)
+ * Prevents DoS attacks via large payloads
+ */
+const MAX_TRANSACTION_DATA_SIZE = 1024 * 1024
+
+/**
+ * Privacy configuration for an intent
+ */
+export interface PrivacyConfig {
+  /** The privacy level */
+  level: PrivacyLevel
+  /** Viewing key (required for compliant mode) */
+  viewingKey?: ViewingKey
+  /** Whether to use stealth addresses */
+  useStealth: boolean
+  /** Whether to encrypt transaction data */
+  encryptData: boolean
+}
+
+/**
+ * Get privacy configuration for a privacy level
+ */
+export function getPrivacyConfig(
+  level: PrivacyLevel,
+  viewingKey?: ViewingKey,
+): PrivacyConfig {
+  switch (level) {
+    case 'transparent':
+      return {
+        level,
+        useStealth: false,
+        encryptData: false,
+      }
+
+    case 'shielded':
+      return {
+        level,
+        useStealth: true,
+        encryptData: true,
+      }
+
+    case 'compliant':
+      if (!viewingKey) {
+        throw new ValidationError(
+          'viewingKey is required for compliant mode',
+          'viewingKey',
+          undefined,
+          ErrorCode.MISSING_REQUIRED
+        )
+      }
+      return {
+        level,
+        viewingKey,
+        useStealth: true,
+        encryptData: true,
+      }
+
+    default:
+      throw new ValidationError(
+        `unknown privacy level: ${level}`,
+        'level',
+        { received: level },
+        ErrorCode.INVALID_PRIVACY_LEVEL
+      )
+  }
+}
+
+/**
+ * Generate a new viewing key
+ */
+export function generateViewingKey(path: string = 'm/0'): ViewingKey {
+  const keyBytes = randomBytes(32)
+  const key = `0x${bytesToHex(keyBytes)}` as HexString
+  const hashBytes = sha256(keyBytes)
+
+  return {
+    key,
+    path,
+    hash: `0x${bytesToHex(hashBytes)}` as Hash,
+  }
+}
+
+/**
+ * Derive a child viewing key using BIP32-style hierarchical derivation
+ *
+ * Uses HMAC-SHA512 for proper key derivation:
+ * - childKey = HMAC-SHA512(masterKey, childPath)
+ * - Takes first 32 bytes as the derived key
+ *
+ * This provides:
+ * - Cryptographic standard compliance (similar to BIP32)
+ * - One-way derivation (cannot derive parent from child)
+ * - Non-correlatable keys (different paths produce unrelated keys)
+ */
+export function deriveViewingKey(
+  masterKey: ViewingKey,
+  childPath: string,
+): ViewingKey {
+  // Extract raw master key bytes (remove 0x prefix if present)
+  const masterKeyHex = masterKey.key.startsWith('0x')
+    ? masterKey.key.slice(2)
+    : masterKey.key
+  const masterKeyBytes = hexToBytes(masterKeyHex)
+
+  // Encode child path as bytes
+  const childPathBytes = utf8ToBytes(childPath)
+
+  // HMAC-SHA512(key=masterKey, data=childPath)
+  // This follows BIP32-style hierarchical derivation
+  const derivedFull = hmac(sha512, masterKeyBytes, childPathBytes)
+
+  // Take first 32 bytes as the derived key (standard practice)
+  const derivedBytes = derivedFull.slice(0, 32)
+  const derived = `0x${bytesToHex(derivedBytes)}` as HexString
+
+  // Compute hash of the derived key for identification
+  const hashBytes = sha256(derivedBytes)
+
+  return {
+    key: derived,
+    path: `${masterKey.path}/${childPath}`,
+    hash: `0x${bytesToHex(hashBytes)}` as Hash,
+  }
+}
+
+// ─── Encryption Constants ─────────────────────────────────────────────────────
+
+/**
+ * Domain separation for encryption key derivation
+ */
+const ENCRYPTION_DOMAIN = 'SIP-VIEWING-KEY-ENCRYPTION-V1'
+
+/**
+ * XChaCha20-Poly1305 nonce size (24 bytes)
+ */
+const NONCE_SIZE = 24
+
+// ─── Key Derivation ───────────────────────────────────────────────────────────
+
+/**
+ * Derive an encryption key from a viewing key using HKDF
+ *
+ * Uses HKDF-SHA256 with domain separation for security.
+ *
+ * @param viewingKey - The viewing key to derive from
+ * @returns 32-byte encryption key
+ */
+function deriveEncryptionKey(viewingKey: ViewingKey): Uint8Array {
+  // Extract the raw key bytes (remove 0x prefix)
+  const keyHex = viewingKey.key.startsWith('0x')
+    ? viewingKey.key.slice(2)
+    : viewingKey.key
+  const keyBytes = hexToBytes(keyHex)
+
+  // Use HKDF to derive a proper encryption key
+  // HKDF(SHA256, ikm=viewingKey, salt=domain, info=path, length=32)
+  const salt = utf8ToBytes(ENCRYPTION_DOMAIN)
+  const info = utf8ToBytes(viewingKey.path)
+
+  return hkdf(sha256, keyBytes, salt, info, 32)
+}
+
+// ─── Transaction Data Type ────────────────────────────────────────────────────
+
+/**
+ * Transaction data that can be encrypted for viewing
+ */
+export interface TransactionData {
+  sender: string
+  recipient: string
+  amount: string
+  timestamp: number
+}
+
+// ─── Encryption Functions ─────────────────────────────────────────────────────
+
+/**
+ * Encrypt transaction data for viewing key holders
+ *
+ * Uses XChaCha20-Poly1305 authenticated encryption with:
+ * - 24-byte random nonce (nonce-misuse resistant)
+ * - HKDF-derived encryption key
+ * - 16-byte authentication tag (included in ciphertext)
+ *
+ * @param data - Transaction data to encrypt
+ * @param viewingKey - Viewing key for encryption
+ * @returns Encrypted transaction with nonce and key hash
+ *
+ * @example
+ * ```typescript
+ * const encrypted = encryptForViewing(
+ *   { sender: '0x...', recipient: '0x...', amount: '100', timestamp: 123 },
+ *   viewingKey
+ * )
+ * // encrypted.ciphertext contains the encrypted data
+ * // encrypted.nonce is needed for decryption
+ * // encrypted.viewingKeyHash identifies which key can decrypt
+ * ```
+ */
+export function encryptForViewing(
+  data: TransactionData,
+  viewingKey: ViewingKey,
+): EncryptedTransaction {
+  // Derive encryption key from viewing key
+  const key = deriveEncryptionKey(viewingKey)
+
+  // Generate random nonce (24 bytes for XChaCha20)
+  const nonce = randomBytes(NONCE_SIZE)
+
+  // Serialize data to JSON
+  const plaintext = utf8ToBytes(JSON.stringify(data))
+
+  // Encrypt with XChaCha20-Poly1305
+  const cipher = xchacha20poly1305(key, nonce)
+  const ciphertext = cipher.encrypt(plaintext)
+
+  return {
+    ciphertext: `0x${bytesToHex(ciphertext)}` as HexString,
+    nonce: `0x${bytesToHex(nonce)}` as HexString,
+    viewingKeyHash: viewingKey.hash,
+  }
+}
+
+/**
+ * Decrypt transaction data with viewing key
+ *
+ * Performs authenticated decryption using XChaCha20-Poly1305.
+ * The authentication tag is verified before returning data.
+ *
+ * @param encrypted - Encrypted transaction data
+ * @param viewingKey - Viewing key for decryption
+ * @returns Decrypted transaction data
+ * @throws {Error} If decryption fails (wrong key, tampered data, etc.)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = decryptWithViewing(encrypted, viewingKey)
+ *   console.log(`Amount: ${data.amount}`)
+ * } catch (e) {
+ *   console.error('Decryption failed - wrong key or tampered data')
+ * }
+ * ```
+ */
+export function decryptWithViewing(
+  encrypted: EncryptedTransaction,
+  viewingKey: ViewingKey,
+): TransactionData {
+  // Verify viewing key hash matches (optional but helpful error message)
+  if (encrypted.viewingKeyHash !== viewingKey.hash) {
+    throw new CryptoError(
+      'Viewing key hash mismatch - this key cannot decrypt this transaction',
+      ErrorCode.DECRYPTION_FAILED,
+      { operation: 'decryptWithViewing' }
+    )
+  }
+
+  // Derive encryption key from viewing key
+  const key = deriveEncryptionKey(viewingKey)
+
+  // Parse nonce and ciphertext
+  const nonceHex = encrypted.nonce.startsWith('0x')
+    ? encrypted.nonce.slice(2)
+    : encrypted.nonce
+  const nonce = hexToBytes(nonceHex)
+
+  const ciphertextHex = encrypted.ciphertext.startsWith('0x')
+    ? encrypted.ciphertext.slice(2)
+    : encrypted.ciphertext
+  const ciphertext = hexToBytes(ciphertextHex)
+
+  // Decrypt with XChaCha20-Poly1305
+  // This will throw if authentication fails (wrong key or tampered data)
+  const cipher = xchacha20poly1305(key, nonce)
+  let plaintext: Uint8Array
+
+  try {
+    plaintext = cipher.decrypt(ciphertext)
+  } catch (e) {
+    throw new CryptoError(
+      'Decryption failed - authentication tag verification failed. ' +
+      'Either the viewing key is incorrect or the data has been tampered with.',
+      ErrorCode.DECRYPTION_FAILED,
+      {
+        cause: e instanceof Error ? e : undefined,
+        operation: 'decryptWithViewing',
+      }
+    )
+  }
+
+  // Parse JSON
+  const textDecoder = new TextDecoder()
+  const jsonString = textDecoder.decode(plaintext)
+
+  // Validate size before parsing to prevent DoS
+  if (jsonString.length > MAX_TRANSACTION_DATA_SIZE) {
+    throw new ValidationError(
+      `decrypted data exceeds maximum size limit (${MAX_TRANSACTION_DATA_SIZE} bytes)`,
+      'transactionData',
+      { received: jsonString.length, max: MAX_TRANSACTION_DATA_SIZE },
+      ErrorCode.INVALID_INPUT
+    )
+  }
+
+  try {
+    const data = JSON.parse(jsonString) as TransactionData
+    // Validate required fields
+    if (
+      typeof data.sender !== 'string' ||
+      typeof data.recipient !== 'string' ||
+      typeof data.amount !== 'string' ||
+      typeof data.timestamp !== 'number'
+    ) {
+      throw new ValidationError(
+        'invalid transaction data format',
+        'transactionData',
+        { received: data },
+        ErrorCode.INVALID_INPUT
+      )
+    }
+    return data
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      throw new CryptoError(
+        'Decryption succeeded but data is malformed JSON',
+        ErrorCode.DECRYPTION_FAILED,
+        { cause: e, operation: 'decryptWithViewing' }
+      )
+    }
+    throw e
+  }
+}
+
+/**
+ * Validate privacy level string
+ */
+export function isValidPrivacyLevel(level: string): level is PrivacyLevel {
+  return ['transparent', 'shielded', 'compliant'].includes(level)
+}
+
+/**
+ * Get human-readable description of privacy level
+ */
+export function getPrivacyDescription(level: PrivacyLevel): string {
+  const descriptions: Record<PrivacyLevel, string> = {
+    transparent: 'Public transaction - all details visible on-chain',
+    shielded: 'Private transaction - sender, amount, and recipient hidden',
+    compliant: 'Private with audit - hidden but viewable with key',
+  }
+  return descriptions[level]
+}
+
+// hexToBytes removed - was only needed for mocked XOR encryption

package/src/proofs/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Proof Providers for SIP Protocol
+ *
+ * This module provides a pluggable interface for ZK proof generation.
+ *
+ * ## Available Providers
+ *
+ * - **MockProofProvider**: For testing only - provides NO cryptographic security
+ * - **NoirProofProvider**: Production provider using Noir circuits (coming in #14, #15, #16)
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { MockProofProvider, NoirProofProvider } from '@sip-protocol/sdk'
+ *
+ * // For testing
+ * const mockProvider = new MockProofProvider()
+ * await mockProvider.initialize()
+ *
+ * // For production (when available)
+ * const noirProvider = new NoirProofProvider()
+ * await noirProvider.initialize()
+ *
+ * // Use with SIP client
+ * const sip = new SIP({
+ *   network: 'testnet',
+ *   proofProvider: noirProvider,
+ * })
+ * ```
+ *
+ * @module proofs
+ */
+
+// Interface and types
+export type {
+  ProofProvider,
+  ProofFramework,
+  FundingProofParams,
+  ValidityProofParams,
+  FulfillmentProofParams,
+  OracleAttestation,
+  ProofResult,
+} from './interface'
+
+export { ProofGenerationError } from './interface'
+
+// Mock provider (testing only)
+export { MockProofProvider } from './mock'
+
+// Noir provider (production)
+export { NoirProofProvider } from './noir'
+export type { NoirProviderConfig } from './noir'

package/src/proofs/interface.ts

@@ -0,0 +1,228 @@
+/**
+ * Proof Provider Interface
+ *
+ * Defines a pluggable interface for ZK proof generation and verification.
+ * This allows different backends (Noir, mock for testing) to be swapped.
+ *
+ * @see docs/specs/ZK-ARCHITECTURE.md for framework decision (Noir)
+ */
+
+import type { ZKProof, Commitment, HexString } from '@sip-protocol/types'
+
+/**
+ * Supported proof framework types
+ */
+export type ProofFramework = 'noir' | 'mock'
+
+/**
+ * Parameters for generating a Funding Proof
+ *
+ * Proves: balance >= minimumRequired without revealing balance
+ *
+ * @see docs/specs/FUNDING-PROOF.md
+ */
+export interface FundingProofParams {
+  /** User's actual balance (private) */
+  balance: bigint
+  /** Minimum amount required for the intent (public) */
+  minimumRequired: bigint
+  /** Blinding factor for the commitment (private) */
+  blindingFactor: Uint8Array
+  /** Asset identifier (public) */
+  assetId: string
+  /** User's address for ownership proof (private) */
+  userAddress: string
+  /** Signature proving ownership of the address (private) */
+  ownershipSignature: Uint8Array
+}
+
+/**
+ * Parameters for generating a Validity Proof
+ *
+ * Proves: intent is authorized by sender without revealing sender
+ *
+ * @see docs/specs/VALIDITY-PROOF.md
+ */
+export interface ValidityProofParams {
+  /** Hash of the intent (public) */
+  intentHash: HexString
+  /** Sender's address (private) */
+  senderAddress: string
+  /** Blinding factor for sender commitment (private) */
+  senderBlinding: Uint8Array
+  /** Sender's secret key (private) */
+  senderSecret: Uint8Array
+  /** Signature authorizing the intent (private) */
+  authorizationSignature: Uint8Array
+  /** Nonce for nullifier generation (private) */
+  nonce: Uint8Array
+  /** Intent timestamp (public) */
+  timestamp: number
+  /** Intent expiry (public) */
+  expiry: number
+}
+
+/**
+ * Parameters for generating a Fulfillment Proof
+ *
+ * Proves: solver delivered output >= minimum to correct recipient
+ *
+ * @see docs/specs/FULFILLMENT-PROOF.md
+ */
+export interface FulfillmentProofParams {
+  /** Hash of the original intent (public) */
+  intentHash: HexString
+  /** Actual output amount delivered (private) */
+  outputAmount: bigint
+  /** Blinding factor for output commitment (private) */
+  outputBlinding: Uint8Array
+  /** Minimum required output from intent (public) */
+  minOutputAmount: bigint
+  /** Recipient's stealth address (public) */
+  recipientStealth: HexString
+  /** Solver's identifier (public) */
+  solverId: string
+  /** Solver's secret for authorization (private) */
+  solverSecret: Uint8Array
+  /** Oracle attestation of delivery (private) */
+  oracleAttestation: OracleAttestation
+  /** Time of fulfillment (public) */
+  fulfillmentTime: number
+  /** Intent expiry (public) */
+  expiry: number
+}
+
+/**
+ * Oracle attestation for cross-chain verification
+ */
+export interface OracleAttestation {
+  /** Recipient who received funds */
+  recipient: HexString
+  /** Amount received */
+  amount: bigint
+  /** Transaction hash on destination chain */
+  txHash: HexString
+  /** Block number containing the transaction */
+  blockNumber: bigint
+  /** Oracle signature (threshold signature for multi-oracle) */
+  signature: Uint8Array
+}
+
+/**
+ * Result of proof generation
+ */
+export interface ProofResult {
+  /** The generated proof */
+  proof: ZKProof
+  /** Public inputs used in the proof */
+  publicInputs: HexString[]
+  /** Commitment (if generated as part of proof) */
+  commitment?: Commitment
+}
+
+/**
+ * Proof Provider Interface
+ *
+ * Implementations of this interface provide ZK proof generation and verification.
+ * The SDK uses this interface to remain agnostic to the underlying ZK framework.
+ *
+ * @example
+ * ```typescript
+ * // Use mock provider for testing
+ * const mockProvider = new MockProofProvider()
+ *
+ * // Use Noir provider for production
+ * const noirProvider = new NoirProofProvider()
+ *
+ * // Configure SIP client with provider
+ * const sip = new SIP({
+ *   network: 'testnet',
+ *   proofProvider: noirProvider,
+ * })
+ * ```
+ */
+export interface ProofProvider {
+  /**
+   * The ZK framework this provider uses
+   */
+  readonly framework: ProofFramework
+
+  /**
+   * Whether the provider is ready to generate proofs
+   * (e.g., circuits compiled, keys loaded)
+   */
+  readonly isReady: boolean
+
+  /**
+   * Initialize the provider (compile circuits, load keys, etc.)
+   *
+   * @throws Error if initialization fails
+   */
+  initialize(): Promise<void>
+
+  /**
+   * Generate a Funding Proof
+   *
+   * Proves that the user has sufficient balance without revealing the exact amount.
+   *
+   * @param params - Funding proof parameters
+   * @returns The generated proof with public inputs
+   * @throws ProofGenerationError if proof generation fails
+   *
+   * @see docs/specs/FUNDING-PROOF.md (~22,000 constraints)
+   */
+  generateFundingProof(params: FundingProofParams): Promise<ProofResult>
+
+  /**
+   * Generate a Validity Proof
+   *
+   * Proves that the intent is authorized without revealing the sender.
+   *
+   * @param params - Validity proof parameters
+   * @returns The generated proof with public inputs
+   * @throws ProofGenerationError if proof generation fails
+   *
+   * @see docs/specs/VALIDITY-PROOF.md (~72,000 constraints)
+   */
+  generateValidityProof(params: ValidityProofParams): Promise<ProofResult>
+
+  /**
+   * Generate a Fulfillment Proof
+   *
+   * Proves that the solver correctly delivered the output.
+   *
+   * @param params - Fulfillment proof parameters
+   * @returns The generated proof with public inputs
+   * @throws ProofGenerationError if proof generation fails
+   *
+   * @see docs/specs/FULFILLMENT-PROOF.md (~22,000 constraints)
+   */
+  generateFulfillmentProof(params: FulfillmentProofParams): Promise<ProofResult>
+
+  /**
+   * Verify a proof
+   *
+   * @param proof - The proof to verify
+   * @returns true if the proof is valid, false otherwise
+   */
+  verifyProof(proof: ZKProof): Promise<boolean>
+}
+
+/**
+ * Error thrown when proof generation fails
+ */
+export class ProofGenerationError extends Error {
+  readonly proofType: 'funding' | 'validity' | 'fulfillment'
+  readonly cause?: Error
+
+  constructor(
+    proofType: 'funding' | 'validity' | 'fulfillment',
+    message: string,
+    cause?: Error,
+  ) {
+    super(`${proofType} proof generation failed: ${message}`)
+    this.name = 'ProofGenerationError'
+    this.proofType = proofType
+    this.cause = cause
+  }
+}