admin/_docs/02_document/components/04_resource_management/description.md

Resource Management

Cycle 1 (2026-05-13) note — AZ-197 removed the Hardware field from GetResourceRequest and removed CheckResourceRequest and POST /resources/check entirely. AZ-183 introduced an OTA update path (POST /get-update, POST /resources/publish, IResourceUpdateService, Resource entity, resources table, ResourcesConfig.EncryptionMasterKey) but it was reverted later the same day after the security audit (finding F-1) — the OTA delivery model itself was deemed obsolete. The component is now back to filesystem-backed storage only.

1. High-Level Overview

Purpose: filesystem-backed storage — upload, list, download (per-user AES-encrypted), folder clearing, installer distribution. Owned by IResourcesService.

Architectural Pattern: a single service over the local filesystem. No DB access, no cache.

Upstream dependencies: Data Layer (ResourcesConfig), Authentication & Security (encryption via Security.EncryptTo).

Downstream consumers: Admin API (resource endpoints).

2. Internal Interfaces

Interface: IResourcesService

Method	Input	Output	Async	Error Types
GetInstaller	bool isStage	(string?, Stream?)	No	None (returns nulls if not found)
GetEncryptedResource	string? dataFolder, string fileName, string key, CancellationToken	Stream	Yes	FileNotFoundException
SaveResource	string? dataFolder, IFormFile data, CancellationToken	void	Yes	BusinessException(NoFileProvided)
ListResources	string? dataFolder, string? search, CancellationToken	IEnumerable<string>	Yes	DirectoryNotFoundException
ClearFolder	string? dataFolder	void	No	None

Input DTO:

GetResourceRequest (post-AZ-197):
  Password: string (required, min 8 chars)
  FileName: string (required, not empty)
  // Hardware field removed by AZ-197.

// CheckResourceRequest — REMOVED by AZ-197.
// GetUpdateRequest, PublishResourceRequest — added by AZ-183, removed in the post-cycle-1 revert.

3. External API Specification

N/A — exposed through Admin API.

4. Data Access Patterns

ResourcesService is filesystem-only — no DB access, no cache.

Source	Service	Pattern
Filesystem (ResourcesConfig.ResourcesFolder)	ResourcesService	Direct read/write/delete

Storage Estimates

• Filesystem: AI models, DLLs, installers — potentially hundreds of MB per file.

5. Implementation Details

State Management: stateless — reads/writes directly to filesystem.

Key Dependencies: none beyond BCL (System.IO).

Error Handling Strategy:

• SaveResource throws BusinessException(NoFileProvided) for null uploads.
• Missing files/directories throw standard .NET I/O exceptions.
• ClearFolder silently returns if directory doesn't exist.
• GetInstaller returns (null, null) tuple if installer file is not found.

6. Extensions and Helpers

Helper	Purpose	Used By
Security.EncryptTo	AES stream encryption	GetEncryptedResource
Security.GetApiEncryptionKey(email, password)	Per-user key derivation (post-AZ-197 — no hardware component)	Admin API (before calling GetEncryptedResource)

7. Caveats & Edge Cases

Known limitations (security-audit findings):

• F-2 (High) — no path traversal protection: dataFolder parameter is concatenated directly with ResourcesFolder. A malicious dataFolder like ../../etc could access arbitrary filesystem paths. Filed as separate ticket.
• SaveResource deletes existing file before writing — no versioning or backup.
• GetEncryptedResource loads the entire encrypted file into a MemoryStream — memory-intensive for large files.
• ListResources wraps a synchronous DirectoryInfo.GetFiles in Task.FromResult — not truly async.

Performance bottlenecks:

• Full file encryption to memory before streaming response: memory usage scales with file size.
• ClearFolder iterates and deletes files synchronously.

8. Dependency Graph

Must be implemented after: Data Layer (ResourcesConfig), Authentication & Security (encryption).

Can be implemented in parallel with: User Management.

Blocks: Admin API.

9. Logging Strategy

Log Level	When	Example
INFO	Successful file save	Resource {data.FileName} Saved Successfully

Log format: string interpolation via Serilog (security audit F-12 hygiene item: convert to structured form).

Log storage: console + rolling file (via Serilog configured in Program.cs).

Modules Covered

• Services/ResourcesService
• Common/Requests/GetResourceRequest (post-AZ-197 — no CheckResourceRequest, no Hardware field)
• Common/Configs/ResourcesConfig (the EncryptionMasterKey field added by AZ-183 was removed in the post-cycle-1 revert)