fix(xdr): implement strict bounds checking for ledger sequence overflow protection

XDR_OVERFLOW_FIX_SUMMARY.md

@@ -0,0 +1,87 @@
+# XDR Integer Overflow Fix Summary
+
+## Problem Description
+The XDR decoder had a critical vulnerability where ledger sequences could overflow when parsing extremely large values near the uint32 boundary (4,294,967,295). This could cause:
+- Silent wraparound to 0 when incrementing sequences at the boundary
+- Unpredictable behavior in ledger state management
+- Potential data corruption in simulation results
+
+## Root Cause Analysis
+1. **Unbounded Increment**: `session.go` used simple `s.ledgerSequence++` without overflow checking
+2. **Insufficient Validation**: `validator.go` only checked for zero and reasonable limits, not overflow boundaries
+3. **Missing Test Coverage**: No tests existed for uint32 boundary conditions
+
+## Solution Implementation
+
+### 1. Enhanced Validation (`internal/simulator/validator.go`)
+```go
+// Added strict bounds checking for overflow prevention
+const maxSafeUint32 = uint32(4294967294) // math.MaxUint32 - 1
+if sequence >= maxSafeUint32 {
+    return &ValidationError{
+        Field: "ledger_sequence", 
+        Message: "sequence too close to uint32 overflow boundary", 
+        Code: "ERR_OVERFLOW_RISK"
+    }
+}
+```
+
+### 2. Safe Increment Logic (`internal/shell/session.go`)
+```go
+// Added overflow-safe increment with automatic recovery
+func (s *Session) incrementLedgerSequence() error {
+    const maxSafeUint32 = uint32(4294967294)
+    if s.ledgerSequence >= maxSafeUint32 {
+        return fmt.Errorf("ledger sequence %d would overflow uint32 boundary", s.ledgerSequence)
+    }
+    s.ledgerSequence++
+    return nil
+}
+```
+
+### 3. Comprehensive Test Coverage
+- **`validator_test.go`**: Tests all boundary conditions and error codes
+- **`session_overflow_test.go`**: Tests session-level overflow protection
+- **`overflow_integration_test.go`**: End-to-end integration tests
+
+## Test Cases Added
+
+### Boundary Value Tests
+- `MaxUint32 - 2`: ✅ PASS (last safe incrementable value)
+- `MaxUint32 - 1`: ❌ FAIL (would overflow on increment)  
+- `MaxUint32`: ❌ FAIL (already at overflow boundary)
+
+### Edge Case Coverage
+- Zero sequences (invalid)
+- Strict mode reasonable limits (1B)
+- Overflow recovery (reset to 1)
+- Normal operation validation
+
+## Files Modified
+1. `internal/simulator/validator.go` - Enhanced bounds checking
+2. `internal/shell/session.go` - Safe increment logic
+3. `internal/simulator/validator_test.go` - New comprehensive tests
+4. `internal/shell/session_overflow_test.go` - Session overflow tests
+5. `internal/simulator/overflow_integration_test.go` - Integration tests
+
+## Verification
+- All new code passes static analysis (no diagnostics)
+- Comprehensive test coverage for overflow scenarios
+- Backward compatibility maintained for normal sequences
+- Error handling provides clear feedback for overflow conditions
+
+## Security Impact
+- **Before**: Silent overflow could corrupt ledger state
+- **After**: Explicit validation prevents overflow, safe recovery on boundary conditions
+- **Risk Mitigation**: Proactive detection and handling of overflow scenarios
+
+## Performance Impact
+- Minimal overhead: Single uint32 comparison per validation
+- No impact on normal operation paths
+- Efficient error handling without exceptions
+
+## Deployment Notes
+- Changes are backward compatible
+- Existing valid sequences continue to work
+- Only sequences near uint32 boundary are affected
+- CI tests will validate the fix before deployment

internal/shell/session.go

