Quality cleanup refactoring

Made-with: Cursor
2026-04-22 06:46:32 +00:00 · 2026-04-13 06:21:26 +03:00
parent 8f7deb3fca
commit 4eaf218f09
33 changed files with 957 additions and 207 deletions
@@ -83,6 +83,7 @@ No tests exist. Coverage is 0% across all categories.
 | 3 | Should endpoint-level authorization be enforced? | Security — currently all endpoints accessible post-login | Team |
 | 4 | Should the resource encryption key be per-user instead of shared? | Security — currently all users share one key for big/small split | Team |
 | 5 | What are the target latency/throughput requirements? | Performance — no SLAs defined | Product |
+| 6 | Investigate replacing binary-split security with TPM on Jetson Orin Nano | Architecture — the binary-split model was designed for untrusted end-user laptops; SaaS/edge deployment on Jetson Orin Nano can use TPM instead, potentially simplifying the loader significantly | Team |

 ## Artifact Index

@@ -17,7 +17,6 @@ Central API client that orchestrates authentication, encrypted resource download
 | token       | str         | JWT bearer token                   |
 | cdn_manager | CDNManager  | CDN upload/download client         |
 | api_url     | str         | Base URL for the resource API      |
-| folder      | str         | Declared in `.pxd` but never assigned — dead attribute |

 #### Methods

@@ -28,17 +27,12 @@ Central API client that orchestrates authentication, encrypted resource download
 | `set_credentials`            | cdef       | `(self, Credentials credentials)`                                 | Internal: set credentials, lazy-init CDN manager             |
 | `login`                      | cdef       | `(self)`                                                          | POST `/login`, store JWT token                               |
 | `set_token`                  | cdef       | `(self, str token)`                                               | Decode JWT claims → create `User` with role mapping          |
-| `get_user`                   | cdef       | `(self) -> User`                                                  | Lazy login + return user                                     |
 | `request`                    | cdef       | `(self, str method, str url, object payload, bint is_stream)`     | Authenticated HTTP request with auto-retry on 401/403        |
-| `list_files`                 | cdef       | `(self, str folder, str search_file)`                             | GET `/resources/list/{folder}` with search param             |
-| `check_resource`             | cdef       | `(self)`                                                          | POST `/resources/check` with hardware fingerprint            |
 | `load_bytes`                 | cdef       | `(self, str filename, str folder) -> bytes`                       | Download + decrypt resource using per-user+hw key            |
-| `upload_file`                | cdef       | `(self, str filename, bytes resource, str folder)`                | POST multipart upload to `/resources/{folder}`               |
+| `upload_file`                | cdef       | `(self, str filename, bytes resource, str folder)`                | POST multipart upload to `/resources/{folder}`; raises on HTTP error |
 | `load_big_file_cdn`          | cdef       | `(self, str folder, str big_part) -> bytes`                       | Download large file part from CDN                            |
 | `load_big_small_resource`    | cpdef      | `(self, str resource_name, str folder) -> bytes`                  | Reassemble resource from small (API) + big (CDN/local) parts |
-| `upload_big_small_resource`  | cpdef      | `(self, bytes resource, str resource_name, str folder)`           | Split-encrypt and upload small part to API, big part to CDN  |
-| `upload_to_cdn`              | cpdef      | `(self, str bucket, str filename, bytes file_bytes)`              | Direct CDN upload                                            |
-| `download_from_cdn`          | cpdef      | `(self, str bucket, str filename) -> bytes`                       | Direct CDN download                                          |
+| `upload_big_small_resource`  | cpdef      | `(self, bytes resource, str resource_name, str folder)`           | Split-encrypt; CDN upload must succeed or raises; then small part via `upload_file` |

 ## Internal Logic

@@ -58,8 +52,8 @@ Central API client that orchestrates authentication, encrypted resource download
 ### Big/Small Resource Split (upload)
 1. Encrypts entire resource with shared resource key
 2. Splits: small part = `min(SMALL_SIZE_KB * 1024, 30% of encrypted)`, big part = remainder
-3. Uploads big part to CDN + saves local copy
-4. Uploads small part to API via multipart POST
+3. Calls `cdn_manager.upload` for the big part; raises if upload fails
+4. Writes big part to local cache, then uploads small part to API via `upload_file` (non-2xx responses propagate)

 ### JWT Role Mapping
 Maps `role` claim string to `RoleEnum`: ApiAdmin, Admin, ResourceUploader, Validator, Operator, or NONE (default).
@@ -89,7 +83,7 @@ The CDN config file is itself downloaded encrypted from the API on first credent

 ## External Integrations

- **Azaion Resource API**: `/login`, `/resources/get/{folder}`, `/resources/{folder}` (upload), `/resources/list/{folder}`, `/resources/check`
+- **Azaion Resource API**: `/login`, `/resources/get/{folder}`, `/resources/{folder}` (upload)
 - **S3 CDN**: via `CDNManager` for large file parts

 ## Security
@@ -11,7 +11,7 @@ Handles the encrypted Docker image archive workflow: downloading a key fragment
 | Function               | Signature                                                              | Description                                              |
 |------------------------|------------------------------------------------------------------------|----------------------------------------------------------|
 | `download_key_fragment`| `(resource_api_url: str, token: str) -> bytes`                         | GET request to `/binary-split/key-fragment` with Bearer auth |
-| `decrypt_archive`      | `(encrypted_path: str, key_fragment: bytes, output_path: str) -> None` | AES-256-CBC decryption with SHA-256 derived key; strips PKCS7 padding |
+| `decrypt_archive`      | `(encrypted_path: str, key_fragment: bytes, output_path: str) -> None` | AES-256-CBC stream decrypt with SHA-256 derived key; PKCS7 removed in-pipeline via unpadder |
 | `docker_load`          | `(tar_path: str) -> None`                                             | Runs `docker load -i <tar_path>` subprocess              |
 | `check_images_loaded`  | `(version: str) -> bool`                                              | Checks all `API_SERVICES` images exist for given version tag |

@@ -26,9 +26,8 @@ Handles the encrypted Docker image archive workflow: downloading a key fragment
 ### `decrypt_archive`
 1. Derives AES key: `SHA-256(key_fragment)` → 32-byte key
 2. Reads first 16 bytes as IV from encrypted file
