asap-protocol 0.3.0__tar.gz → 0.5.0__tar.gz

asap_protocol-0.5.0/.cursor/dev-planning/code-review/v0.5.0/sprint-s3-code-review.md

@@ -0,0 +1,284 @@
+# Code Review: PR #19 - feat(security): add replay attack prevention and HTTPS enforcement
+
+## 1. Executive Summary
+
+* **Impact Analysis:** **Medium Risk**. New security-critical validation code (timestamp and nonce) integrated into the request processing pipeline. HTTPS enforcement affects all client connections.
+* **Architecture Check:** **Yes**. Implementation follows SOLID principles, separates validation logic into dedicated module (`validators.py`), and uses Protocol pattern for extensibility.
+* **Blockers:** **0** critical issues found.
+
+---
+
+## 2. Critical Issues (Must Fix)
+
+*No critical security or logic bugs found.* The implementation is solid, properly handles edge cases, and includes comprehensive test coverage.
+
+---
+
+## 3. Improvements & Refactoring (Strongly Recommended)
+
+The following are quality improvements that would enhance the robustness and maintainability of the implementation.
+
+### 3.1 [Concurrency] Potential Race Condition in `InMemoryNonceStore` - `src/asap/transport/validators.py`
+
+* **Location:** Lines 169-184 (`is_used` method)
+* **Context:** The `is_used` method performs cleanup and check within a lock, but there's a TOCTOU (time-of-check-time-of-use) race condition between `is_used()` and `mark_used()` calls in `validate_envelope_nonce()`.
+* **Problem:** Two concurrent requests with the same nonce could both pass `is_used()` before either calls `mark_used()`.
+* **Risk:** Low. Under typical load, this race is unlikely. However, for a high-security protocol, this should be addressed.
+* **Suggestion:** Combine check-and-mark into a single atomic operation:
+
+```python
+# file: src/asap/transport/validators.py
+
+class InMemoryNonceStore:
+    # ... existing code ...
+    
+    def check_and_mark(self, nonce: str, ttl_seconds: int) -> bool:
+        """Atomically check if nonce is used and mark it if not.
+        
+        Args:
+            nonce: The nonce value to check and mark
+            ttl_seconds: Time-to-live in seconds for the nonce
+            
+        Returns:
+            True if nonce was already used, False if it was newly marked
+        """
+        with self._lock:
+            self._cleanup_expired()
+            if nonce in self._store and self._store[nonce] >= time.time():
+                return True  # Already used
+            self._store[nonce] = time.time() + ttl_seconds
+            return False  # Newly marked
+```
+
+Then in `validate_envelope_nonce()`:
+```diff
+-    if nonce_store.is_used(nonce):
+-        raise InvalidNonceError(...)
+-    nonce_store.mark_used(nonce, ttl_seconds=600)
++    if nonce_store.check_and_mark(nonce, ttl_seconds=600):
++        raise InvalidNonceError(...)
+```
+
+**Note:** This would require updating the `NonceStore` Protocol to include the atomic method.
+
+---
+
+### 3.2 [Resilience] Missing Empty Nonce String Validation - `src/asap/transport/validators.py`
+
+* **Location:** Lines 261-269
+* **Context:** The nonce validation checks for non-string types but doesn't reject empty strings.
+* **Problem:** An empty string `""` would pass validation and be stored, but it offers no replay protection.
+* **Suggestion:**
+
+```diff
+# file: src/asap/transport/validators.py (Line 263-269)
+
+    # Validate nonce is a string
+-   if not isinstance(nonce, str):
++   if not isinstance(nonce, str) or not nonce:
+        raise InvalidNonceError(
+            nonce=str(nonce),
+-           message=f"Nonce must be a string, got {type(nonce).__name__}",
++           message=f"Nonce must be a non-empty string, got {type(nonce).__name__ if not isinstance(nonce, str) else 'empty string'}",
+            details={"envelope_id": envelope.id},
+        )
+```
+
+---
+
+### 3.3 [Observability] Nonce Exposed in Log Output - `src/asap/transport/server.py`
+
+* **Location:** Lines 885-889
+* **Context:** The nonce value is logged when validation fails.
+* **Problem:** Nonces, while not directly sensitive, could be useful to attackers for reconnaissance if exposed in logs.
+* **Suggestion:** Consider truncating or hashing the nonce in logs:
+
+```diff
+# file: src/asap/transport/server.py (Lines 885-889)
+
+            except InvalidNonceError as e:
+                logger.warning(
+                    "asap.request.invalid_nonce",
+                    envelope_id=envelope.id,
+-                   nonce=e.nonce,
++                   nonce_prefix=e.nonce[:8] + "..." if len(e.nonce) > 8 else e.nonce,
+                    error=e.message,
+                )
+```
+
+---
+
+### 3.4 [Data Integrity] Hardcoded TTL in `validate_envelope_nonce` - `src/asap/transport/validators.py`
+
+* **Location:** Line 280
+* **Context:** The nonce TTL is hardcoded to 600 seconds (10 minutes).
+* **Problem:** This should be configurable or derived from `MAX_ENVELOPE_AGE_SECONDS` to ensure consistency.
+* **Suggestion:**
+
+```diff
+# file: src/asap/transport/validators.py (Line 279-280)
+
++   # Use 2x envelope age as TTL to ensure nonces expire after the envelope would
++   # have been rejected anyway, providing some buffer
++   nonce_ttl = MAX_ENVELOPE_AGE_SECONDS * 2  # 10 minutes by default
+-   nonce_store.mark_used(nonce, ttl_seconds=600)
++   nonce_store.mark_used(nonce, ttl_seconds=nonce_ttl)
+```
+
+---
+
+### 3.5 [Defensive Coding] IPv6 Localhost Edge Case - `src/asap/transport/client.py`
+
+* **Location:** Lines 207-224 (`_is_localhost` method)
+* **Context:** IPv6 localhost detection handles `::1` but not full forms like `[::1]`.
+* **Problem:** URLs like `http://[::1]:8000` would have hostname `[::1]` (with brackets) not `::1`.
+* **Suggestion:**
+
+```diff
+# file: src/asap/transport/client.py (Lines 222-224)
+
+        hostname_lower = hostname.lower()
+-       return hostname_lower in ("localhost", "127.0.0.1", "::1")
++       # Handle both ::1 and [::1] (bracket notation from URL parsing)
++       return hostname_lower in ("localhost", "127.0.0.1", "::1", "[::1]")
+```
+
+---
+
+### 3.6 [Testing] Missing Integration Test for Validation Order - `tests/transport/`
+
+* **Location:** New test file recommended
+* **Context:** Timestamp validation runs before nonce validation in the server handler.
+* **Problem:** No test verifies the validation order or that both validations are consistently applied together.
+* **Suggestion:** Add an integration test that verifies:
+  1. Invalid timestamp is rejected before nonce check
+  2. Valid timestamp with invalid nonce is rejected
+  3. Both validations return appropriate error codes
+
+---
+
+## 4. Nitpicks & Questions
+
+### Code Style
+
+* **`src/asap/transport/validators.py` (Line 10):** `datetime, timezone` import could be grouped with stdlib imports for PEP 8 compliance, but current grouping is acceptable.
+
+* **`src/asap/errors.py` (Lines 229-234):** The conditional dict merge pattern is creative but slightly hard to read:
+  ```python
+  **(age_seconds is not None and {"age_seconds": age_seconds} or {})
+  ```
+  Consider explicit if/else for clarity (but this is a nitpick - current code works correctly).
+
+### Documentation
+
+* **`docs/security.md`:** Excellent comprehensive documentation. Minor suggestion: add a "Quick Reference" table at the top summarizing the validation constants and their values.
+
+### Type Annotations
+
+* **`src/asap/transport/client.py` (Line 208):** `parsed_url: Any` type annotation loses type safety. Consider using `ParseResult` from `urllib.parse`:
+  ```python
+  from urllib.parse import ParseResult
+  
+  @staticmethod
+  def _is_localhost(parsed_url: ParseResult) -> bool:
+  ```
+
+### Test Coverage
+
+* **`tests/transport/unit/test_validators.py`:** Tests are well-structured. The `test_expired_nonce_allowed_again` test uses `time.sleep(1.1)` which is acceptable for unit tests but could cause flakiness. Consider using time mocking for more reliable tests.
+
+---
+
+## 5. Domain-Specific Analysis
+
+### 5.1 Replay Attack Prevention
+
+**Timestamp Validation:**
+- ✅ Correct implementation of 5-minute age window
+- ✅ Correct implementation of 30-second future tolerance
+- ✅ Timezone handling covers naive and non-UTC timestamps
+- ✅ Error messages include detailed context for debugging
+
+**Nonce Validation:**
+- ✅ Optional by design (backward compatible)
+- ✅ Lazy cleanup prevents unbounded memory growth
+- ⚠️ Race condition between `is_used()` and `mark_used()` (see Section 3.1)
+- ⚠️ Hardcoded 10-minute TTL (see Section 3.4)
+
+### 5.2 HTTPS Enforcement
+
+**Client-Side Validation:**
+- ✅ Localhost exception for development is appropriate
+- ✅ Clear error messages with override instructions
+- ✅ Warning log for HTTP localhost usage
+- ⚠️ IPv6 localhost edge case (see Section 3.5)
+
+### 5.3 Concurrency Safety
+
+| Component | Thread-Safe | Notes |
+|-----------|-------------|-------|
+| `InMemoryNonceStore` | ✅ Yes | Uses `RLock` for all operations |
+| `validate_envelope_timestamp` | ✅ Yes | Stateless function |
+| `validate_envelope_nonce` | ⚠️ Partial | TOCTOU race (see Section 3.1) |
+
+---
+
+## 6. Verification Results
+
+### Automated Tests
+
+| Check | Command | Result |
+|-------|---------|--------|
+| Unit Tests | `uv run pytest tests/transport/unit/test_validators.py -v` | ✅ **11/11 passed** |
+| HTTPS Tests | `uv run pytest tests/transport/test_client.py -v -k HTTPS` | ✅ **6/6 passed** |
+| Full Suite | `uv run pytest` | ✅ **627 passed** |
+| Coverage | `pytest --cov` | ✅ **91.90%** |
+
+### Static Analysis
+
+| Check | Command | Result |
+|-------|---------|--------|
+| Linting | `uv run ruff check src/asap/transport/` | ✅ **All checks passed** |
+| Type Check | `uv run mypy --strict src/asap/transport/` | ✅ **No issues found** |
+
+### Manual Verification
+
+* **Timestamp validation flow:** Traced through `server.py` lines 856-879, confirms early return on validation failure.
+* **Nonce validation flow:** Traced through `server.py` lines 881-904, confirms proper error handling.
+* **HTTPS enforcement:** Traced through `client.py` lines 174-197, confirms localhost exception logic.
+
+---
+
+## 7. Commits Review
+
+The PR follows atomic commit principles with clear conventional commit messages:
+
+| Commit | Type | Description | Status |
+|--------|------|-------------|--------|
+| `e3ca11a` | feat | Add timestamp validation constants | ✅ Well-scoped |
+| `ffe7127` | feat | Add timestamp validation for replay prevention | ✅ Well-scoped |
+| `57f324d` | feat | Add optional nonce validation | ✅ Well-scoped |
+| `7ba44f6` | feat | Integrate timestamp validation in handler | ✅ Well-scoped |
+| `5e03420` | feat | Enforce HTTPS for production connections | ✅ Well-scoped |
+| `37c9dae` | test | Add timestamp and HTTPS validation tests | ✅ Well-scoped |
+| `97bdbf3` | docs | Add replay prevention and HTTPS docs | ✅ Well-scoped |
+| `57e6f2d` | test | Add edge case tests for improved coverage | ✅ Well-scoped |
+
+---
+
+## 8. Conclusion
+
+**APPROVED FOR MERGE** ✅
+
+The implementation is production-ready with strong security foundations. The suggestions in Section 3 are improvements for future iterations, not blockers.
+
+**Key Strengths:**
+- Clean separation of concerns with dedicated `validators.py` module
+- Comprehensive error handling with detailed context
+- Backward compatible (nonce validation is optional)
+- Thorough documentation and test coverage
+
+**Recommended Follow-ups (Post-Merge):**
+1. Address the TOCTOU race condition in `InMemoryNonceStore` (Priority: Medium)
+2. Add empty nonce string validation (Priority: Low)
+3. Make nonce TTL configurable or derived from envelope age constant (Priority: Low)

