[AZ-189] [AZ-190] [AZ-191] [AZ-192] [AZ-193] [AZ-194] [AZ-195] Add e2e blackbox test suite

Made-with: Cursor

_docs/02_document/components/03_auth_and_security/description.md

@@ -0,0 +1,87 @@
+# Authentication & Security
+
+## 1. High-Level Overview
+
+**Purpose**: JWT token creation/validation and cryptographic utilities (password hashing, hardware fingerprint hashing, AES file encryption/decryption).
+
+**Architectural Pattern**: Service + static utility — `AuthService` is a DI-managed service for JWT operations; `Security` is a static class for cryptographic primitives.
+
+**Upstream dependencies**: Data Layer (JwtConfig, IUserService for GetByEmail), ASP.NET Core (IHttpContextAccessor).
+
+**Downstream consumers**: Admin API (token creation on login, current user resolution), User Management (password hashing, hardware hashing), Resource Management (encryption key derivation, stream encryption).
+
+## 2. Internal Interfaces
+
+### Interface: IAuthService
+
+| Method | Input | Output | Async | Error Types |
+|--------|-------|--------|-------|-------------|
+| `GetCurrentUser` | (none — reads from HttpContext) | `User?` | Yes | None |
+| `CreateToken` | `User` | `string` (JWT) | No | None |
+
+### Static: Security
+
+| Method | Input | Output | Description |
+|--------|-------|--------|-------------|
+| `ToHash` | `string` | `string` (Base64) | SHA-384 hash |
+| `GetHWHash` | `string hardware` | `string` (Base64) | Salted hardware hash |
+| `GetApiEncryptionKey` | `string email, string password, string? hwHash` | `string` (Base64) | Derives AES encryption key |
+| `EncryptTo` | `Stream input, Stream output, string key, CancellationToken` | void | AES-256-CBC encrypt stream |
+| `DecryptTo` | `Stream encrypted, Stream output, string key, CancellationToken` | void | AES-256-CBC decrypt stream |
+
+## 3. External API Specification
+
+N/A — exposed through Admin API.
+
+## 4. Data Access Patterns
+
+No direct database access. `AuthService.GetCurrentUser` delegates to `IUserService.GetByEmail`.
+
+## 5. Implementation Details
+
+**Algorithmic Complexity**: Encryption/decryption is O(n) where n is file size, streaming in 512 KB buffers.
+
+**State Management**: `AuthService` is stateless (reads claims from HTTP context per request). `Security` is purely static.
+
+**Key Dependencies**:
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| System.IdentityModel.Tokens.Jwt | 7.1.2 | JWT token generation |
+| Microsoft.AspNetCore.Authentication.JwtBearer | 10.0.3 | JWT middleware integration |
+
+**Error Handling Strategy**:
+- `EncryptTo` throws `ArgumentNullException` for unreadable streams or empty keys.
+- JWT token creation does not throw (malformed config would cause runtime errors at middleware level).
+- `GetCurrentUser` returns null if claims are missing or user not found.
+
+## 6. Extensions and Helpers
+
+None — `Security` itself is a utility consumed by other components.
+
+## 7. Caveats & Edge Cases
+
+**Known limitations**:
+- Password hashing uses SHA-384 without per-user salt or key stretching. Not resistant to rainbow table attacks.
+- Hardware and encryption key salts are hardcoded constants.
+- `GetCurrentUserEmail` assumes `ClaimTypes.Name` is always present; accessing a missing key would throw `KeyNotFoundException`.
+- AES encryption prepends IV as first 16 bytes — consumers must know this format.
+
+**Performance bottlenecks**:
+- Large file encryption loads encrypted output into `MemoryStream` before sending — high memory usage for large files.
+
+## 8. Dependency Graph
+
+**Must be implemented after**: Data Layer (for JwtConfig, IUserService).
+
+**Can be implemented in parallel with**: User Management (shared dependency on Data Layer).
+
+**Blocks**: Admin API, Resource Management (uses encryption).
+
+## 9. Logging Strategy
+
+No explicit logging in AuthService or Security.
+
+## Modules Covered
+- `Services/AuthService`
+- `Services/Security`