Feature: Add Avatar Upload and Processing API

[3m1n3nc3]

Description

Add signed avatar upload, validation, processing, finalization, replacement, and deletion.

File Location

learnault-api/src/domain/assets/, profile routes/services, storage adapter/worker, and tests

Design Reference

API Roadmap Phase 1: Add Avatar Upload and Processing API.

Dependencies

• Status: Blocked
• Blocked by: Feature: Replace Mock User Helpers with Profile API; Feature: Add Transaction Outbox and Job Delivery Foundation
• Blocks: Integration suite

Tasks

• Define storage provider and development fake
• Issue short-lived user-scoped upload intent with size/type constraints
• Verify image and queue scan/metadata/resize processing
• Finalize approved variants atomically
• Retire replaced assets per lifecycle policy
• Test MIME spoofing, oversize, cross-user access, failures, replace, and delete

Acceptance Criteria

• Users cannot finalize/delete another user's object
• Invalid files never become active avatars
• Storage credentials are never returned
• Replacement/deletion follows policy
• Tests/OpenAPI pass

Verification Evidence

• Attach redacted upload flow and fake-provider security/processing tests

Difficulty

Advanced

[Lanhubs]

I can take ownership of this issue. Designing and implementing a secure, atomic, and multi-stage signed asset lifecycle—complete with constraint verification, background variant processing, and strict resource isolation—is an excellent match for my backend engineering workflow.

Proposed Implementation Strategy
Storage Provider & Fake Adapter: I will define a unified abstract storage adapter interface under learnault-api/src/domain/assets/. For local development and test runners, I will build a secure local fake provider that replicates remote behaviors (including failure states) without leaking structural network credentials or needing active cloud connections.

Presigned Upload Intent: I will create an endpoint to issue short-lived, cryptographically signed upload intents or pre-signed URLs. This mechanism enforces rigorous frontend constraints up front, validating file size and allowed image MIME types (image/jpeg, image/png, etc.) before the object ever touches your persistent layout.

Validation, Ingestion & Variant Processing: Once uploaded, the processing pipe will verify the asset payload. It will actively handle explicit validation checks against MIME-type spoofing (analyzing the actual file headers rather than trusting extension tags). Approved uploads will trigger image normalization, metadata extraction, and resizing into necessary thumbnail variants.

Atomic Replacement & Lifecycle Retirement: I will implement the asset finalization routine within the profile services layer. The swap will operate atomically to update the profile record and immediately flag replaced or orphaned avatar assets for deletion according to your retention policy.

Multi-Tenant Security Enforcement: Every finalization, read, or deletion request will be heavily guarded by absolute ownership checks. Users will only ever be permitted to mutate objects tied directly to their authenticated context, completely preventing cross-user access exploits.

Defensive Unit & Integration Tests: I will author an isolated suite of tests to thoroughly challenge the edge cases: blocking oversized uploads, rejecting malicious MIME-spoofed binaries, asserting exact cross-user isolation failures, and verifying that storage credentials are never leaked down to the client.

[grantfox-oss]

🦊 GrantFox — @Lanhubs has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #87)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.