asap_protocol-0.5.0/.cursor/dev-planning/code-review/v0.5.0/sprint-s4-code-review.md

@@ -0,0 +1,99 @@
+# Code Review: PR #20 (S4 Retry & Auth)
+
+## 1. Executive Summary
+* **Impact Analysis:** **Medium-High Risk**. The core retry and circuit breaker logic is solid, but a critical gap in exception handling (Timeouts) compromises the improved resilience.
+* **Architecture Check:** **Yes**. The implementation aligns well with the planned architecture, utilizing decorators, efficient constants, and proper layering.
+* **Blockers:** **1** critical issue found (Unhandled Timeouts).
+
+## 2. Critical Issues (Must Fix)
+*Issues that cause bugs, security risks, or strictly violate architecture/linting rules.*
+
+### Unhandled Request Timeouts - src/asap/transport/client.py
+* **Location:** Lines 613-800 (`send` method retry loop)
+* **Problem:** The current implementation catches `httpx.ConnectError` but fails to catch `httpx.TimeoutException`. If a request times out (network stall, firewall, slow server), the exception will bubble up immediately, bypassing the retry logic and, critically, **failing to record the failure in the Circuit Breaker**. This defeat the purpose of the circuit breaker for one of its most important use cases (unresponsive services).
+* **Recommendation:** Catch `httpx.TimeoutException`, record the failure, and trigger the retry logic.
+
+```diff
+-            except httpx.ConnectError as e:
+-                error_msg = (
+-                    f"Connection error to {self.base_url}: {e}. "
+-                    f"Verify the agent is running and accessible."
+-                )
+-                last_exception = ASAPConnectionError(error_msg, cause=e, url=self.base_url)
+-                # Log retry attempt
+-                if attempt < self.max_retries - 1:
+-                    delay = self._calculate_backoff(attempt)
+-                    logger.warning(
+-                        "asap.client.retry",
+-                        # ...
+-                    )
+-                    logger.info(...)
+-                    await asyncio.sleep(delay)
+-                    continue
++            except (httpx.ConnectError, httpx.TimeoutException) as e:
++                is_timeout = isinstance(e, httpx.TimeoutException)
++                error_type = "Timeout" if is_timeout else "Connection error"
++                error_msg = (
++                    f"{error_type} to {self.base_url}: {e}. "
++                    f"Verify the agent is running and accessible."
++                )
++                last_exception = ASAPConnectionError(error_msg, cause=e, url=self.base_url)
++                
++                # Log retry attempt
++                if attempt < self.max_retries - 1:
++                    delay = self._calculate_backoff(attempt)
++                    logger.warning(
++                        "asap.client.retry",
++                        # ... args ...
++                        message=f"{error_type}, retrying in {delay:.2f}s..."
++                    )
++                    await asyncio.sleep(delay)
++                    continue
++
++                # Retries exhausted: Record failure in Circuit Breaker
++                if self._circuit_breaker is not None:
++                    self._circuit_breaker.record_failure()
++                    # Log circuit state change if needed (copy logic from 5xx handler)
++
++                raise last_exception
+```
+
+## 3. Improvements & Refactoring (Strongly Recommended)
+
+### Circuit Breaker Reset on Remote Error - src/asap/transport/client.py
+- **Location:** Lines 741-748 (`ASAPRemoteError` handling)
+- **Context:** If the server responds with a valid JSON-RPC error (e.g., `-32603` or "Method not found"), it means the *connection* and *transport* are healthy. Currently, this path does not call `record_success()`, so the circuit breaker acts as if the request never succeeded (failure count isn't reset). This could lead to a "stale" failure count effectively reducing the threshold for subsequent real failures.
+- **Suggestion:** Consider a valid JSON-RPC error as a "Success" from the Circuit Breaker's perspective (service is reachable).
+
+```diff
+                 # Check for JSON-RPC error
+                 if "error" in json_response:
++                    # Record success pattern (service is reachable)
++                    if self._circuit_breaker is not None:
++                        self._circuit_breaker.record_success()
++                        
+                     error = json_response["error"]
+                     raise ASAPRemoteError(...)
+```
+
+### Robust Retry-After Parsing - src/asap/transport/client.py
+- **Location:** Line 676
+- **Context:** The HTTP `Retry-After` header can be an HTTP Date string. The current implementation only supports seconds (`float`).
+- **Suggestion:** Add support for Date parsing using `email.utils.parsedate_to_datetime`.
+
+```diff
+-                                delay = float(retry_after)
++                                # Simple check for digit, else try date parsing
++                                if retry_after.replace('.', '', 1).isdigit():
++                                    delay = float(retry_after)
++                                else:
++                                    # Add date parsing logic here (or TODO)
++                                    # from email.utils import parsedate_to_datetime
++                                    # ... calculate delta ...
+```
+
+## 4. Nitpicks & Questions
+
+*   **[src/asap/transport/client.py] (Line 368)**: `self._request_counter` is updated with `+= 1` which is not atomic across threads. Since `CircuitBreaker` uses `RLock`, there is an implication of thread-safety. If `ASAPClient` is shared across threads, this could cause ID collisions. Consider using `itertools.count` and `next()` or a lock if thread safety is a requirement.
+
+*   **[src/asap/transport/client.py] (Line 284)**: The `__init__` method argument list is getting very long (11 args). Consider grouping the retry/circuit-breaker configs into a `RetryConfig` dataclass/pydantic model to avoid `False, 5, 60.0` boolean trap issues and clean up the signature.