[STORAGE]: Redesign file uploads as an authorized, validated lifecycle

[barry01-hash]

Context

Avatars, payout files, milestone evidence, and feedback need different ownership, visibility, retention, and validation rules. Treating storage as generic upload/delete operations risks orphaned objects and authorization drift.

Scope

• Define a file metadata model linking each object to owner, purpose, parent entity, size, MIME type, checksum, and lifecycle state.
• Use server-authorized signed upload/download flows; keep privileged storage credentials server-only.
• Enforce allowlists, byte limits, quotas, normalized object keys, and content verification.
• Add quarantine/scanning hooks before files become downloadable.
• Make replacement/deletion transactional through an outbox or cleanup worker.
• Add orphan detection and retention cleanup in dry-run and apply modes.

Acceptance criteria

• Users cannot read, replace, or delete another tenant’s private objects.
• File type validation checks content, not only extension or client MIME.
• Database failures do not leave permanently orphaned files.
• Public avatars and private evidence use explicit separate policies.
• Integration tests cover oversized, spoofed, duplicate, and unauthorized files.
• Storage lifecycle and incident cleanup runbooks are documented.

Relevant areas

manage-files/route.ts, upload-avatar/route.ts, files.service.ts, payout/profile schemas, Supabase storage configuration.