Add E2E tests, fix bugs

Made-with: Cursor
2026-04-22 12:26:32 +00:00 · 2026-04-13 05:17:48 +03:00
parent 1f98b5e958
commit 8f7deb3fca
71 changed files with 4740 additions and 29 deletions
@@ -0,0 +1,102 @@
+# Security
+
+## 1. High-Level Overview
+
+**Purpose**: Provides AES-256-CBC encryption/decryption, multiple key derivation strategies, and OS-specific hardware fingerprinting for machine-bound access control.
+
+**Architectural Pattern**: Utility / Strategy — stateless static methods for crypto operations; hardware fingerprinting with caching.
+
+**Upstream dependencies**: Core Models (01) — uses `Credentials` type, `constants.log()`
+
+**Downstream consumers**: Resource Management (03) — `ApiClient` uses all Security and HardwareService methods
+
+## 2. Internal Interfaces
+
+### Interface: Security
+
+| Method                      | Input                                  | Output | Async | Error Types |
+|-----------------------------|----------------------------------------|--------|-------|-------------|
+| `encrypt_to`                | `bytes input_bytes, str key`           | bytes  | No    | cryptography errors |
+| `decrypt_to`                | `bytes ciphertext_with_iv, str key`    | bytes  | No    | cryptography errors |
+| `get_hw_hash`               | `str hardware`                         | str    | No    | —           |
+| `get_api_encryption_key`    | `Credentials creds, str hardware_hash` | str    | No    | —           |
+| `get_resource_encryption_key`| —                                     | str    | No    | —           |
+| `calc_hash`                 | `str key`                              | str    | No    | —           |
+
+All methods are `@staticmethod cdef` (Cython-only visibility).
+
+### Interface: HardwareService
+
+| Method              | Input | Output | Async | Error Types         |
+|---------------------|-------|--------|-------|---------------------|
+| `get_hardware_info` | —     | str    | No    | subprocess errors   |
+
+`@staticmethod cdef` with module-level caching in `_CACHED_HW_INFO`.
+
+## 3. External API Specification
+
+N/A — internal-only component.
+
+## 4. Data Access Patterns
+
+### Caching Strategy
+
+| Data            | Cache Type | TTL      | Invalidation  |
+|-----------------|-----------|----------|---------------|
+| Hardware info   | In-memory (module global) | Process lifetime | Never (static hardware) |
+
+## 5. Implementation Details
+
+**Algorithmic Complexity**: All crypto operations are O(n) in input size.
+
+**State Management**: HardwareService has one cached string; Security is fully stateless.
+
+**Key Dependencies**:
+
+| Library      | Version | Purpose                              |
+|--------------|---------|--------------------------------------|
+| cryptography | 44.0.2  | AES-256-CBC cipher, PKCS7 padding    |
+
+**Error Handling Strategy**:
+- Crypto errors propagate to caller (no catch)
+- `subprocess.check_output` in HardwareService raises `CalledProcessError` on failure
+
+**Key Derivation Hierarchy**:
+1. Hardware hash: `SHA-384("Azaion_{hw_string}_%$$$)0_")` → base64
+2. API encryption key: `SHA-384("{email}-{password}-{hw_hash}-#%@AzaionKey@%#---")` → base64 (per-user, per-machine)
+3. Resource encryption key: `SHA-384("-#%@AzaionKey@%#---234sdfklgvhjbnn")` → base64 (fixed, shared)
+4. AES key expansion: `SHA-256(string_key)` → 32-byte AES key (inside encrypt/decrypt)
+
+## 6. Extensions and Helpers
+
+None.
+
+## 7. Caveats & Edge Cases
+
+**Known limitations**:
+- `get_resource_encryption_key()` returns a fixed key — all users share the same resource encryption key
+- Hardware detection uses `shell=True` subprocess — injection risk if inputs were user-controlled (they are not)
+- Linux hardware detection may fail on systems without `lscpu`, `lspci`, or `/sys/block/sda`
+- Multiple GPUs: only the first GPU line is captured
+
+**Potential race conditions**:
+- `_CACHED_HW_INFO` is a module global written without locking — concurrent first calls could race, but the result is idempotent
+
+## 8. Dependency Graph
+
+**Must be implemented after**: Core Models (01)
+
+**Can be implemented in parallel with**: Resource Management (03) depends on this, so Security must be ready first
+
+**Blocks**: Resource Management (03)
+
+## 9. Logging Strategy
+
+| Log Level | When | Example |
+|-----------|------|---------|
+| INFO      | Hardware info gathered | `"Gathered hardware: CPU: ... GPU: ... Memory: ... DriveSerial: ..."` |
+| INFO      | Cached hardware reuse | `"Using cached hardware info"` |
+
+**Log format**: Via `constants.log()` — `[HH:mm:ss INFO] message`
+
+**Log storage**: Same as Core Models logging configuration