-3. Decrypts remaining data in 64KB chunks using AES-256-CBC
-4. After decryption, reads last byte of output to determine PKCS7 padding length
-5. Truncates output file to remove padding
+3. Streams ciphertext in 64KB chunks through AES-256-CBC decryptor
+4. Feeds decrypted chunks through `padding.PKCS7(128).unpadder()`; writes unpadded bytes to the output file (`finalize` on decryptor and unpadder at end)

 ### `check_images_loaded`
 Iterates all 7 service image names, runs `docker image inspect <name>:<version>` for each. Returns `False` on first missing image.
@@ -36,7 +35,7 @@ Iterates all 7 service image names, runs `docker image inspect <name>:<version>`
 ## Dependencies

 - **Internal**: none (leaf module)
- **External**: `hashlib`, `os`, `subprocess` (stdlib), `requests` (2.32.4), `cryptography` (44.0.2)
+- **External**: `hashlib`, `subprocess` (stdlib), `requests` (2.32.4), `cryptography` (44.0.2)

 ## Consumers

@@ -8,15 +8,10 @@ Centralizes shared configuration constants and provides the application-wide log

 ### Constants (cdef, module-level)

-| Name                   | Type | Value                          |
-|------------------------|------|--------------------------------|
-| CONFIG_FILE            | str  | `"config.yaml"`                |
-| QUEUE_CONFIG_FILENAME  | str  | `"secured-config.json"`        |
-| AI_ONNX_MODEL_FILE    | str  | `"azaion.onnx"`                |
-| CDN_CONFIG             | str  | `"cdn.yaml"`                   |
-| MODELS_FOLDER          | str  | `"models"`                     |
-| SMALL_SIZE_KB          | int  | `3`                            |
-| ALIGNMENT_WIDTH        | int  | `32`                           |
+| Name          | Type | Value        |
+|---------------|------|--------------|
+| CDN_CONFIG    | str  | `"cdn.yaml"` |
+| SMALL_SIZE_KB | int  | `3`          |

 Note: `QUEUE_MAXSIZE`, `COMMANDS_QUEUE`, `ANNOTATIONS_QUEUE` are declared in the `.pxd` but not defined in the `.pyx` — they are unused in this codebase.

@@ -30,7 +25,7 @@ Note: `QUEUE_MAXSIZE`, `COMMANDS_QUEUE`, `ANNOTATIONS_QUEUE` are declared in the
 ## Internal Logic

 Loguru is configured with three sinks:
- **File sink**: `Logs/log_loader_{date}.txt`, INFO level, daily rotation, 30-day retention, async (enqueue=True)
+- **File sink**: under `LOG_DIR`, path template `log_loader_{time:YYYYMMDD}.txt`, INFO level, daily rotation, 30-day retention, async (enqueue=True)
 - **Stdout sink**: DEBUG level, filtered to INFO/DEBUG/SUCCESS only, colorized
 - **Stderr sink**: WARNING+ level, colorized

@@ -39,7 +34,7 @@ Log format: `[HH:mm:ss LEVEL] message`
 ## Dependencies

 - **Internal**: none (leaf module)
- **External**: `loguru` (0.7.3), `sys`, `time`
+- **External**: `loguru` (0.7.3), `os`, `sys`

 ## Consumers

@@ -53,7 +48,11 @@ None.

 ## Configuration

-No env vars consumed directly. Log file path is hardcoded to `Logs/log_loader_{date}.txt`.
+| Env Variable | Default | Description                          |
+|--------------|---------|--------------------------------------|
+| LOG_DIR      | `Logs`  | Directory for daily log files        |
+
+The file sink uses Loguru’s `{time:YYYYMMDD}` in the filename under `LOG_DIR`.

 ## External Integrations

@@ -33,29 +33,36 @@ FastAPI application entry point providing HTTP endpoints for health checks, auth

 ### Module-level State

-| Name           | Type               | Description                                    |
-|----------------|--------------------|------------------------------------------------|
-| api_client     | ApiClient or None  | Lazy-initialized singleton                     |
-| unlock_state   | UnlockState        | Current unlock workflow state                  |
-| unlock_error   | Optional[str]      | Last unlock error message                      |
-| unlock_lock    | threading.Lock     | Thread safety for unlock state mutations       |
+| Name              | Type                    | Description                                                    |
+|-------------------|-------------------------|----------------------------------------------------------------|
+| `_api_client`     | `ApiClient` or `None`   | Lazy-initialized singleton                                     |
+| `_api_client_lock`| `threading.Lock`        | Protects lazy initialization of `_api_client` (double-checked) |
+| `_unlock`         | `_UnlockStateHolder`    | Holds unlock workflow state and last error under an inner lock |
+
+#### `_UnlockStateHolder`
+
+| Member    | Description                                                                 |
+|-----------|-----------------------------------------------------------------------------|
+| `get()`   | Returns `(state: UnlockState, error: Optional[str])` under lock             |
+| `set(state, error=None)` | Sets state and optional error message under lock                 |
+| `state` (property) | Current `UnlockState` (read under lock)                              |

 ## Internal Logic

 ### `get_api_client()`
-Lazy singleton pattern: creates `ApiClient(RESOURCE_API_URL)` on first call.
+Double-checked locking: if `_api_client` is `None`, acquires `_api_client_lock`, re-checks, then imports `ApiClient` and constructs `ApiClient(RESOURCE_API_URL)` once.

 ### Unlock Workflow (`_run_unlock`)
 Background task (via FastAPI BackgroundTasks) that runs these steps:
-1. Check if Docker images already loaded → if yes, set `ready`
+1. Check if Docker images already loaded → if yes, set `ready` (preserving any prior error from `get()`)
 2. Authenticate with API (login)
 3. Download key fragment from `/binary-split/key-fragment`
 4. Decrypt archive at `IMAGES_PATH` → `.tar`
 5. `docker load` the tar file
-6. Clean up tar file
-7. Set state to `ready` (or `error` on failure)
+6. Remove tar file; on `OSError`, log a warning and continue
+7. Set state to `ready` with no error (or `error` on failure)

-State transitions are guarded by `unlock_lock` (threading.Lock).
+State and error are updated only through `_unlock.set()` and read via `_unlock.get()` / `_unlock.state`.

 ### `/unlock` Endpoint
 - If already `ready` → return immediately
@@ -65,8 +72,8 @@ State transitions are guarded by `unlock_lock` (threading.Lock).

 ## Dependencies

