Oleksandr Bezdieniezhnykh
7.7 KiB
Azaion Admin API — Documentation Report
Executive Summary
The Azaion Admin API is a .NET 10.0 Minimal API serving as the backend management service for the Azaion Suite annotation platform. The codebase was fully documented bottom-up: 27 source modules across 4 .NET projects, assembled into 5 logical components, with system-level architecture, 7 flows, data model, and deployment documentation produced. The system manages users, authenticates via JWT, binds software to hardware fingerprints, and distributes AES-encrypted resources.
Problem Statement
The Azaion annotation platform requires centralized control over who can use its desktop software, on which physical machines, and with what permissions. The Admin API solves this by providing user lifecycle management with role-based access, hardware fingerprint binding to prevent unauthorized redistribution, and per-user encrypted resource delivery. It serves both human administrators (via an admin web panel) and desktop client applications.
Architecture Overview
The API follows a layered architecture: Data Layer (PostgreSQL via linq2db) → Services (UserService, AuthService, ResourcesService) → Minimal API endpoints. Components communicate via direct DI injection within a single process.
Technology stack: C# / .NET 10.0, ASP.NET Core Minimal API, PostgreSQL (linq2db 5.4.1 + Npgsql), JWT Bearer auth, AES-256-CBC encryption, Serilog logging, Swagger docs.
Deployment: Single Docker container on self-hosted Linux server, ARM64, Woodpecker CI, private registry.
Component Summary
| # | Component | Purpose | Dependencies |
|---|---|---|---|
| 01 | Data Layer | DB access, ORM mapping, entities, configs, caching | None (leaf) |
| 02 | User Management | User CRUD, hardware binding, role management | 01, 03 |
| 03 | Auth & Security | JWT tokens, password hashing, AES encryption | 01 |
| 04 | Resource Management | File upload/download, encrypted delivery | 01, 03 |
| 05 | Admin API | 17 HTTP endpoints, middleware, DI composition | 01, 02, 03, 04 |
Implementation order:
- Phase 1: Data Layer (01), Auth & Security (03) — no dependencies, can be parallel
- Phase 2: User Management (02), Resource Management (04) — depend on Phase 1
- Phase 3: Admin API (05) — composition root, depends on all
System Flows
| Flow | Description | Key Components |
|---|---|---|
| F1: User Login | Email/password validation → JWT token | API, User Mgmt, Auth |
| F2: User Registration | Admin creates user with role | API, User Mgmt |
| F3: Encrypted Resource Download | Hardware check → key derivation → AES encrypt → stream | API, Auth, User Mgmt, Resource Mgmt |
| F4: Hardware Check | First-time binding or hash comparison | API, Auth, User Mgmt |
| F5: Resource Upload | File save to server filesystem | API, Resource Mgmt |
| F6: Installer Download | Latest AzaionSuite.Iterative* file delivery |
API, Auth, Resource Mgmt |
| F7: User Management CRUD | Role change, enable/disable, delete | API, User Mgmt |
Risk Summary
| Level | Count | Key Risks |
|---|---|---|
| High | 2 | SHA-384 password hashing without per-user salt; no path traversal protection on resource endpoints |
| Medium | 4 | No UNIQUE constraint on email; hardcoded credentials in test; no rate limiting on login; encryption in memory limits file size |
| Low | 3 | apiUploaderPolicy dead code; hardware_hash unused DB column; no health check endpoint |
Test Coverage
| Component | Existing Tests | Coverage |
|---|---|---|
| Data Layer | 0 | None |
| User Management | 1 (integration, live DB) | CheckHardwareHash only |
| Auth & Security | 2 (encrypt/decrypt) | AES round-trip only |
| Resource Management | 0 | None |
| Admin API | 0 | None |
Overall acceptance criteria coverage: 2 / 28 ACs covered by existing tests (7%)
Key Decisions (from code analysis)
| # | Decision | Rationale | Alternatives Rejected |
|---|---|---|---|
| 1 | Minimal API over Controllers | Small endpoint count, minimal boilerplate | MVC Controllers |
| 2 | Read/Write DB connection separation | Enforce privilege levels | Single connection with app-level guards |
| 3 | Per-user resource encryption | Bind resources to specific user + hardware | Server-side access control only |
| 4 | Hardware fingerprint binding | Prevent software redistribution | License keys, online activation |
| 5 | linq2db over EF Core | Lightweight, no migration overhead | Entity Framework Core |
Open Questions
| # | Question | Impact | Assigned To |
|---|---|---|---|
| 1 | Should email column have a UNIQUE constraint? |
Race condition in registration could create duplicates | DBA / Developer |
| 2 | Is the hardware_hash DB column intentionally unused? |
Dead column wastes space, confuses schema readers | Developer |
| 3 | Should password hashing be upgraded to bcrypt/Argon2? | Current SHA-384 without salt is weak against rainbow tables | Security review |
| 4 | Should path traversal protection be added to resource endpoints? | dataFolder parameter allows arbitrary filesystem access |
Security review |
| 5 | Should apiUploaderPolicy be removed or applied? |
Dead code that suggests incomplete feature | Product owner |
Artifact Index
| File | Description |
|---|---|
_docs/00_problem/problem.md |
Problem statement |
_docs/00_problem/restrictions.md |
Technical and operational constraints |
_docs/00_problem/acceptance_criteria.md |
28 acceptance criteria derived from code |
_docs/00_problem/input_data/data_parameters.md |
DB schema, API schemas, config schemas |
_docs/00_problem/security_approach.md |
Authentication, authorization, encryption details |
_docs/01_solution/solution.md |
Solution description with architecture table |
_docs/02_document/00_discovery.md |
Codebase discovery (tree, tech stack, dependency graph) |
_docs/02_document/modules/ |
27 individual module documentation files |
_docs/02_document/components/01_data_layer/description.md |
Data Layer component spec |
_docs/02_document/components/02_user_management/description.md |
User Management component spec |
_docs/02_document/components/03_auth_and_security/description.md |
Auth & Security component spec |
_docs/02_document/components/04_resource_management/description.md |
Resource Management component spec |
_docs/02_document/components/05_admin_api/description.md |
Admin API component spec |
_docs/02_document/common-helpers/01_helper_extensions.md |
Extensions helper doc |
_docs/02_document/common-helpers/02_helper_business_exception.md |
BusinessException helper doc |
_docs/02_document/architecture.md |
System architecture (8 sections, 5 ADRs) |
_docs/02_document/system-flows.md |
7 system flows with sequence diagrams |
_docs/02_document/data_model.md |
Data model with ERD, ORM mapping, observations |
_docs/02_document/deployment/containerization.md |
Docker multi-stage build |
_docs/02_document/deployment/ci_cd_pipeline.md |
Woodpecker CI pipeline |
_docs/02_document/deployment/environment_strategy.md |
Environment config strategy |
_docs/02_document/deployment/observability.md |
Logging and monitoring status |
_docs/02_document/diagrams/components.md |
Component relationship diagram (Mermaid) |
_docs/02_document/diagrams/flows/flow_login.md |
Login flow diagram |
_docs/02_document/diagrams/flows/flow_encrypted_resource_download.md |
Encrypted download flow diagram |
_docs/02_document/diagrams/flows/flow_hardware_check.md |
Hardware check flowchart |
_docs/02_document/04_verification_log.md |
Verification results (87 entities, 3 corrections) |
_docs/02_document/FINAL_report.md |
This report |