Oleksandr Bezdieniezhnykh
6.9 KiB
Azaion.Loader — Documentation Report
Executive Summary
Azaion.Loader is a Cython/Python microservice that securely distributes encrypted AI model resources and Docker service images to ARM64 edge devices. The codebase consists of 10 modules organized into 4 components, built around a binary-split encryption scheme and hardware-bound key derivation. No test suite exists — creating one is the recommended next step.
Problem Statement
Edge devices running Azaion's AI/drone services need a self-contained way to authenticate against a central API, download encrypted resources (using a split-storage scheme for security), and bootstrap their Docker environment by decrypting and loading pre-deployed image archives. All security-critical logic must be IP-protected through compiled native extensions.
Architecture Overview
The system is a single-container FastAPI service that delegates to Cython-compiled modules for encryption, key derivation, and API communication. It uses a binary-split storage model where resources are encrypted and split between an authenticated REST API (small part) and an S3-compatible CDN (large part). Docker image archives are decrypted using a server-provided key fragment and loaded via Docker CLI.
Technology stack: Python 3.11 + Cython 3.1.3, FastAPI/Uvicorn, AES-256-CBC (cryptography), boto3 (S3 CDN), Docker CLI
Deployment: Single Docker container on ARM64 edge devices, built via Woodpecker CI, pushed to local registry
Component Summary
| # | Component | Purpose | Dependencies |
|---|---|---|---|
| 01 | Core Models | Shared constants, data types (Credentials, User, UnlockState), logging | — |
| 02 | Security | AES-256-CBC encryption, key derivation, hardware fingerprinting | 01 |
| 03 | Resource Management | API client, CDN operations, binary-split resource scheme, Docker unlock | 01, 02 |
| 04 | HTTP API | FastAPI endpoints — thin controller | 01, 03 |
Implementation order:
- Phase 1: Core Models (01) — no dependencies
- Phase 2: Security (02) — depends on Core Models
- Phase 3: Resource Management (03) — depends on Core Models + Security
- Phase 4: HTTP API (04) — depends on Core Models + Resource Management
System Flows
| Flow | Description | Key Components |
|---|---|---|
| F1 Authentication | Login → JWT → CDN config init | 04, 03, 02 |
| F2 Resource Download | Small part (API) + big part (CDN/local) → decrypt → return | 04, 03, 02 |
| F3 Resource Upload | Encrypt → split → small to API, big to CDN | 04, 03, 02 |
| F4 Docker Unlock | Auth → key fragment → decrypt archive → docker load | 04, 03 |
| F5 Unlock Status Poll | Read current unlock state | 04 |
| F6 Health/Status | Liveness + readiness probes | 04 |
See system-flows.md for full sequence diagrams and flowcharts.
Risk Summary
| Level | Count | Key Risks |
|---|---|---|
| High | 2 | No test suite; JWT decoded without signature verification |
| Medium | 4 | No endpoint authorization; shared resource encryption key; synchronous I/O for large files; race condition on ApiClient singleton |
| Low | 3 | Unused dependencies (psutil); dead code declarations; hardcoded log path |
Test Coverage
No tests exist. Coverage is 0% across all categories.
| Component | Integration | Performance | Security | Acceptance | AC Coverage |
|---|---|---|---|---|---|
| 01 Core Models | 0 | 0 | 0 | 0 | 0/18 |
| 02 Security | 0 | 0 | 0 | 0 | 0/18 |
| 03 Resource Mgmt | 0 | 0 | 0 | 0 | 0/18 |
| 04 HTTP API | 0 | 0 | 0 | 0 | 0/18 |
Overall acceptance criteria coverage: 0 / 18 (0%)
Key Decisions (Inferred from Code)
| # | Decision | Rationale | Alternatives Rejected |
|---|---|---|---|
| 1 | Cython for IP protection | Prevent reverse-engineering of security logic | Pure Python (too readable), Rust (ecosystem mismatch) |
| 2 | Binary-split resource storage | Security: compromise of one storage is insufficient | Single encrypted download (bandwidth cost), unencrypted CDN (security risk) |
| 3 | Docker CLI via subprocess | Simplicity for Docker-in-Docker on edge devices | Docker Python SDK (extra dependency), external image loading (not self-contained) |
| 4 | Hardware-bound key derivation | Tie resource access to specific physical machines | Software-only licensing (easily transferable), hardware dongles (extra hardware) |
Open Questions
| # | Question | Impact | Assigned To |
|---|---|---|---|
| 1 | Should JWT signature verification be enabled? | Security — currently trusts API server blindly | Team |
| 2 | Is psutil needed or can it be removed from requirements? |
Cleanup — unused dependency | Team |
| 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
| File | Description |
|---|---|
_docs/00_problem/problem.md |
Problem statement |
_docs/00_problem/restrictions.md |
Hardware, software, environment restrictions |
_docs/00_problem/acceptance_criteria.md |
18 acceptance criteria |
_docs/00_problem/input_data/data_parameters.md |
Data schemas and sources |
_docs/00_problem/security_approach.md |
Security architecture |
_docs/01_solution/solution.md |
Solution overview |
_docs/02_document/00_discovery.md |
Codebase discovery |
_docs/02_document/modules/*.md |
10 module-level docs |
_docs/02_document/components/01_core_models/description.md |
Core Models component spec |
_docs/02_document/components/02_security/description.md |
Security component spec |
_docs/02_document/components/03_resource_management/description.md |
Resource Management component spec |
_docs/02_document/components/04_http_api/description.md |
HTTP API component spec |
_docs/02_document/architecture.md |
System architecture |
_docs/02_document/system-flows.md |
System flow diagrams |
_docs/02_document/data_model.md |
Entity data model |
_docs/02_document/deployment/containerization.md |
Docker containerization |
_docs/02_document/deployment/ci_cd_pipeline.md |
Woodpecker CI pipeline |
_docs/02_document/deployment/observability.md |
Logging and health checks |
_docs/02_document/diagrams/components.md |
Component relationship diagram |
_docs/02_document/04_verification_log.md |
Verification pass results |
_docs/02_document/FINAL_report.md |
This report |