Quality cleanup refactoring

Made-with: Cursor

_docs/04_refactoring/01-quality-cleanup/analysis/refactoring_roadmap.md

@@ -0,0 +1,63 @@
+# Refactoring Roadmap
+
+**Run**: 01-quality-cleanup
+**Hardening tracks**: Technical Debt (Track A)
+**Total changes**: 10
+
+## Phased Execution
+
+### Phase 1 — Critical Fixes (C03, C04, C09, C10)
+
+Data integrity and correctness issues. These changes fix silent data corruption and silent upload failures.
+
+| Change | Files | Risk | Points |
+|--------|-------|------|--------|
+| C03 | security.pyx | medium | 2 |
+| C04 | binary_split.py | medium | 2 |
+| C09 | api_client.pyx | medium | 1 |
+| C10 | api_client.pyx | medium | 1 |
+
+### Phase 2 — Safety (C01, C02)
+
+Thread safety under concurrent requests.
+
+| Change | Files | Risk | Points |
+|--------|-------|------|--------|
+| C01 | main.py | low | 2 |
+| C02 | main.py | low | 2 |
+
+### Phase 3 — Cleanup (C05, C06, C07, C08)
+
+Dead code removal and minor configurability/error handling.
+
+| Change | Files | Risk | Points |
+|--------|-------|------|--------|
+| C05 | constants.pyx | low | 1 |
+| C06 | main.py | low | 1 |
+| C07 | api_client.pyx, api_client.pxd | low | 1 |
+| C08 | constants.pyx, constants.pxd | low | 1 |
+
+## Task Grouping
+
+Changes are grouped into 3 implementable tasks to reduce overhead while keeping each under 5 complexity points:
+
+| Task | Changes | Points | Rationale |
+|------|---------|--------|-----------|
+| T1: Fix crypto padding + upload error handling | C03, C04, C09, C10 | 3 | All correctness fixes — crypto + error propagation |
+| T2: Thread safety in main.py | C01, C02 | 3 | Both affect main.py concurrency patterns |
+| T3: Dead code removal + minor fixes | C05, C06, C07, C08 | 2 | All low-risk cleanup, independent of T1/T2 |
+
+**Dependency order**: T1 → T2 → T3 (T2 and T3 can run in parallel after T1)
+
+## Gap Analysis
+
+| Acceptance Criteria | Status | Gap |
+|-------------------|--------|-----|
+| AC-1 through AC-10 (Functional) | Covered by e2e tests | No gap |
+| AC-11 through AC-15 (Security) | AC-11 improved by C03/C04 | JWT verification (AC-14) tracked as Open Question #1 |
+| AC-16 through AC-18 (Operational) | No change needed | No gap |
+
+## Risk Summary
+
+- **Highest risk**: C03/C04 — changing decryption behavior. If existing encrypted data has non-standard padding, the library will raise instead of silently passing. This is correct behavior but could surface latent issues.
+- **Mitigation**: The e2e test suite exercises upload/download roundtrip (test_upload_download_roundtrip), which validates the encrypt→decrypt path end-to-end.

_docs/04_refactoring/01-quality-cleanup/analysis/research_findings.md

@@ -0,0 +1,61 @@
+# Research Findings
+
+## Current State Analysis
+
+### Strengths
+- Small codebase (785 LOC) — easy to reason about
+- Clear component boundaries (Core Models → Security → Resource Mgmt → HTTP API)
+- Cython compilation achieves IP protection goal
+- Binary-split scheme is clever security design
+- E2e test suite now provides 100% endpoint coverage (18 tests, all passing)
+
+### Weaknesses
+- Thread safety gaps in the singleton and global state patterns
+- Manual cryptographic operations where library functions exist
+- Dead code accumulated from earlier iterations
+- Hardcoded configuration values
+
+## Change-Specific Analysis
+
+### C01/C02: Thread Safety (main.py)
+
+**Current**: Bare global variable + `if None` check for ApiClient singleton. Module-level globals for unlock state.
+
+**Recommended approach**: Double-checked locking with `threading.Lock` for the singleton. Encapsulate unlock state in a class with lock-guarded accessors. These are standard Python concurrency patterns — no library changes needed.
+
+**Alternative considered**: Using `functools.lru_cache` for singleton — rejected because it doesn't provide thread safety guarantees for the initialization side-effects (CDN config download).
+
+### C03/C04: PKCS7 Padding (security.pyx, binary_split.py)
+
+**Current**: Manual last-byte inspection without full padding validation.
+
+**Recommended approach**: Use `cryptography.hazmat.primitives.padding.PKCS7(128).unpadder()` — already imported in `security.pyx`. For `binary_split.py`, integrate the library's unpadder into the streaming decryption instead of post-hoc file truncation.
+
+**Risk**: If any existing encrypted data was produced with non-standard padding, the library unpadder will raise `ValueError` instead of silently passing. This is correct behavior — it surfaces corruption that was previously hidden.
+
+### C05: Log Path (constants.pyx)
+
+**Current**: Hardcoded `"Logs/log_loader_{time:YYYYMMDD}.txt"`.
+
+**Recommended approach**: `os.environ.get("LOG_DIR", "Logs")` — minimal change, no new dependencies.
+
+### C06: Error Handling (main.py)
+
+**Current**: `except OSError: pass` — violates project rules.
+
+**Recommended approach**: Import `constants` and call `constants.logerror()`. One-line fix.
+
+**Note**: `constants` is a Cython module — `main.py` would need to import the compiled `.so`. This works because `main.py` already imports other Cython modules indirectly via `api_client`. However, `main.py` currently only imports `unlock_state` (pure Python). A simpler approach is using `loguru.logger.warning()` directly since loguru is already configured by the time `main.py` runs.
+
+### C07/C08: Dead Code Removal
+
+**Approach**: Straight deletion. Git history preserves everything. No behavioral risk.
+
+## Prioritized Recommendations
+
+| Priority | Changes | Rationale |
+|----------|---------|-----------|
+| 1 (critical fix) | C03, C04 | Correctness — silent data corruption on invalid padding |
+| 2 (safety) | C01, C02 | Thread safety under concurrent requests |
+| 3 (cleanup) | C07, C08 | Reduce cognitive load, prevent drift |
+| 4 (minor) | C05, C06 | Configurability and error visibility |