File Storage

Upload, download, list, and delete files. Supports public and private visibility with HMAC-signed URLs for private file access.

Use case: Allow users to upload profile pictures, documents, or any binary files. Private files can only be accessed by their uploader or admins, or via a time-limited signed URL.

How It Works

1. Files are uploaded via multipart form to POST /files/upload.
2. The StorageManager validates MIME type and per-user storage quota.
3. Files are stored on disk with UUID-based names in separate public/ and private/ directories.
4. Metadata (name, MIME type, size, uploader, visibility) is recorded in the _files SQLite table.
5. Private files require a signed URL generated by GET /files/:id/signed-url. The URL includes an HMAC token and expiry timestamp; it is verified on download.

Storage Structure

<project-root>/
  storage/
    public/         <- Publicly downloadable files
      <uuid>.jpg
      <uuid>.png
    private/        <- Signed-URL-only files
      <uuid>.pdf
      <uuid>.docx

Access URLs

Visibility	Download URL	Auth Required
public	/files/:id/download	No
private	/files/:id/download?token=<hmac>&expires=<unix-ts>	Signed URL (HMAC-SHA256)

Signed URLs are generated via GET /files/:id/signed-url. The default TTL is 1 hour, configurable via signedUrlTTLSeconds in config.

Size and Quota Limits

Setting	Environment Variable	Default
Max file size	ROTIFEX_STORAGE_MAX_FILE_SIZE_MB	10 MB
Max storage per user	Config only (maxStoragePerUserMB)	100 MB