Avatar uploads on Settings → Profile (replace URL-only field with file upload)

[bdunncompany]

Avatar uploads for user profiles (replacing the URL-only field)

Title suggestion: Avatar uploads on Settings → Profile (replace URL-only field with file upload)

Category: Ideas / Feature requests

---

The problem

The Settings → Profile screen only lets users set an avatar by pasting a publicly-reachable HTTPS URL into a text field. That URL is stored on users.avatar_url and rendered with an <img src>. This has two practical problems:

1. Air-gapped or LAN-only self-hosts have nowhere to host the image. A user on a Tailscale-only or LAN-only Breeze instance can't put an image somewhere their browser can reach without going outside the perimeter.
2. Deployments behind an identity-aware proxy break the avatar silently. If a user tries to "host" the image on their own Breeze instance (or any other CF-Access-protected origin), the proxy returns a 302 to the login page for unauthenticated image requests. <img> can't follow that, so the avatar shows up blank. No error, no feedback, just no picture.

Concrete example: I'm running Breeze behind Cloudflare Access on a self-host. There's no URL I can paste into the field that renders, short of using a third-party image host. Every other tool in this category (and every SaaS in general) just lets you upload a file from the profile screen.

Even leaving aside the proxy case, "paste an internet-reachable URL" is friction that other products have abandoned. A <input type="file"> on the profile page covers the 90% case directly.

Proposed solution

Replace the URL field with a file upload. Files land on the existing api_data Docker named volume, the same one apps/api/src/services/fileStorage.ts already uses for remote/transfers. No new infrastructure required; no new dependencies; no schema migration.

Storage

/data/avatars/<userId>.<ext> on the api_data volume.

• Survives container recreate and image bumps (which the in-container filesystem would not).
• Mirrors the established pattern: ./data/transfers (chunked transfers), ./data/patch-reports (patch reports), etc.
• A 1,000-user instance with 256-ish-pixel images is ~50 MB on disk. Object storage is overkill at this scale.
• If you'd prefer S3-only (e.g. for the hosted SaaS where api may scale horizontally), isS3Configured() is already wired and we can branch the same way apps/api/src/routes/software.ts:642 does. Filesystem first, S3 as Phase 2 if needed, or the other way round if you'd rather not back up a new volume on hosted.

API

Three new endpoints under existing userRoutes (apps/api/src/routes/users.ts):