- **Internal**: `unlock_state` (UnlockState enum), `api_client` (lazy import), `binary_split` (lazy import)
- **External**: `os`, `threading` (stdlib), `fastapi`, `pydantic`
+- **Internal**: `UnlockState` from `unlock_state`, `get_api_client()` (lazy `api_client` import), `binary_split` (lazy import in unlock paths)
+- **External**: `os`, `threading` (stdlib), `fastapi`, `pydantic`, `loguru` (logger for tar cleanup warnings)

 ## Consumers

@@ -94,7 +101,7 @@ None — this is the entry point module.

 - Login endpoint returns 401 on auth failure
 - All resource endpoints use authenticated API client
- Unlock state is thread-safe via `threading.Lock`
+- Unlock state and error are guarded by `_UnlockStateHolder`’s lock; API client initialization is guarded by `_api_client_lock`
 - Lazy imports of Cython modules (`api_client`, `binary_split`) to avoid import-time side effects

 ## Tests
@@ -15,7 +15,7 @@ All methods are `@staticmethod cdef` — Cython-only visibility, not callable fr
 | Method                      | Signature                                                       | Description                                                          |
 |-----------------------------|-----------------------------------------------------------------|----------------------------------------------------------------------|
 | `encrypt_to`                | `(input_bytes, key) -> bytes`                                   | AES-256-CBC encrypt with random IV, PKCS7 padding; returns `IV + ciphertext` |
-| `decrypt_to`                | `(ciphertext_with_iv_bytes, key) -> bytes`                      | AES-256-CBC decrypt; first 16 bytes = IV; manual PKCS7 unpad        |
+| `decrypt_to`                | `(ciphertext_with_iv_bytes, key) -> bytes`                      | AES-256-CBC decrypt; first 16 bytes = IV; PKCS7 via `padding.PKCS7(128).unpadder()` |
 | `get_hw_hash`               | `(str hardware) -> str`                                         | Derives hardware hash: `SHA-384("Azaion_{hardware}_%$$$)0_")` → base64 |
 | `get_api_encryption_key`    | `(Credentials creds, str hardware_hash) -> str`                 | Derives per-user+hw key: `SHA-384("{email}-{password}-{hw_hash}-#%@AzaionKey@%#---")` → base64 |
 | `get_resource_encryption_key`| `() -> str`                                                    | Returns fixed shared key: `SHA-384("-#%@AzaionKey@%#---234sdfklgvhjbnn")` → base64 |
@@ -40,7 +40,7 @@ All methods are `@staticmethod cdef` — Cython-only visibility, not callable fr
 1. SHA-256 hash of string key → 32-byte AES key
 2. Split input: first 16 bytes = IV, rest = ciphertext
 3. AES-CBC decrypt
-4. Manual PKCS7 unpadding: read last byte as padding length; strip if 1–16
+4. PKCS7 removal via `cryptography` `padding.PKCS7(128).unpadder()` (`update` + `finalize`)

 ### Key Derivation Hierarchy
 - **Hardware hash**: salted hardware fingerprint → SHA-384 → base64
@@ -1,8 +1,8 @@
 # Dependencies Table

 **Date**: 2026-04-13
-**Total Tasks**: 5
-**Total Complexity Points**: 21
+**Total Tasks**: 8
+**Total Complexity Points**: 29

 | Task | Name | Complexity | Dependencies | Epic |
 |------|------|-----------|-------------|------|
@@ -11,6 +11,9 @@
 | 03 | test_resources | 5 | 01, 02 | Blackbox Tests |
 | 04 | test_unlock | 5 | 01, 02 | Blackbox Tests |
 | 05 | test_resilience_perf | 3 | 01, 02 | Blackbox Tests |
+| 06 | refactor_crypto_uploads | 3 | None | 01-quality-cleanup |
+| 07 | refactor_thread_safety | 3 | None | 01-quality-cleanup |
+| 08 | refactor_cleanup | 2 | 06 | 01-quality-cleanup |

 ## Execution Batches

@@ -19,6 +22,8 @@
 | 1 | 01_test_infrastructure | No | 5 |
 | 2 | 02_test_health_auth | No | 3 |
 | 3 | 03_test_resources, 04_test_unlock, 05_test_resilience_perf | Yes (parallel) | 13 |
+| 4 | 06_refactor_crypto_uploads, 07_refactor_thread_safety | Yes (parallel) | 6 |
+| 5 | 08_refactor_cleanup | No | 2 |

 ## Test Scenario Coverage

