feat: profile pictures — Gravatar fallback + custom upload

New users get a Gravatar-backed avatar automatically (computed from email
at signup); users can upload a custom photo instead via Settings, or
revert to the Gravatar/initials fallback. avatarUrl stays the single
resolved value (custom photo, OAuth photo, or precomputed Gravatar URL)
so every existing avatar-rendering spot across the app needs zero changes.

- users.hasCustomAvatar tracks whether avatarUrl is a real upload vs a
  computed Gravatar fallback, so "remove photo" knows what to revert to.
- New /api/v1/upload/avatar-presign route (session-scoped, generic —
  the existing recipe-photo presign route required a recipeId).
- CSP img-src needed www.gravatar.com added, or every browser blocks
  the fallback avatar outright.
- Settings page now reads avatarUrl from a fresh DB query instead of
  Better Auth's session object — the session cookie cache (5 min TTL)
  was serving a stale image right after upload, showing the initials
  fallback until the cache happened to expire.

Verified locally: signup auto-sets a Gravatar URL, upload persists
across reload, remove correctly reverts to Gravatar/initials.

apps/web/app/(app)/settings/page.tsx

@@ -12,7 +12,7 @@ export default async function SettingsPage() {
 
   const dbUser = await db.query.users.findFirst({
     where: eq(users.id, session.user.id),
-    columns: { bio: true, privateBio: true, isPrivate: true },
+    columns: { bio: true, privateBio: true, isPrivate: true, hasCustomAvatar: true, avatarUrl: true },
   });
 
   return (
@@ -20,11 +20,12 @@ export default async function SettingsPage() {
       user={{
         name: session.user.name,
         email: session.user.email,
-        image: session.user.image ?? null,
+        image: dbUser?.avatarUrl ?? null,
         locale: (session.user as { locale?: string }).locale ?? "en",
         bio: dbUser?.bio ?? null,
         privateBio: dbUser?.privateBio ?? null,
         isPrivate: dbUser?.isPrivate ?? false,
+        hasCustomAvatar: dbUser?.hasCustomAvatar ?? false,
       }}
     />
   );

apps/web/app/api/v1/upload/avatar-presign/route.ts

@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { requireSession } from "@/lib/api-auth";
+import { createPresignedUploadUrl } from "@/lib/storage";
+import { checkAndIncrementTierLimit, TierLimitError } from "@/lib/tiers";
+
+const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp", "image/avif"] as const;
+type AllowedType = (typeof ALLOWED_TYPES)[number];
+const MAX_FILE_SIZE = 5 * 1024 * 1024;
+
+const Schema = z.object({
+  contentType: z.string().refine((t): t is AllowedType => (ALLOWED_TYPES as readonly string[]).includes(t), {
+    message: "Content type must be jpeg, png, webp, or avif",
+  }),
+  fileSize: z.number().int().positive().max(MAX_FILE_SIZE, "File exceeds 5MB limit"),
+});
+
+export async function POST(req: NextRequest) {
+  const { session, response } = await requireSession();
+  if (response) return response;
+
+  const body = await req.json() as unknown;
+  const parsed = Schema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: "Validation error", issues: parsed.error.issues }, { status: 400 });
+  }
+
+  const { contentType, fileSize } = parsed.data;
+
+  try {
+    const sizeMb = Math.ceil(fileSize / (1024 * 1024));
+    await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "storage", sizeMb);
+  } catch (err) {
+    if (err instanceof TierLimitError) {
+      return NextResponse.json({ error: "Storage limit reached for your tier" }, { status: 403 });
+    }
+    throw err;
+  }
+
+  const ext = contentType.split("/")[1] ?? "jpg";
+  const key = `user-avatars/${session!.user.id}/${crypto.randomUUID()}.${ext}`;
+  const url = await createPresignedUploadUrl(key, contentType);
+
+  return NextResponse.json({ url, key });
+}

apps/web/app/api/v1/users/me/route.ts

@@ -3,6 +3,7 @@ import { headers } from "next/headers";
 import { auth } from "@/lib/auth/server";
 import { db, users, eq } from "@epicure/db";
 import { z } from "zod";
