File Storage

@repo/storage handles file uploads behind one provider-agnostic API, gated by config.storage.enabled in packages/config/src/index.ts. When enabled it persists files to an S3-compatible bucket or the local filesystem; when off, isStorageEnabled() returns false, POST /storage/upload responds 503, and upload UI is hidden.

What you get

• Avatar uploads: uploadAvatar() with per-user mutex, atomic swap, and rollback on DB failure.
• Quotas: per-user daily upload cap (429 over limit; admins bypass).
• Rate limiting: per-IP burst limit on the upload endpoint.
• MIME + magic-byte validation: only real jpeg/png/gif/webp pass; renamed files are rejected.
• Public vs private: two buckets. Public files (avatars, assets) go to the public bucket and get a URL; private files (the default) go to the private bucket and return url: null.

Configuration

config.storage is a discriminated union - { enabled: false } or the full shape. The shipped default is on:

storage: { enabled: true, provider: "s3", maxFileSizeMB: 5, dailyUploadLimit: 20 }

Credentials live in environment variables, not config - see Environment variables.

Providers

• s3 reads STORAGE_REGION, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, and two buckets - STORAGE_PUBLIC_BUCKET (publicly readable: avatars, assets) and STORAGE_PRIVATE_BUCKET (credentials-only: private uploads) - plus optional STORAGE_PUBLIC_URL (the public bucket's CDN or custom domain).
• local reads STORAGE_LOCAL_PATH (default ../../data) and optional STORAGE_LOCAL_PUBLIC_URL; LocalProvider serves only the public/ prefix and blocks path-traversal, absolute-path, and null-byte attacks.

Public and private buckets

The s3 provider uses two buckets so the bucket boundary - not a key prefix - is the privacy guarantee:

• STORAGE_PUBLIC_BUCKET holds public files (avatars, assets). Give it a custom domain or r2.dev URL so the files are anonymously readable, and point STORAGE_PUBLIC_URL at that base.
• STORAGE_PRIVATE_BUCKET holds private uploads. Leave it credentials-only; the app reads those files back through readFile() behind your own auth check.

Public objects are stored under a public/ key prefix, which also tells deleteFile/readFile which bucket a key belongs to. Don't make the private bucket public: on Cloudflare R2 a custom domain exposes the whole bucket, so keeping public and private in separate buckets is what keeps private uploads private.

Upload endpoint

The shared backend exposes POST /storage/upload, guarded by authGuard and a per-IP rate limiter (10 requests / 60s). It accepts multipart/form-data with a file field plus optional folder, then enforces, in order:

A folder of avatars routes to uploadAvatar() (per-user mutex + atomic DB swap); any other folder lands under {userId}/{folder}. Endpoint uploads are always public - they return a served URL.

Programmatically, uploadFile(file, filename, contentType, { folder, visibility }) defaults to visibility: "private" (returns url: null); pass "public" to land under a public/ prefix and get a URL.

Rate limiting and quotas

Two Redis-backed limits, keyed from cacheConfig in packages/config/src/cache.ts:

checkDailyUploadQuota() increments the counter and compares it against dailyUploadLimit. See Caching for the Redis store wiring.

Frequently asked questions

Why does uploadFile() return url: null? The programmatic helper defaults to visibility: "private". Pass { visibility: "public" } to land under the public/ prefix and get a served URL. (The POST /storage/upload endpoint always uploads public, so it never returns null.)

Can I switch from local to s3 after launch? Yes - flip config.storage.provider and set the STORAGE_* env vars. Old keys keep their paths; deleteFileFromAllProviders() cleans up across both during the transition.

How are images resized? Avatars are resized and center-cropped to 256x256 WebP on the client before upload, so no server-side image library runs in the request path.