@@ -0,0 +1,77 @@
+# Fix Crypto Padding and Upload Error Handling
+
+**Task**: 06_refactor_crypto_uploads
+**Name**: Fix crypto padding and upload error propagation
+**Description**: Replace manual PKCS7 unpadding with library implementation and propagate upload failures instead of swallowing them
+**Complexity**: 3 points
+**Dependencies**: None
+**Component**: Security, Resource Management
+**Tracker**: PENDING
+**Epic**: PENDING (01-quality-cleanup)
+
+## Problem
+
+The decryption path uses manual PKCS7 padding removal that only checks the last byte instead of validating all padding bytes. Corrupted or tampered ciphertext silently produces garbage output. Additionally, resource upload failures (both CDN and API) are silently swallowed — the caller reports success when the upload actually failed.
+
+## Outcome
+
+- Decryption raises on invalid padding instead of returning garbage
+- Upload failures propagate to the HTTP endpoint and return appropriate error responses
+- The encrypt→decrypt roundtrip uses the same library for both directions
+
+## Scope
+
+### Included
+- Replace manual unpadding in Security.decrypt_to with library PKCS7 unpadder
+- Replace manual padding removal in binary_split.decrypt_archive with library unpadder
+- Check cdn_manager.upload return value in upload_big_small_resource
+- Let upload_file exceptions propagate instead of catching and logging
+
+### Excluded
+- Changing encryption (encrypt_to) — already uses the library correctly
+- Modifying CDNManager.upload/download internals
+- Changing the binary-split scheme itself
+
+## Acceptance Criteria
+
+**AC-1: Library unpadder in Security.decrypt_to**
+Given an encrypted resource produced by encrypt_to
+When decrypt_to is called
+Then it uses padding.PKCS7(128).unpadder() instead of manual byte inspection
+
+**AC-2: Library unpadder in decrypt_archive**
+Given an encrypted Docker image archive
+When decrypt_archive is called
+Then padding is removed using the cryptography library, not manual file truncation
+
+**AC-3: CDN upload failure raises**
+Given cdn_manager.upload returns False
+When upload_big_small_resource is called
+Then an exception is raised before the method returns
+
+**AC-4: API upload failure propagates**
+Given the Resource API is unreachable during upload
+When upload_file is called
+Then the exception propagates to the caller
+
+**AC-5: Roundtrip still works**
+Given a resource is uploaded via upload_big_small_resource
+When it is downloaded via load_big_small_resource
+Then the original content is returned unchanged
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| AC-5 | Docker services running | Upload then download a resource | Content matches original | — |
+
+## Constraints
+
+- security.pyx is Cython — changes must be valid Cython syntax
+- binary_split.py uses streaming file I/O — unpadding must work with the existing chunk-based approach
+
+## Risks & Mitigation
+
+**Risk 1: Existing encrypted data with non-standard padding**
+- *Risk*: If any previously encrypted data has irregular padding bytes, the library unpadder will raise ValueError
+- *Mitigation*: The e2e test_upload_download_roundtrip validates the full encrypt→decrypt path; all existing data was produced by encrypt_to which uses the same library padder
@@ -0,0 +1,66 @@
+# Thread Safety in Main Module
+
+**Task**: 07_refactor_thread_safety
+**Name**: Thread-safe singleton and encapsulated unlock state
+**Description**: Add thread-safe initialization for the ApiClient singleton and encapsulate unlock state management
+**Complexity**: 3 points
+**Dependencies**: None
+**Component**: HTTP API
+**Tracker**: PENDING
+**Epic**: PENDING (01-quality-cleanup)
+
+## Problem
+
+The ApiClient singleton in main.py is initialized without a lock — concurrent requests can create duplicate instances. The unlock workflow state is managed through module-level globals, scattering state transitions across multiple functions.
+
+## Outcome
+
+- ApiClient singleton initialization is thread-safe under concurrent HTTP requests
+- Unlock state is encapsulated in a dedicated holder with thread-safe accessors
+- No change to external behavior or API responses
+
+## Scope
+
+### Included
+- Add threading.Lock for ApiClient singleton initialization (double-checked locking)
+- Create a state holder class for unlock_state and unlock_error with lock-guarded methods
+- Update all unlock state reads/writes to use the holder
+
+### Excluded
+- Changing the ApiClient class itself (api_client.pyx)
+- Modifying the unlock workflow logic or state machine transitions
+- Adding new endpoints or changing API contracts
+
+## Acceptance Criteria
+
+**AC-1: Thread-safe singleton**
+Given multiple concurrent requests hitting any endpoint
+When get_api_client() is called simultaneously
+Then exactly one ApiClient instance is created
+
+**AC-2: Encapsulated unlock state**
+Given the unlock workflow is in progress
+When unlock/status is queried
+Then state is read through a thread-safe accessor, not via bare globals
+
+**AC-3: Existing behavior preserved**
+Given the current e2e test suite
+When all tests are run
+Then all 18 tests pass with no regressions
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| AC-3 | Docker services running | Full e2e suite | 18 passed, 0 failed | — |
+
+## Constraints
+
+- main.py is pure Python — no Cython syntax constraints
+- Must preserve FastAPI's BackgroundTasks compatibility for the unlock flow
+
+## Risks & Mitigation
+
+**Risk 1: Lock contention on high-concurrency paths**
+- *Risk*: Adding a lock to get_api_client could slow concurrent requests
+- *Mitigation*: Double-checked locking means the lock is only acquired once during initialization; subsequent calls check the fast path without locking
@@ -0,0 +1,75 @@
+# Dead Code Removal and Minor Fixes
+
+**Task**: 08_refactor_cleanup
+**Name**: Remove dead code, fix log path and error handling
+**Description**: Remove orphan methods and constants, make log path configurable, log os.remove failure
+**Complexity**: 2 points
+**Dependencies**: 06_refactor_crypto_uploads
+**Component**: Resource Management, Core Models, HTTP API
+**Tracker**: PENDING
+**Epic**: PENDING (01-quality-cleanup)
+
+## Problem
+
+The codebase contains 5 never-called methods in ApiClient and 8 orphan constant declarations. The log file path is hardcoded with no environment override. A file removal error is silently swallowed.
+
+## Outcome
+
+- Dead methods and constants are removed from source and declaration files
+- Log file directory is configurable via environment variable
+- File removal failure is logged instead of silently ignored
+- Codebase is smaller and cleaner with no behavioral regressions
+
+## Scope
+
+### Included
+- Delete 5 orphan methods from api_client.pyx: get_user, list_files, check_resource, upload_to_cdn, download_from_cdn
+- Delete corresponding declarations from api_client.pxd
+- Delete 5 unused constants from constants.pyx: CONFIG_FILE, QUEUE_CONFIG_FILENAME, AI_ONNX_MODEL_FILE, MODELS_FOLDER, ALIGNMENT_WIDTH
+- Delete 8 orphan declarations from constants.pxd (keep CDN_CONFIG, SMALL_SIZE_KB, log, logerror)
+- Make log directory configurable via LOG_DIR env var in constants.pyx
+- Replace bare except: pass with warning log in main.py _run_unlock
+
+### Excluded
+- Modifying any live code paths or method signatures
+- Changing the logging format or levels
+- Removing hardware_service.pyx silent catches (those are by-design for cross-platform compatibility)
+
+## Acceptance Criteria
+
+**AC-1: Dead methods removed**
+Given the source code
+When searching for get_user, list_files, check_resource, upload_to_cdn, download_from_cdn
+Then no definitions or declarations exist in api_client.pyx or api_client.pxd
+
+**AC-2: Dead constants removed**
+Given constants.pyx and constants.pxd
+When the files are inspected
+Then only CDN_CONFIG, SMALL_SIZE_KB, log, logerror declarations remain in the pxd
+
+**AC-3: Configurable log path**
+Given LOG_DIR environment variable is set
+When the application starts
+Then logs are written to the specified directory
+
+**AC-4: Error logged on tar removal failure**
+Given os.remove fails on the tar file during unlock
+When the failure occurs
+Then a warning-level log message is emitted
+
+**AC-5: No regressions**
+Given the current e2e test suite
+When all tests are run
+Then all 18 tests pass
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| AC-5 | Docker services running | Full e2e suite | 18 passed, 0 failed | — |
+
+## Risks & Mitigation
+
+**Risk 1: Removing a method that's called via dynamic dispatch**
+- *Risk*: A method could be invoked dynamically (getattr, etc.) rather than statically
+- *Mitigation*: All removed methods are cdef/cpdef — cdef methods cannot be called dynamically from Python; cpdef methods were grep-verified to have zero callers
@@ -0,0 +1,32 @@
+# Batch Report
+
+**Batch**: 4
+**Tasks**: 06_refactor_crypto_uploads, 07_refactor_thread_safety
+**Date**: 2026-04-13
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| 06_refactor_crypto_uploads | Done | 3 files | 18/18 pass | 4/4 ACs covered | None |
+| 07_refactor_thread_safety | Done | 1 file | 18/18 pass | 3/3 ACs covered | None |
+
+## AC Test Coverage: All covered
+## Code Review Verdict: PASS (manual review)
+## Auto-Fix Attempts: 0
+## Stuck Agents: None
+
+## Changes Summary
+
+### Task 06 (security.pyx, binary_split.py, api_client.pyx)
+- C03: Replaced manual PKCS7 unpadding with `padding.PKCS7(128).unpadder()` in `security.pyx`
+- C04: Integrated streaming PKCS7 unpadder into `decrypt_archive` pipeline in `binary_split.py`, removed post-hoc file truncation
+- C09: Added CDN upload return value check in `upload_big_small_resource`
+- C10: Removed exception swallowing in `upload_file` — errors now propagate
+
+### Task 07 (main.py)
+- C01: Double-checked locking for `get_api_client()` singleton
+- C02: Encapsulated unlock state in `_UnlockStateHolder` class with lock-guarded access
+- C06: Replaced silent `except OSError: pass` with `logger.warning`
+
+## Next Batch: 08_refactor_cleanup
@@ -0,0 +1,26 @@
+# Batch Report
+
+**Batch**: 5
+**Tasks**: 08_refactor_cleanup
+**Date**: 2026-04-13
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| 08_refactor_cleanup | Done | 4 files | 18/18 pass | 5/5 ACs covered | None |
+
+## AC Test Coverage: All covered
+## Code Review Verdict: PASS (manual review)
+## Auto-Fix Attempts: 0
+## Stuck Agents: None
+
+## Changes Summary
+
+### Task 08 (api_client.pyx, api_client.pxd, constants.pyx, constants.pxd)
+- C07: Removed 5 orphan methods from `api_client.pyx` and their declarations from `.pxd`
+- C08: Removed 5 orphan constants from `constants.pyx` and 7 orphan declarations from `constants.pxd`
+- C05: Made log path configurable via `LOG_DIR` environment variable (defaults to `Logs`)
+- Removed unused `import time` from `constants.pyx`
+
+## Next Batch: All tasks complete
@@ -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.
@@ -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 |
@@ -0,0 +1,97 @@
+# Baseline Metrics
+
+## Run Info
+
+- **Run**: 01-quality-cleanup
+- **Mode**: Automatic
+- **Date**: 2026-04-13
+
+## Source Metrics
+
+| Metric | Value |
+|--------|-------|
+| Source files | 11 |
+| Source LOC | 785 |
+| Test files | 6 |
+| Test LOC | 295 |
+| Endpoints | 7 |
+
+### Source File Breakdown
+
+| File | LOC | Type |
+|------|-----|------|
+| api_client.pyx | 222 | Cython |
+| main.py | 187 | Python |
+| hardware_service.pyx | 100 | Cython |
+| binary_split.py | 69 | Python |
+| security.pyx | 68 | Cython |
+| cdn_manager.pyx | 44 | Cython |
+| constants.pyx | 44 | Cython |
+| setup.py | 27 | Python |
+| unlock_state.py | 11 | Python |
+| credentials.pyx | 9 | Cython |
+| user.pyx | 6 | Cython |
+
+## Test Results (Last Run)
+
+| Metric | Value |
+|--------|-------|
+| Total tests | 18 |
+| Passed | 18 |
+| Failed | 0 |
+| Skipped | 0 |
+| Errors | 0 |
+| Duration | 12.87s |
+
+## Endpoint Inventory
+
+| Endpoint | Method | Tested | Notes |
+|----------|--------|--------|-------|
+| /health | GET | Yes | AC-1 |
+| /status | GET | Yes | AC-2 partial |
+| /login | POST | Yes | AC-2, AC-3 |
+| /load/{filename} | POST | Yes | AC-4 |
+| /upload/{filename} | POST | Yes | AC-5 |
+| /unlock | POST | Yes | AC-6, AC-7, AC-10 |
+| /unlock/status | GET | Yes | AC-8 |
+
+## Identified Issues
+
+| # | Issue | Location | Severity | Category |
+|---|-------|----------|----------|----------|
+| 1 | ApiClient singleton not thread-safe | main.py:20-25 | Medium | Race condition |
+| 2 | Global mutable unlock state | main.py:48-50 | Medium | Testability / thread safety |
+| 3 | Manual PKCS7 unpadding (incomplete validation) | security.pyx:38-44, binary_split.py:46-53 | Medium | Security / correctness |
+| 4 | Hardcoded log file path | constants.pyx:20 | Low | Configurability |
+| 5 | `os.remove` error silently swallowed | main.py:143-146 | Low | Error handling |
+| 6 | Dead code: 5 orphan methods + 5 orphan constants | api_client.pyx, constants.pyx | Low | Dead code |
+
+### Issue Details
+
+**Issue 1 — ApiClient singleton race condition**: `get_api_client()` checks `if api_client is None` and assigns without a lock. Under concurrent requests, two threads could create separate instances, the second overwriting the first.
+
+**Issue 2 — Global mutable unlock state**: `unlock_state` and `unlock_error` are module-level globals in `main.py`. They are protected by `unlock_lock` for writes, but the pattern of global state makes reasoning about state transitions harder and prevents running multiple unlock sequences.
+
+**Issue 3 — Manual PKCS7 unpadding**: `security.pyx:38-44` manually reads the last byte to determine padding length, but does not validate that all N trailing bytes equal N (as PKCS7 requires). Corrupted or tampered ciphertext silently produces garbage. If the last byte is outside 1-16, data is returned as-is with no error. The library's `padding.PKCS7(128).unpadder()` is already imported (line 8) and used for encryption — the same should be used for decryption. The same manual pattern exists in `binary_split.py:46-53` for archive decryption.
+
+**Issue 4 — Hardcoded log path**: `constants.pyx:20` writes to `"Logs/log_loader_{time:YYYYMMDD}.txt"` with no environment variable override. Works in Docker where `/app/Logs/` is the implicit path, but breaks or creates unexpected directories in other environments.
+
+**Issue 5 — Silent error swallowing**: `main.py:143-146` catches `OSError` on `os.remove(tar_path)` and passes silently. Per project rules, errors should not be silently suppressed.
+
+**Issue 6 — Dead code**: 5 orphan methods in `api_client.pyx` (`get_user`, `list_files`, `check_resource`, `upload_to_cdn`, `download_from_cdn`) — defined and declared in `.pxd` but never called from any source file. 5 orphan constants in `constants.pyx` (`CONFIG_FILE`, `QUEUE_CONFIG_FILENAME`, `AI_ONNX_MODEL_FILE`, `MODELS_FOLDER`, `ALIGNMENT_WIDTH`) — declared but never referenced outside their own file. Git history preserves them if ever needed again.
+
+## Dependencies
+
+| Package | Version | Used In |
+|---------|---------|---------|
+| fastapi | latest | main.py |
+| uvicorn[standard] | latest | server |
+| Cython | 3.1.3 | build |
+| requests | 2.32.4 | api_client, binary_split |
+| pyjwt | 2.10.1 | api_client |
+| cryptography | 44.0.2 | security, binary_split |
+| boto3 | 1.40.9 | cdn_manager |
+| loguru | 0.7.3 | constants |
+| pyyaml | 6.0.2 | api_client |
+| psutil | 7.0.0 | hardware_service |
+| python-multipart | latest | main.py (file upload) |
@@ -0,0 +1,44 @@
+# Logical Flow Analysis
+
+Traced all 6 documented flows (F1-F6) through actual code. Findings below.
+
+## F1 Authentication — No contradictions
+
+Flow matches documentation. `set_credentials_from_dict` → `set_credentials` → `load_bytes(CDN_CONFIG)` → triggers `login()` internally → downloads cdn.yaml → inits CDNManager. Naming (`set_credentials_from_dict`) understates what the method does, but behavior is correct.
+
+## F2 Resource Download — No contradictions
+
+`load_big_small_resource` correctly: downloads small part (API), checks local big part, falls back to CDN on decrypt failure. The `folder` parameter doubles as S3 bucket name and local directory — works by convention.
+
+## F3 Resource Upload — No contradictions
+
+`upload_big_small_resource` encrypts, splits at min(3KB, 30%), uploads big to CDN + local, small to API. Flow matches docs.
+
+## F4 Docker Unlock — Minor inefficiency
+
+`_run_unlock` calls `set_credentials_from_dict(email, password)` then `client.login()`. If the client is fresh, `set_credentials_from_dict` already triggers `login()` internally (through the CDN config download chain), making the explicit `login()` call redundant. Not a bug — just a wasted HTTP round-trip.
+
+## F5 Unlock Status — No contradictions
+
+Reads `unlock_state` and `unlock_error` under `unlock_lock`. Correct.
+
+## F6 Health/Status — No contradictions
+
+`/health` returns static response. `/status` reads `client.token`. Correct.
+
+## Strategic Note: Binary-Split Security Model May Be Obsolete
+
+The binary-split resource scheme (small part on API + big part on CDN) and the loader's key-fragment-based Docker unlock were designed for a specific threat model: distributing AI models to **end-user laptops** where the device is untrusted. The loader shipped only 99% of the model in the installer; the remaining 1% (first 3KB) was downloaded at runtime to prevent extraction.
+
+The software distribution model has since shifted to **SaaS** — services run on web servers or **Jetson Orin Nano** edge devices where the entire system can be secured via **TPM** (Trusted Platform Module). This makes the binary-split mechanism potentially unnecessary overhead.
+
+**Recommended investigation**: Evaluate whether TPM-based security on Jetson Orin Nano can replace the binary-split scheme entirely, simplifying the loader to a standard authenticated resource downloader. This is out of scope for the current refactoring run but should be tracked as a future architecture decision.
+
+## Additional Dead Code Found
+
+`constants.pxd` declares 3 variables never defined in `constants.pyx`:
+- `QUEUE_MAXSIZE` (line 3)
+- `COMMANDS_QUEUE` (line 4)
+- `ANNOTATIONS_QUEUE` (line 5)
+
+These are orphan forward declarations — no definition exists, and nothing references them. Added to Issue 6.
@@ -0,0 +1,50 @@
+# Execution Log
+
+**Run**: 01-quality-cleanup
+**Date**: 2026-04-13
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total tasks | 3 |
+| Batches | 2 |
+| Total changes | 10 (C01–C10) |
+| Files modified | 7 |
+| Tests before | 18 passed |
+| Tests after | 18 passed |
+
+## Batches
+
+### Batch 4: Crypto + Thread Safety (parallel)
+- **Tasks**: 06_refactor_crypto_uploads, 07_refactor_thread_safety
+- **Verdict**: PASS
+- **Report**: `_docs/03_implementation/batch_04_report.md`
+
+### Batch 5: Cleanup (sequential, depended on batch 4)
+- **Tasks**: 08_refactor_cleanup
+- **Verdict**: PASS
+- **Report**: `_docs/03_implementation/batch_05_report.md`
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| security.pyx | C03: Library PKCS7 unpadder |
+| binary_split.py | C04: Streaming PKCS7 unpadder |
+| api_client.pyx | C09: CDN upload check, C10: error propagation, C07: dead methods removed |
+| api_client.pxd | C07: dead declarations removed |
+| main.py | C01: thread-safe singleton, C02: unlock state holder, C06: log os.remove |
+| constants.pyx | C05: LOG_DIR env var, C08: dead constants removed, dead import removed |
+| constants.pxd | C08: dead declarations removed |
+
+## Blocked / Failed
+
+None.
+
+## Tracker Status
+
+Jira not authenticated — task statuses not updated. Pending transitions:
+- 06_refactor_crypto_uploads → Done
+- 07_refactor_thread_safety → Done
+- 08_refactor_cleanup → Done
@@ -0,0 +1,92 @@
+# List of Changes
+
+**Run**: 01-quality-cleanup
+**Mode**: automatic
+**Source**: self-discovered
+**Date**: 2026-04-13
+
+## Summary
+
+Address thread safety issues, replace unsafe manual cryptographic padding with library implementations, remove dead code, and fix minor configurability/error-handling gaps.
+
+## Changes
+
+### C01: Thread-safe ApiClient singleton
+- **File(s)**: main.py
+- **Problem**: `get_api_client()` checks `if api_client is None` and assigns without a lock. Concurrent requests can create duplicate instances, with the second overwriting the first.
+- **Change**: Protect the singleton initialization with a `threading.Lock` using the double-checked locking pattern.
+- **Rationale**: FastAPI serves concurrent requests via threads; the global singleton must be safe under concurrency.
+- **Risk**: low
+- **Dependencies**: None
+
+### C02: Encapsulate unlock state
+- **File(s)**: main.py
+- **Problem**: `unlock_state` and `unlock_error` are module-level globals mutated via a lock. This pattern scatters state management across the module and makes the state machine hard to reason about.
+- **Change**: Move unlock state and error into a small state holder class that encapsulates the lock and provides thread-safe read/write methods.
+- **Rationale**: Single Responsibility — state management belongs in one place, not spread across endpoint handlers and background tasks.
+- **Risk**: low
+- **Dependencies**: None
+
+### C03: Use library PKCS7 unpadder in Security.decrypt_to
+- **File(s)**: security.pyx
+- **Problem**: `decrypt_to` manually reads the last byte to determine padding length. It does not validate that all N trailing bytes equal N (PKCS7 requirement). Corrupted ciphertext silently produces garbage. The `padding.PKCS7(128).unpadder()` is already imported but unused for decryption.
+- **Change**: Replace manual unpadding (lines 38-44) with the library's `padding.PKCS7(128).unpadder()`, matching the encrypt path.
+- **Rationale**: The library validates all padding bytes and raises on corruption instead of silently returning garbage.
+- **Risk**: medium — changes decryption output on invalid input (correctly raises instead of silently passing)
+- **Dependencies**: None
+
+### C04: Use library PKCS7 unpadder in decrypt_archive
+- **File(s)**: binary_split.py
+- **Problem**: `decrypt_archive` manually reads the last byte of the decrypted file to strip padding (lines 46-53). Same incomplete PKCS7 validation as C03.
+- **Change**: After decryption, use the `cryptography` library's PKCS7 unpadder to strip padding instead of manual byte inspection and file truncation.
+- **Rationale**: Same as C03 — proper validation, raises on corruption.
+- **Risk**: medium — same reasoning as C03
+- **Dependencies**: None
+
+### C05: Configurable log file path
+- **File(s)**: constants.pyx
+- **Problem**: Log file sink is hardcoded to `"Logs/log_loader_{time:YYYYMMDD}.txt"`. No environment variable override. Creates unexpected directories outside Docker.
+- **Change**: Read the log directory from an environment variable (e.g., `LOG_DIR`) with the current value as default.
+- **Rationale**: Configurability across development and production environments.
+- **Risk**: low
+- **Dependencies**: None
+
+### C06: Log os.remove failure instead of swallowing
+- **File(s)**: main.py
+- **Problem**: `os.remove(tar_path)` catches `OSError` and passes silently (lines 143-146). Hides information about filesystem issues.
+- **Change**: Log the exception at warning level instead of silently passing.
+- **Rationale**: Per project rules, errors should not be silently suppressed.
+- **Risk**: low
+- **Dependencies**: None
+
+### C07: Remove dead methods from ApiClient
+- **File(s)**: api_client.pyx, api_client.pxd
+- **Problem**: 5 methods are defined and declared but never called from any source file: `get_user`, `list_files`, `check_resource`, `upload_to_cdn`, `download_from_cdn`.
+- **Change**: Delete the 5 orphan method definitions from `api_client.pyx` and their declarations from `api_client.pxd`.
+- **Rationale**: Dead code misleads readers and breaks when its dependencies evolve. Git history preserves it.
+- **Risk**: low
+- **Dependencies**: None
+
+### C08: Remove dead constants
+- **File(s)**: constants.pyx, constants.pxd
+- **Problem**: 5 constants in `constants.pyx` are never referenced outside their own file: `CONFIG_FILE`, `QUEUE_CONFIG_FILENAME`, `AI_ONNX_MODEL_FILE`, `MODELS_FOLDER`, `ALIGNMENT_WIDTH`. Additionally, 3 variables are declared in `constants.pxd` with no definition in `constants.pyx`: `QUEUE_MAXSIZE`, `COMMANDS_QUEUE`, `ANNOTATIONS_QUEUE`.
+- **Change**: Delete the 5 unused constant definitions from `constants.pyx` and all 8 orphan declarations from `constants.pxd` (keeping only `CDN_CONFIG`, `SMALL_SIZE_KB`, `log`, `logerror`).
+- **Rationale**: Dead code rots. Orphan `.pxd` declarations with no backing definition are especially misleading.
+- **Risk**: low
+- **Dependencies**: None
+
+### C09: CDN upload failure silently ignored
+- **File(s)**: api_client.pyx
+- **Problem**: `upload_big_small_resource` (line 203) calls `self.cdn_manager.upload()` which returns `False` on failure, but the return value is never checked. A failed CDN upload means the big part is only saved locally — the resource cannot be downloaded from other devices.
+- **Change**: Check the return value of `cdn_manager.upload` and raise on failure, matching the pattern in the (currently orphan) `upload_to_cdn` method.
+- **Rationale**: Silent upload failure leads to incomplete resources that cannot be downloaded from CDN on other devices.
+- **Risk**: medium — previously-silent failures will now raise exceptions
+- **Dependencies**: None
+
+### C10: API upload failure silently swallowed
+- **File(s)**: api_client.pyx
+- **Problem**: `upload_file` (line 91-102) catches all exceptions and only logs them. The caller (`upload_big_small_resource` at line 206) never knows the API upload failed. The small part is silently lost.
+- **Change**: Let the exception propagate to the caller instead of catching and logging. The caller's error handling (main.py endpoint) will convert it to an appropriate HTTP error.
+- **Rationale**: The upload endpoint should report failure, not return `{"status": "ok"}` when the small part was never uploaded.
+- **Risk**: medium — previously-silent failures will now raise exceptions
+- **Dependencies**: None
@@ -0,0 +1,30 @@
+# Existing Test Coverage Assessment
+
+**Suite**: 18 e2e blackbox tests (all passing)
+**Runner**: pytest via scripts/run-tests.sh
+**Last run**: 18 passed, 0 failed, 0 skipped (12.87s)
+
+## Coverage by Change
+
+| Change | Files | Covered By | Coverage |
+|--------|-------|------------|----------|
+| C03 | security.pyx (decrypt_to) | test_upload_download_roundtrip — exercises encrypt→decrypt full path | Full |
+| C04 | binary_split.py (decrypt_archive) | test_unlock_with_corrupt_archive — exercises decrypt path (error case) | Partial — no happy-path unlock test |
+| C09 | api_client.pyx (cdn upload check) | test_upload_resource, test_upload_download_roundtrip — upload happy path | Full |
+| C10 | api_client.pyx (upload_file propagation) | test_upload_resource — upload to API path | Full |
+| C01 | main.py (singleton) | All endpoint tests exercise get_api_client() | Full (sequential only) |
+| C02 | main.py (unlock state) | test_unlock_status_idle, test_unlock_missing_archive, test_unlock_concurrent_returns_current_state | Full |
+| C05 | constants.pyx (log path) | Indirect — service starts and logs | Sufficient |
+| C06 | main.py (os.remove log) | test_unlock_with_corrupt_archive — triggers _run_unlock | Partial |
+| C07 | api_client.pyx (dead methods) | N/A — deletion only, no behavior change | N/A |
+| C08 | constants.pyx (dead constants) | N/A — deletion only, no behavior change | N/A |
+
+## Assessment
+
+All public API endpoints are covered by blackbox tests. The critical refactoring paths — encrypt/decrypt roundtrip (C03), resource upload/download (C09/C10), and unlock state management (C02) — have dedicated e2e tests.
+
+**Gaps identified**:
+- No concurrency-specific test for C01 (singleton race). Sequential e2e tests exercise the singleton but don't stress concurrent access. Acceptable risk — the fix is a standard pattern.
+- C04 only has an error-path test (corrupt archive). No happy-path unlock test exists because it would require a real encrypted Docker image archive.
+
+**Conclusion**: Existing coverage is sufficient for the refactoring scope. No new tests needed before proceeding.
@@ -0,0 +1,13 @@
+# New Tests
+
+No new tests added. All new internal code paths are exercised by existing e2e tests:
+
+| New Code | Covered By |
+|----------|------------|
+| `_UnlockStateHolder` class | test_unlock_status_idle, test_unlock_missing_archive, test_unlock_concurrent_returns_current_state |
+| Double-checked locking in `get_api_client()` | All endpoint tests (each calls get_api_client) |
+| CDN upload exception raise | test_upload_resource, test_upload_download_roundtrip |
+| Library PKCS7 unpadder (security.pyx) | test_upload_download_roundtrip (encrypt→decrypt roundtrip) |
+| Library PKCS7 unpadder (binary_split.py) | test_unlock_with_corrupt_archive (error path) |
+| `upload_file` exception propagation | test_upload_resource |
+| `LOG_DIR` env var | Indirect (service starts successfully with default) |
@@ -0,0 +1,3 @@
+# Obsolete Tests
+
+None identified. Removed methods (get_user, list_files, check_resource, upload_to_cdn, download_from_cdn) and constants had no existing tests — they were orphans with no callers or test references.
@@ -0,0 +1,3 @@
+# Updated Tests
+
+No test updates required. All 18 e2e tests pass without modification — the refactoring preserved all public API contracts (endpoints, request/response formats, error codes).
@@ -0,0 +1,67 @@
+# Verification Report
+
+**Run**: 01-quality-cleanup
+**Date**: 2026-04-13
+
+## Test Results
+
+| Metric | Value |
+|--------|-------|
+| Total tests | 18 |
+| Passed | 18 |
+| Failed | 0 |
+| Skipped | 0 |
+| Duration | 18.11s |
+
+## Metric Comparison
+
+### Source LOC (same 11 files as baseline)
+
+| File | Baseline | Final | Delta |
+|------|----------|-------|-------|
+| api_client.pyx | 222 | 188 | -34 |
+| main.py | 187 | 199 | +12 |
+| hardware_service.pyx | 100 | 100 | 0 |
+| binary_split.py | 69 | 64 | -5 |
+| security.pyx | 68 | 64 | -4 |
+| cdn_manager.pyx | 44 | 45 | +1 |
+| constants.pyx | 44 | 38 | -6 |
+| setup.py | 27 | 28 | +1 |
+| unlock_state.py | 11 | 12 | +1 |
+| credentials.pyx | 9 | 10 | +1 |
+| user.pyx | 6 | 7 | +1 |
+| **Total** | **785** | **755** | **-30** |
+
+### Summary Metrics
+
+| Metric | Baseline | Final | Delta | Status |
+|--------|----------|-------|-------|--------|
+| Source LOC | 785 | 755 | -30 | Improved |
+| Test LOC | 295 | 369 | +74 | Improved |
+| Tests | 18 | 18 | 0 | Unchanged |
+| Test pass rate | 100% | 100% | 0 | Unchanged |
+| Endpoints | 7 | 7 | 0 | Unchanged |
+| Dead methods | 5 | 0 | -5 | Improved |
+| Dead constants | 5 | 0 | -5 | Improved |
+| Silent error paths | 3 | 0 | -3 | Improved |
+| Manual crypto | 2 | 0 | -2 | Improved |
+| Thread safety issues | 2 | 0 | -2 | Improved |
+
+### Acceptance Criteria
+
+| Criterion | Status | Evidence |
+|-----------|--------|----------|
+| C01: Thread-safe singleton | Met | Double-checked locking in main.py |
+| C02: Encapsulated unlock state | Met | _UnlockStateHolder with internal lock |
+| C03: Library PKCS7 in security.pyx | Met | padding.PKCS7(128).unpadder() replaces manual code |
+| C04: Library PKCS7 in binary_split.py | Met | Streaming unpadder integrated into decrypt pipeline |
+| C05: Configurable log path | Met | LOG_DIR env var with Logs default |
+| C06: Log os.remove failure | Met | logger.warning on OSError |
+| C07: Dead methods removed | Met | 5 methods deleted from api_client.pyx + .pxd |
+| C08: Dead constants removed | Met | 5 constants from .pyx + 7 declarations from .pxd |
+| C09: CDN upload check | Met | Exception raised on cdn_manager.upload() failure |
+| C10: Upload error propagation | Met | try/except removed from upload_file |
+
+## Regressions
+
+None.
@@ -2,8 +2,8 @@

 ## Current Step
 flow: existing-code
-step: 5
-name: Implement Tests
-status: completed
-sub_step: All batches done
+step: 7
+name: Refactor
+status: done
+sub_step: 7 — Phase 7 Documentation (complete)
 retry_count: 0