Auditor profile images on private Vercel Blob

Recommendation

Non-goals: Clerk profile images, public Blob storage, a full admin review screen in the first upload slice, or browser-side image trust/validation.

Confirmed current state

• next.config.ts is on Next.js 16.2.6 and currently has an empty images configuration.
• User.profileImages, ProfileImage, and File already exist. ProfileImage currently has only an approved boolean.
• The object-storage abstraction already supports private objects, presigned PUT/GET URLs, stable pathnames, and an expiresAt value.
• The Vercel provider defaults signed URLs to five minutes but already accepts a caller-provided lifetime.
• The shared Dropzone already owns file selection, validation state, progress, retry, and caller-supplied upload controllers.
• The auditor profile read/write boundary already lives in src/portals/auditor/profile; the route action files are thin adapters.
• The profile header currently renders a 54×54 MUI Avatar with an empty source and initials fallback.

Next.js image configuration

Use the exact private store hostname and restrict optimization to processed profile-image paths. Signed URLs contain query parameters, so do not set search: ''; that setting would reject every signed URL.

images: {
  remotePatterns: [
    {
      protocol: 'https',
      hostname: process.env.PROFILE_IMAGE_BLOB_HOSTNAME,
      port: '',
      pathname: '/profile-images/processed/**',
      // search intentionally omitted: signed URLs require query parameters
    },
    // Development only: the local mock host on port 9966, same pathname
  ],
  qualities: [75],
  formats: ['image/webp'],
  maximumRedirects: 0,
}

• Add a typed server/build variable such as PROFILE_IMAGE_BLOB_HOSTNAME. Its value is the exact <store-id>.private.blob.vercel-storage.com hostname, not a wildcard and not the token.
• Use Image inside the circular avatar container with explicit dimensions, sizes="54px", quality={75}, and objectFit: 'cover'.
• Keep one allowed quality until another surface proves it needs more. Width/height and sizes control dimensions; quality controls encoding.
• Add the local mock origin only in development so private-image behavior remains testable without widening production hosts.

Image upload lifecycle

1. Open: clicking the header avatar opens ActionDialog. Its body contains the shared Dropzone configured for one image, an explicit MIME allowlist, and a conservative byte limit.
2. Authorize: a thin server action calls auditorPortal.profile().images.createUploadTicket(). The portal resolves the current user; the browser never supplies a trusted user ID.
3. Ticket: create an immutable staging pathname under profile-images/staging/{userId}/{uuid}. Return a private presigned PUT URL lasting about 10 minutes, constrained by pathname, MIME type, operation, and maximum bytes.
4. Upload: a feature-owned DropzoneUploadController sends the file directly to the signed URL and reports progress. The shared Dropzone remains storage-provider-neutral.
5. Finalize: the client submits the issued pathname/ticket reference. The server rechecks ownership, reads the private staging object, validates actual bytes—not only the browser MIME—and rejects oversized dimensions or unsupported decoders.
6. Normalize: rotate from EXIF, strip metadata, resize within an agreed maximum, and encode a safe processed format. Upload to a new immutable pathname under profile-images/processed/{userId}/{uuid}.webp.
7. Persist: in one database transaction, create the File row with PRIVATE access and a ProfileImage row in PENDING. Supersede any older pending candidate for that user.
8. Clean up: delete the staging object after success. If DB persistence fails, delete the processed object as compensation. Record cleanup failures for later orphan reconciliation.
9. Display: the owner sees “Awaiting approval” in the dialog, but the profile header continues showing the most recent approved image or initials.

Signed URL and renewal policy

How the app decides to re-sign

• The server read model returns { imageId, url, expiresAt }. Serialize expiresAt as ISO text at the server/client boundary.
• A pure helper evaluates expiresAt - now <= renewalBuffer. Check on mount, when the tab becomes visible, when the browser comes back online, and from a one-shot timer scheduled for the renewal boundary.
• On image error, request one fresh URL and retry once. Do not create a retry loop.
• The refresh action re-queries the database and rechecks authorization and APPROVED status before signing. It does not trust the old pathname sent by the browser.
• Return signed-URL responses as non-cacheable application data. Never persist the URL in File, Prisma audit JSON, Sentry context, analytics, or console logs.

Types and data model

Reuse

• ObjectStorageAccess, CreateObjectUploadUrlInput, CreateObjectReadUrlInput, and SignedObjectUrl.
• DropzoneUploadController, DropzoneUploadResult, and DropzoneFileStatus.
• Prisma payload types derived with satisfies Prisma.*Select/Include, matching the existing profile read pattern.
• Zod schemas at action boundaries for upload-ticket, finalize, and admin-decision inputs.

Add or extend

Schema recommendation

Replace approved Boolean with status and review metadata: status, submittedAt, reviewedAt, reviewedByUserId, rejectionReason, width, and height. Make fileId unique so one stored file cannot back multiple profile-image records.

Add a migration-level partial unique index for one APPROVED row per userId. Backfill existing approved=true rows carefully before dropping the boolean.

Approval enforcement

1. Resource invariant: profile-image module/service methods own status transitions. Repositories perform persistence only.
2. Portal authorization: auditors may create, read, or withdraw their own pending candidates. Only an admin/superadmin ability may approve or reject.
3. Read policy: shared profile surfaces query approved images only. The owner modal and admin review surface use separate, explicitly scoped reads for pending rows.
4. Atomic decision: approval runs in one transaction: lock/recheck the candidate, mark the prior approved row REPLACED, mark the candidate APPROVED, and append the audit event.
5. Database guard: the partial unique index prevents two approved rows even if two admins act concurrently.
6. Notification seam: keep the future “notify admins/auditor” extension in the profile-image application/service method after the durable decision, not in the Blob provider or UI component.

Exception management and audit risks

Audit shape

Use the previously proposed append-only auditor-profile audit event pattern: actor ID, action, source, summary, structured changes, and optional before/after snapshots. Create the event in the same Prisma transaction as the status change. Recommended actions are profile_image.submitted, approved, rejected, replaced, and withdrawn.

Expected validation errors should return stable user-safe codes. Unexpected provider, processing, and persistence failures should use the existing Sentry capture helper with image/user correlation IDs and without signed URLs or sensitive metadata.

Implementation order

Validation and exit criteria

• Vitest covers URL renewal boundaries, upload constraints, state transitions, authorization, concurrent approval, and cleanup compensation.
• Prisma validation and the migration test confirm backfill plus the one-approved-row constraint. Apply any new migration locally before completion.
• Private Blob integration verifies: unsigned read fails; signed read succeeds; expired URL fails; pending image never appears in the standard profile read.
• next/image accepts the signed private URL, the local mock URL works in development, and no wildcard storage hostname is allowed in production.
• Uploading a replacement leaves the old approved avatar visible until approval; approval swaps it; rejection leaves it unchanged.
• Sentry/log inspection confirms signed URLs, Blob tokens, raw EXIF, and image bytes are absent.

Open product decisions

1. Maximum upload bytes and source pixel dimensions.
2. Normalized output size and whether cropping is automatic or user-controlled.
3. Whether former approved images are retained for audit, deleted immediately, or deleted after a retention window.
4. Whether seven-day revocation latency is acceptable. If not, use an authenticated image proxy.

Public technical references: Vercel Blob private storage, Vercel Blob signed URLs, and Next.js Image configuration.