Add E2E tests, fix bugs

Made-with: Cursor
2026-04-22 10:16: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,81 @@
+# Module: security
+
+## Purpose
+
+Provides AES-256-CBC encryption/decryption and multiple key derivation strategies for API resource protection and hardware-bound access control.
+
+## Public Interface
+
+### Classes
+
+#### `Security` (cdef class)
+
+All methods are `@staticmethod cdef` — Cython-only visibility, not callable from pure Python.
+
+| 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        |
+| `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 |
+| `calc_hash`                 | `(str key) -> str`                                              | SHA-384 hash → base64 string                                        |
+
+### Module-level Constants
+
+| Name        | Value    | Status |
+|-------------|----------|--------|
+| BUFFER_SIZE | `65536`  | Unused — declared but never referenced |
+
+## Internal Logic
+
+### Encryption (`encrypt_to`)
+1. SHA-256 hash of string key → 32-byte AES key
+2. Generate random 16-byte IV
+3. PKCS7-pad plaintext to 128-bit block size
+4. AES-CBC encrypt
+5. Return `IV || ciphertext`
+
+### Decryption (`decrypt_to`)
+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
+
+### Key Derivation Hierarchy
+- **Hardware hash**: salted hardware fingerprint → SHA-384 → base64
+- **API encryption key**: combines user credentials + hardware hash + salt → SHA-384 → base64 (per-download key)
+- **Resource encryption key**: fixed salt string → SHA-384 → base64 (shared key for big/small resource split)
+
+## Dependencies
+
+- **Internal**: `credentials` (for `Credentials` type in `get_api_encryption_key`)
+- **External**: `base64`, `hashlib`, `os` (stdlib), `cryptography` (44.0.2)
+
+## Consumers
+
+- `api_client` — calls `encrypt_to`, `decrypt_to`, `get_hw_hash`, `get_api_encryption_key`, `get_resource_encryption_key`
+
+## Data Models
+
+None.
+
+## Configuration
+
+None.
+
+## External Integrations
+
+None.
+
+## Security
+
+- AES-256-CBC with PKCS7 padding for data encryption
+- SHA-384 for key derivation (with various salts)
+- SHA-256 for AES key expansion from string keys
+- `get_resource_encryption_key()` uses a hardcoded salt — the key is static and shared across all users
+- `get_api_encryption_key()` binds encryption to user credentials + hardware — per-user, per-machine keys
+
+## Tests
+
+No tests found.