• POST /api/v1/users/me/avatar: multipart upload, single file field
  • MIME allowlist: image/png, image/jpeg, image/webp (no SVG to avoid embedded-JS XSS, no GIF in v1)
  • Magic-byte verification on the first bytes (don't trust Content-Type)
  • 5 MB cap
  • Writes /data/avatars/<userId>.<ext> atomically (write .tmp + rename())
  • Sets users.avatar_url = '/api/v1/users/<userId>/avatar'
  • Audit log entry: user.avatar.upload
• GET /api/v1/users/:id/avatar: auth-required, streams the bytes, Cache-Control: private, max-age=300, weak ETag (mtime + size). Returns 404 when no avatar set so the frontend falls back to initials.
• DELETE /api/v1/users/me/avatar: unlinks the file, sets avatar_url = NULL, audit log entry.

No image-processing dependency in v1. The 5 MB cap is the backstop against abuse. If anyone asks for server-side resize later, sharp can be added without changing the storage layout.

UI

Replace the URL <input> block in apps/web/src/components/settings/ProfilePage.tsx with:

• 96px avatar preview
• "Upload new picture" button (and drag-and-drop onto the preview circle)
• "Remove" button (only shown when an avatar is set)
• Helper text: "PNG, JPG, or WebP. Max 5 MB."

Known gotcha worth flagging up front: <img src> can't send Bearer auth

If the GET endpoint requires Authorization, <img src="/api/v1/users/<id>/avatar"> 401s, since the browser doesn't send the Bearer header for image requests. Two reasonable options:

• Option A (what I went with): a small client-side blob-cache helper that fetches the bytes via the same fetchWithAuth everything else uses, turns the response into an object URL, and feeds that to <img>. About 150 lines, refcounted across the topbar, dropdown, and profile preview so the bytes are fetched once. No server change required.
• Option B: authenticate the GET via the session cookie (which <img> does send automatically). Simpler client, but requires the route to accept cookie-auth in addition to Bearer, and CSRF considerations apply to a GET in a way they don't otherwise.

Either is defensible. Worth deciding before a PR lands so there's a single canonical approach in tree.

Schema

No changes. users.avatar_url text already exists and gets reused.

Migration

None forced. Existing rows with external URLs keep rendering as-is. On the next profile save (or first upload), the field becomes the new internal /api/v1/users/<userId>/avatar path. The PATCH validator at apps/api/src/routes/users.ts either drops avatarUrl from the schema (so upload is the only set path) or gets loosened to accept the internal path too. See open question 2 below.

Open questions for the maintainer

1. Filesystem vs S3-only. I'd lean toward filesystem first (/data/avatars/ on api_data volume) as the lowest-friction path for the self-hosted majority. Is hosted SaaS OK with that, or does api scale horizontally enough that filesystem isn't shared, in which case S3-only on hosted + filesystem-or-S3 on self-hosted is a better split?
2. Keep the URL field as a secondary input, or remove entirely? I'd remove it (cleaner, kills the third-party-tracking-pixel side effect), but if there's any client out there that PATCHes avatarUrl directly via the API (mobile? portal? external integration?), I'd keep it as a power-user fallback.
3. Rate limiting. Is there an existing per-user limiter I should hook into for the upload endpoint? Couldn't find one in a quick grep. Happy to add a small per-user bucket if not.
4. Image transforms in v1. OK shipping without sharp (relying on the 5 MB cap and CSS to render small), or want server-side resize on day 1?
5. <img> auth: blob fetch vs cookie auth. (See gotcha above.) Which would you prefer in tree?

Scope of work

File	Change
apps/api/src/routes/users.ts	Add 3 endpoints, drop avatarUrl from PATCH schema (or loosen it)
apps/api/src/services/avatarStorage.ts (new)	Filesystem helpers + magic-byte check, mirrors fileStorage.ts pattern
apps/api/src/routes/users.test.ts	Tests for new endpoints, MIME rejection, size cap, magic-byte rejection
apps/web/src/components/settings/ProfilePage.tsx	Replace URL field with upload UI; wire DELETE; refresh auth store
apps/web/src/lib/avatarBlobCache.ts (new, only if Option A)	Refcounted blob-URL cache so <img> can render an auth'd path
apps/web/src/components/settings/ProfilePage.test.tsx	Tests for upload + delete + invalid file feedback
docs/	One short page on avatar storage layout

Roughly +500 LoC net, no new deps, no migration file, no env vars.

State of the work

I have all of the above implemented and running on my self-host instance. Tests pass, the upload/render/delete cycle works end-to-end in Chrome and Safari, and the topbar, dropdown, and profile preview all show the uploaded avatar via the blob-cache hook (Option A). Happy to open a PR, just want a quick read on questions 1, 2, and 5 first so the PR matches what you'd merge.

[ToddHebebrand]

Thanks @bdunncompany — well-scoped, and the gotcha section on <img> + Bearer auth is the right thing to surface upfront. Decisions on your five:

1. Both paths via the existing isS3Configured() gate. Storage helper checks isS3Configured() (apps/api/src/services/s3Storage.ts:37–39), writes to avatars/<userId>.<ext> in S3 if configured, falls back to ${AVATAR_STORAGE_PATH:-./data/avatars}/<userId>.<ext> on filesystem otherwise. This mirrors the gate at apps/api/src/routes/software.ts:642.

Worth being explicit on intent: any deployment running more than one API instance needs S3 — filesystem on a Docker volume is single-instance only and doesn't survive horizontal scale-out. The filesystem path is the right default for the self-host single-container case (one operator, one box, one volume), but treat S3 as the production path. Add AVATAR_STORAGE_PATH to docker-compose.yml alongside TRANSFER_STORAGE_PATH and PATCH_REPORT_STORAGE_PATH so the self-host default lives on the same api_data volume, and document the S3 requirement in the same place we document it for the software catalog.

2. Remove the URL field cleanly — no fallback. No mobile or external callers PATCH avatarUrl directly. Keeping the URL field around as a "power-user fallback" preserves a third-party-tracking-pixel surface for very little benefit — anyone running their own Breeze that wants an externally-hosted avatar can still upload the image once.

Migration: existing rows with external URLs keep rendering as-is (the <img> doesn't care about the storage backend); on next profile save the field gets overwritten with the internal /api/v1/users/<userId>/avatar path. Drop avatarUrl from the PATCH updateMeSchema (apps/api/src/routes/users.ts:439–445) so the upload endpoint is the only write path. Don't soft-deprecate — just remove it from the input schema.

3. No sharp, do the resize client-side. sharp is not a current dependency, and the size-on-the-wire concern (5MB raw × every page that renders avatars) is real even with Cache-Control: private, max-age=300. Front-load the work in the browser:

• On file select in ProfilePage.tsx, use canvas.toBlob() to resize to 256×256 webp (jpeg fallback for older browsers), targeting ~100KB
• Server-side, drop the cap from 5MB to 1MB and reject anything larger — there's no legitimate reason to upload a >1MB pre-resized avatar
• Server still validates: magic bytes, MIME allowlist (png/jpeg/webp, no SVG/GIF)

This sidesteps the sharp install (50MB native dep), keeps the server stateless re: image processing, and gives users a faster upload too.

4. Rate limiting: add it. 5 uploads per hour per user. No existing per-user limiter — apps/api/src/services/rate-limit.ts has per-IP login/password-reset limiters but nothing per-user. Add an avatarUploadLimiter config (limit: 5, windowSeconds: 3600), key it as avatar:upload:<userId>, and use the existing rateLimiter(getRedis(), key, limit, windowSeconds) helper. 5/hour is generous enough for legitimate "I tried three crops" usage and tight enough that abuse hits the wall fast.

5. <img> auth: go with Option A (blob fetch). Two reasons:

• The refresh cookie is httpOnly + sameSite=lax and is strictly a refresh-token cookie (apps/api/src/routes/auth/helpers.ts) — it's not validated as a general session cookie on arbitrary GETs. Reusing it for image auth would require a parallel auth path on the GET endpoint, and that's the kind of "two auth modes on one route" that produces subtle CSRF/cache bugs later.
• We don't have any existing pattern in the SPA for auth'd binary content via <img>, so whatever you build here becomes the pattern. Blob-fetch via fetchWithAuth is consistent with everything else in the SPA.

One thing to bake into the helper: bust the blob URL cache on upload and delete events (otherwise users see their old avatar until next page load). Refcounted with a manual invalidate-by-userId is enough; don't over-engineer it.

Cross-cutting: the GET endpoint needs the same tenant scoping as getScopedUser (apps/api/src/routes/users.ts:220–260) — partner-scoped users can only fetch avatars for users in their partner; org-scoped users only within their org. Reuse the helper rather than duplicating the scoping logic, and make sure the 404 path is identical whether the user genuinely has no avatar or the requester doesn't have permission to see them (don't leak existence). Same audit log policy as other user-mutation routes (actorType: 'user').

Open as draft when ready.

[ToddHebebrand]

Shipped in #1059 (merged 2026-06-08). Settings → Profile now has a real file-upload avatar replacing the URL-only field: magic-byte format sniff (rejects SVG/non-image even when extension lies), size cap, atomic temp+rename write, traversal-guarded path, and authed-blob serving via a tenant-scoped GET /:id/avatar (own-avatar short-circuit, same-404 no-enumeration for foreign ids). Upload → render → Remove all verified in-browser. Closing as resolved.