+import { gravatarUrl } from "@/lib/gravatar";
 
 const PatchSchema = z.object({
   name: z.string().min(1).max(100).optional(),
@@ -10,6 +11,8 @@ const PatchSchema = z.object({
   bio: z.string().max(500).optional().nullable(),
   privateBio: z.string().max(2000).optional().nullable(),
   isPrivate: z.boolean().optional(),
+  // A custom-uploaded avatar URL, or null to revert to the Gravatar fallback.
+  avatarUrl: z.string().url().max(2048).optional().nullable(),
 });
 
 export async function PATCH(req: Request) {
@@ -19,6 +22,18 @@ export async function PATCH(req: Request) {
   const body = PatchSchema.safeParse(await req.json());
   if (!body.success) return NextResponse.json({ error: body.error.flatten() }, { status: 400 });
 
-  await db.update(users).set(body.data).where(eq(users.id, session.user.id));
-  return NextResponse.json({ ok: true });
+  const { avatarUrl, ...rest } = body.data;
+  const updates: Partial<typeof users.$inferInsert> = { ...rest };
+  if (avatarUrl !== undefined) {
+    if (avatarUrl === null) {
+      updates.avatarUrl = gravatarUrl(session.user.email);
+      updates.hasCustomAvatar = false;
+    } else {
+      updates.avatarUrl = avatarUrl;
+      updates.hasCustomAvatar = true;
+    }
+  }
+
+  await db.update(users).set(updates).where(eq(users.id, session.user.id));
+  return NextResponse.json({ ok: true, avatarUrl: updates.avatarUrl });
 }

apps/web/components/settings/avatar-uploader.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import { useState, useRef } from "react";
+import { useTranslations } from "next-intl";
+import { toast } from "sonner";
+import { Camera, Loader2, X } from "lucide-react";
+import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";
+import { Button } from "@/components/ui/button";
+
+export function AvatarUploader({
+  name,
+  image,
+  hasCustomAvatar,
+  onChange,
+}: {
+  name: string;
+  image: string | null;
+  hasCustomAvatar: boolean;
+  onChange: (image: string | null, hasCustomAvatar: boolean) => void;
+}) {
+  const t = useTranslations("settingsForm");
+  const [uploading, setUploading] = useState(false);
+  const [preview, setPreview] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  async function handleFile(file: File) {
+    setUploading(true);
+    setPreview(URL.createObjectURL(file));
+    try {
+      const presignRes = await fetch("/api/v1/upload/avatar-presign", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ contentType: file.type, fileSize: file.size }),
+      });
+      if (!presignRes.ok) {
+        const err = await presignRes.json() as { error?: string };
+        toast.error(err.error ?? t("avatarUploadFailed"));
+        return;
+      }
+      const { url } = await presignRes.json() as { url: string; key: string };
+      await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": file.type } });
+
+      // The presigned PUT URL is already publicUrl/bucket/key with query-string
+      // signing params appended — strip those to get the plain public GET URL.
+      const saveRes = await fetch("/api/v1/users/me", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ avatarUrl: url.split("?")[0] }),
+      });
+      if (!saveRes.ok) {
+        toast.error(t("avatarUploadFailed"));
+        return;
+      }
+      const saved = await saveRes.json() as { avatarUrl?: string };
+      onChange(saved.avatarUrl ?? url.split("?")[0]!, true);
+      toast.success(t("avatarUploadSuccess"));
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  async function handleRemove() {
+    setUploading(true);
+    try {
+      const res = await fetch("/api/v1/users/me", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ avatarUrl: null }),
+      });
+      if (!res.ok) {
+        toast.error(t("avatarUploadFailed"));
+        return;
+      }
+      const saved = await res.json() as { avatarUrl?: string };
+      setPreview(null);
+      onChange(saved.avatarUrl ?? null, false);
+      toast.success(t("avatarRemoved"));
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return (
+    <div className="flex items-center gap-4">
+      <div className="relative">
+        <Avatar size="lg" className="size-16">
+          <AvatarImage src={preview ?? image ?? undefined} alt={name} />
+          <AvatarFallback className="text-lg">{name.slice(0, 2).toUpperCase()}</AvatarFallback>
+        </Avatar>
+        {uploading && (
+          <div className="absolute inset-0 flex items-center justify-center rounded-full bg-black/40">
+            <Loader2 className="h-5 w-5 animate-spin text-white" />
+          </div>
+        )}
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <input
+          ref={inputRef}
+          type="file"
+          accept="image/jpeg,image/png,image/webp,image/avif"
+          className="hidden"
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            if (file) void handleFile(file);
+            e.target.value = "";
+          }}
+        />
+        <Button type="button" variant="outline" size="sm" onClick={() => inputRef.current?.click()} disabled={uploading}>
+          <Camera className="h-4 w-4" />
+          {t("changePhoto")}
+        </Button>
+        {hasCustomAvatar && (
+          <button
+            type="button"
+            onClick={() => { void handleRemove(); }}
+            disabled={uploading}
+            className="flex items-center gap-1 text-xs text-muted-foreground hover:text-destructive transition-colors disabled:opacity-50"
+          >
+            <X className="h-3 w-3" />
+            {t("removePhoto")}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

apps/web/components/settings/settings-form.tsx

@@ -10,6 +10,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@
 import { Switch } from "@/components/ui/switch";
 import { useTranslations } from "next-intl";
 import { useLocale, SUPPORTED_LOCALES, type Locale } from "@/lib/i18n/provider";
+import { AvatarUploader } from "./avatar-uploader";
 
 type UserProps = {
   name: string;
@@ -19,6 +20,7 @@ type UserProps = {
   bio: string | null;
   privateBio: string | null;
   isPrivate: boolean;
+  hasCustomAvatar: boolean;
 };
 
 export function SettingsForm({ user }: { user: UserProps }) {
@@ -26,6 +28,8 @@ export function SettingsForm({ user }: { user: UserProps }) {
   const t_common = useTranslations("common");
   const { setLocale } = useLocale();
 
+  const [avatarImage, setAvatarImage] = useState(user.image);
+  const [hasCustomAvatar, setHasCustomAvatar] = useState(user.hasCustomAvatar);
   const [name, setName] = useState(user.name);
   const [bio, setBio] = useState(user.bio ?? "");
   const [privateBio, setPrivateBio] = useState(user.privateBio ?? "");
@@ -96,6 +100,15 @@ export function SettingsForm({ user }: { user: UserProps }) {
     <div className="space-y-6">
       <section className="rounded-xl border p-6 space-y-4">
         <h2 className="font-semibold text-lg">{t("profile")}</h2>
+        <AvatarUploader
+          name={user.name}
+          image={avatarImage}
+          hasCustomAvatar={hasCustomAvatar}
+          onChange={(image, custom) => {
+            setAvatarImage(image);
+            setHasCustomAvatar(custom);
+          }}
+        />
         <div className="space-y-2">
           <Label>{t("displayName")}</Label>
           <Input value={name} onChange={(e) => setName(e.target.value)} />

apps/web/lib/auth/server.ts

@@ -5,6 +5,7 @@ import { db, users, sessions, accounts, verifications, eq, count } from "@epicur
 import { sendEmail, verifyEmailHtml, resetPasswordHtml, welcomeHtml } from "@/lib/email";
 import { isSignupsDisabled } from "@/lib/site-settings";
 import { findValidInvite, consumeInvite, INVITE_COOKIE } from "@/lib/invites";
+import { gravatarUrl } from "@/lib/gravatar";
 
 export const auth = betterAuth({
   trustedOrigins: [process.env["BETTER_AUTH_URL"] ?? "http://localhost:3000"],
@@ -100,6 +101,13 @@ export const auth = betterAuth({
             await db.update(users).set({ role: "admin" }).where(eq(users.id, user.id));
           }
 
+          // Only email/password signups land here without an avatar already
+          // set (OAuth providers set `image` — mapped to avatarUrl — before
+          // this hook runs) — give them a Gravatar-backed default.
+          if (!user.image) {
+            await db.update(users).set({ avatarUrl: gravatarUrl(user.email) }).where(eq(users.id, user.id));
+          }
+
           // Consume the invite that gated this signup, if any (regardless of
           // whether signups have since been re-enabled/disabled).
           const token = context?.getCookie(INVITE_COOKIE);

apps/web/lib/gravatar.ts

@@ -0,0 +1,11 @@
+import { createHash } from "crypto";
+
+// Gravatar keys avatars by MD5 of the trimmed, lowercased email — no other
+// normalization is defined by their API.
+export function gravatarUrl(email: string, size = 200): string {
+  const hash = createHash("md5").update(email.trim().toLowerCase()).digest("hex");
+  // d=404 makes Gravatar 404 instead of serving a placeholder when no avatar
+  // is registered for the hash, so callers relying on <img onError> fallback
+  // (e.g. the Avatar component's initials fallback) behave correctly.
+  return `https://www.gravatar.com/avatar/${hash}?s=${size}&d=404`;
+}

apps/web/next.config.ts

@@ -35,7 +35,7 @@ const securityHeaders = [
       "default-src 'self'",
       "script-src 'self' 'unsafe-inline' 'unsafe-eval'", // unsafe-eval needed by Next.js dev; tighten in prod
       "style-src 'self' 'unsafe-inline'",
-      `img-src 'self' data: blob: ${storageOrigin}`,
+      `img-src 'self' data: blob: ${storageOrigin} https://www.gravatar.com`,
       "font-src 'self'",
       `connect-src 'self' ${storageOrigin}`,
       "frame-ancestors 'none'",

packages/db/src/migrations/0032_boring_layla_miller.sql

@@ -0,0 +1 @@
+ALTER TABLE "users" ADD COLUMN "has_custom_avatar" boolean DEFAULT false NOT NULL;

packages/db/src/schema/users.ts

@@ -19,6 +19,7 @@ export const users = pgTable("users", {
   emailVerified: boolean("email_verified").notNull().default(false),
   name: text("name").notNull(),
   avatarUrl: text("avatar_url"),
+  hasCustomAvatar: boolean("has_custom_avatar").notNull().default(false),
   bio: text("bio"),
   privateBio: text("private_bio"),
   isPrivate: boolean("is_private").notNull().default(false),