@@ -122,8 +122,12 @@ func (s *Session) buildInvocationEnvelope(contractID, function string, args []st
 
 // updateLedgerState updates the session's ledger state based on simulation results
 func (s *Session) updateLedgerState(resp *simulator.SimulationResponse) {
-	// Increment ledger sequence
-	s.ledgerSequence++
+	// Safely increment ledger sequence with overflow protection
+	if err := s.incrementLedgerSequence(); err != nil {
+		// Log error but don't fail the operation - reset to safe value
+		fmt.Printf("Warning: ledger sequence overflow detected, resetting to 1: %v\n", err)
+		s.ledgerSequence = 1
+	}
 
 	// Update timestamp
 	now := time.Now().Unix()
@@ -136,6 +140,18 @@ func (s *Session) updateLedgerState(resp *simulator.SimulationResponse) {
 	// This would involve parsing the ResultMetaXDR to get state changes
 }
 
+// incrementLedgerSequence safely increments the ledger sequence with overflow protection
+func (s *Session) incrementLedgerSequence() error {
+	const maxSafeUint32 = uint32(4294967294) // math.MaxUint32 - 1
+
+	if s.ledgerSequence >= maxSafeUint32 {
+		return fmt.Errorf("ledger sequence %d would overflow uint32 boundary", s.ledgerSequence)
+	}
+
+	s.ledgerSequence++
+	return nil
+}
+
 // GetStateSummary returns a summary of the current ledger state
 func (s *Session) GetStateSummary() StateSummary {
 	return StateSummary{

internal/shell/session_overflow_test.go

@@ -0,0 +1,139 @@
+// Copyright 2026 Erst Users
+// SPDX-License-Identifier: Apache-2.0
+
+package shell
+
+import (
+	"context"
+	"math"
+	"testing"
+
+	"github.com/dotandev/hintents/internal/rpc"
+	"github.com/dotandev/hintents/internal/simulator"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// MockRunner implements simulator.RunnerInterface for testing
+type MockRunner struct {
+	response *simulator.SimulationResponse
+	err      error
+}
+
+func (m *MockRunner) Run(ctx context.Context, req *simulator.SimulationRequest) (*simulator.SimulationResponse, error) {
+	if m.err != nil {
+		return nil, m.err
+	}
+	return m.response, nil
+}
+
+func TestSessionLedgerSequenceOverflowProtection(t *testing.T) {
+	tests := []struct {
+		name            string
+		initialSequence uint32
+		expectedResult  uint32
+		expectReset     bool
+	}{
+		{
+			name:            "normal increment",
+			initialSequence: 12345,
+			expectedResult:  12346,
+			expectReset:     false,
+		},
+		{
+			name:            "near max uint32 - safe",
+			initialSequence: math.MaxUint32 - 2,
+			expectedResult:  math.MaxUint32 - 1,
+			expectReset:     false,
+		},
+		{
+			name:            "at overflow boundary",
+			initialSequence: math.MaxUint32 - 1,
+			expectedResult:  1, // Should reset to 1
+			expectReset:     true,
+		},
+		{
+			name:            "at max uint32",
+			initialSequence: math.MaxUint32,
+			expectedResult:  1, // Should reset to 1
+			expectReset:     true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Create mock runner
+			mockRunner := &MockRunner{
+				response: &simulator.SimulationResponse{
+					Status: "success",
+					Events: []string{},
+					Logs:   []string{},
+				},
+			}
+
+			// Create session with mock runner
+			session := NewSession(mockRunner, nil, rpc.NetworkTestnet)
+			session.ledgerSequence = tt.initialSequence
+
+			// Test the increment logic directly (Invoke would fail due to unimplemented envelope building)
+			err := session.incrementLedgerSequence()
+
+			if tt.expectReset {
+				// Should return error for overflow
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), "would overflow uint32 boundary")
+
+				// Simulate the reset behavior from updateLedgerState
+				session.ledgerSequence = 1
+			} else {
+				require.NoError(t, err)
+			}
+
+			assert.Equal(t, tt.expectedResult, session.ledgerSequence)
+		})
+	}
+}
+
+func TestIncrementLedgerSequence(t *testing.T) {
+	session := NewSession(nil, nil, rpc.NetworkTestnet)
+
+	// Test normal increment
+	session.ledgerSequence = 100
+	err := session.incrementLedgerSequence()
+	require.NoError(t, err)
+	assert.Equal(t, uint32(101), session.ledgerSequence)
+
+	// Test overflow protection
+	session.ledgerSequence = math.MaxUint32 - 1
+	err = session.incrementLedgerSequence()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "would overflow uint32 boundary")
+	// Sequence should remain unchanged when error occurs
+	assert.Equal(t, uint32(math.MaxUint32-1), session.ledgerSequence)
+
+	// Test at max uint32
+	session.ledgerSequence = math.MaxUint32
+	err = session.incrementLedgerSequence()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "would overflow uint32 boundary")
+	assert.Equal(t, uint32(math.MaxUint32), session.ledgerSequence)
+}
+
+func TestUpdateLedgerStateOverflowHandling(t *testing.T) {
+	session := NewSession(nil, nil, rpc.NetworkTestnet)
+
+	// Set sequence to overflow boundary
+	session.ledgerSequence = math.MaxUint32 - 1
+
+	mockResponse := &simulator.SimulationResponse{
+		Status: "success",
+		Events: []string{},
+		Logs:   []string{},
+	}
+
+	// This should trigger overflow protection and reset to 1
+	session.updateLedgerState(mockResponse)
+
+	// Should be reset to 1 due to overflow protection
+	assert.Equal(t, uint32(1), session.ledgerSequence)
+}