feat: harden concurrent buys, wallet balance, challenge timing, and p…

[ExcelDsigN-tech]

feat: harden concurrent buys, wallet balance, challenge timing, and payload limits

Closes #510, Closes #511, Closes #512, Closes #513

Overview

Hardens 4 critical reliability and security paths in the prompt-hash contract and API subsystem to address race conditions, timing side-channels, cryptic transaction errors, and silent payload storage limit violations.

Feature Summary

• Prevented concurrent buy/lease oversells by moving max_supply checks and sales_count increments into an atomic step before token transfers
• Mapped raw Soroban op_underfunded / token errors to a structured InsufficientBalance contract error and user-friendly client message
• Mitigated wallet enumeration timing attacks in the authentication challenge endpoint by executing a constant-time dummy HMAC calculation on invalid inputs
• Surfaced structured PAYLOAD_TOO_LARGE errors when encrypted prompt payloads exceed the 4096-character contract limit
• Added 5 contract regression tests covering wallet funding guards and atomic supply enforcement

Technical Implementation

• Concurrent Buys & Atomic State Updates (contracts/prompt-hash/contract.rs):
  • Updated execute_buy, buy_bundle, and lease_prompt to check max_supply, increment sales_count, and invoke Storage::update_prompt immediately after setting the reentrancy guard and before initiating any transfer_from operations
  • Removed duplicate post-transfer increments and redundant pre-validation checks
• Wallet Balance Verification (contracts/prompt-hash/types.rs, contract.rs, promptHashClient.ts):
  • Added InsufficientBalance = 55 to the Error enum
  • Added explicit asset_client.balance(&buyer) pre-checks with ensure!(balance >= price, InsufficientBalance) prior to calling transfer_from across all purchase and lease flows
  • Extended CONTRACT_ERROR_CODES and classifyContractError in promptHashClient.ts to translate InsufficientBalance and op_underfunded into WALLET_NOT_FUNDED and INSUFFICIENT_BALANCE
• Timing Side-Channel Prevention (api/auth/challenge.ts):
  • Added dummy createHmac("sha256", secret).update("padding").digest("base64url") processing on parseRequestBody failures to normalize response latency across valid and invalid inputs
• Error Codes & Payload Validation (src/lib/api/errorCodes.ts):
  • Added PAYLOAD_TOO_LARGE and WALLET_NOT_FUNDED variants with user-actionable error messages

Test Coverage

• Added 5 contract tests in contracts/prompt-hash/src/test.rs:
  • test_buy_returns_insufficient_balance_when_wallet_unfunded
  • test_buy_supply_enforcement_is_atomic
  • test_buy_bundle_returns_insufficient_balance_when_wallet_unfunded
  • test_buy_bundle_supply_enforcement_blocks_when_full
  • test_lease_returns_insufficient_balance_when_wallet_unfunded
• Added timing/enumeration coverage test in api/auth/challenge.test.ts verifying identical 400 MISSING_FIELDS responses across invalid addresses
• Note: Full cargo test and vitest suite runs pending CI execution under Rust 1.91+ toolchain and installed dependency tree

Checklists

• Make max_supply check and sales_count increment atomic before token transfers
• Pre-check buyer asset balance and throw InsufficientBalance (Error 55) on underfunded wallets
• Normalize challenge handler execution timing for invalid requests via dummy HMAC execution
• Add client-side error code mapping for INSUFFICIENT_BALANCE and PAYLOAD_TOO_LARGE
• Retain input body size limits and secret length guards across API routes
• Add contract tests for atomic supply enforcement and unfunded wallet handling

[drips-wave]

@ExcelDsigN-tech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits