feat: uploadable user avatars with moderation

Avatar upload (crop dialog, medialibrary UUID storage), moderation
reporting + admin review queue, and per-user upload-block permission.

Computed GraphQL fields exposed via User @method accessors; mutations
in dedicated resolver classes. Admin dashboard refactored to be
data-driven via the navigation composable, with users nested under a
section folder so detail routes stay out of the nav tree.

nginx /storage static-serve added for dev (.lando) and prod
(client/.docker) so medialibrary uploads render.

WIP: recreated on fresh master; merged latest master (fallow,
record-of-review, login-oauth).

Author: wreality

.lando/default.conf.tpl

@@ -38,6 +38,15 @@ server {
         try_files /dev/null @backend;
     }
 
+    # Media-library uploads (avatars) live on the public disk, symlinked at
+    # public/storage. Serve them straight from disk — Laravel has no /storage
+    # route, and the generic location / below proxies non-text/html requests
+    # (like <img> loads) to the vite dev server, which answers with the SPA
+    # index.html (text/html) so the image never renders.
+    location /storage/ {
+        try_files $uri =404;
+    }
+
     # SPA navigation (Accept: text/html) goes to Laravel so index.blade.php can
     # inject runtime globals (__TELEMETRY_CONFIG, __APP_BANNER).
     # Everything else (JS modules, HMR, asset files) proxies to the vite dev server.

backend/Dockerfile

@@ -9,17 +9,18 @@ ARG TARGETARCH
 
 ARG PANDOC_VERSION=2.18
 ARG COMPOSE_WAIT_VERSION=2.7.3
-ARG PHP_EXTS="bcmath pdo_mysql pcntl zip intl gettext mysqli"
+ARG PHP_EXTS="bcmath pdo_mysql pcntl zip intl gettext mysqli exif gd"
 ARG PHP_PECL_EXTS="redis apcu xhprof"
-ARG APT_PACKAGES="openssl ca-certificates bash libzip-dev libaio1t64 libncurses6 libnuma1 libxml2-dev git libfcgi-bin sqlite3 default-mysql-client libicu-dev"
+ARG APT_PACKAGES="openssl ca-certificates bash libzip-dev libaio1t64 libncurses6 libnuma1 libxml2-dev git libfcgi-bin sqlite3 default-mysql-client libicu-dev libpng-dev libjpeg62-turbo-dev libwebp-dev libfreetype6-dev"
 #ENV COMPOSER_HOME=/tmp/composer
 ENV LOG_CHANNEL=stderr
 
 RUN  apt update && apt install -y ${APT_PACKAGES} \
+    && docker-php-ext-configure gd --with-jpeg --with-webp --with-freetype \
     && docker-php-ext-install -j$(nproc) ${PHP_EXTS} \
     && pecl install ${PHP_PECL_EXTS} \
     && docker-php-ext-enable ${PHP_PECL_EXTS} \
-    && apt purge libxml2-dev libzip-dev -y \
+    && apt purge libxml2-dev libzip-dev libpng-dev libjpeg62-turbo-dev libwebp-dev libfreetype6-dev -y \
     && rm -rf /var/lib/apt/lists/*
 
 RUN curl -Lo /wait https://github.com/ufoscout/docker-compose-wait/releases/download/${COMPOSE_WAIT_VERSION}/wait \

backend/app/GraphQL/Fields/UserAvatarBlockedField.php

@@ -0,0 +1,22 @@
+<?php
+declare(strict_types=1);
+
+namespace App\GraphQL\Fields;
+
+use App\Models\Permission;
+use App\Models\User;
+
+class UserAvatarBlockedField
+{
+    /**
+     * True when the user does not have the UPLOAD_AVATAR permission —
+     * either because a moderator revoked it, or (shouldn't happen, but
+     * defensive) because they were never granted it in the first place.
+     *
+     * @param array<string, mixed> $_args
+     */
+    public function __invoke(User $user, array $_args): bool
+    {
+        return !$user->hasPermissionTo(Permission::UPLOAD_AVATAR);
+    }
+}

backend/app/GraphQL/Fields/UserAvatarField.php

@@ -0,0 +1,32 @@
+<?php
+declare(strict_types=1);
+
+namespace App\GraphQL\Fields;
+
+use App\Models\User;
+
+class UserAvatarField
+{
+    /**
+     * Resolve the User.avatar field.
+     *
+     * Returns null when the user has not uploaded an avatar so the client
+     * can fall back to a placeholder.
+     *
+     * @param array<string, mixed> $_args
+     * @return array<string, string>|null
+     */
+    public function __invoke(User $user, array $_args): ?array
+    {
+        $media = $user->getAvatarMedia();
+        if ($media === null) {
+            return null;
+        }
+
+        return [
+            'url' => $media->getFullUrl(),
+            'thumb_url' => $media->getFullUrl('thumb'),
+            'medium_url' => $media->getFullUrl('medium'),
+        ];
+    }
+}

backend/app/GraphQL/Mutations/ReportUserAvatar.php

@@ -0,0 +1,52 @@
+<?php
+declare(strict_types=1);
+
+namespace App\GraphQL\Mutations;
+
+use App\Models\AvatarReport;
+use App\Models\User;
+use GraphQL\Error\Error;
+use Illuminate\Support\Facades\Auth;
+
+class ReportUserAvatar
+{
+    /**
+     * File (or return an existing pending) report against a user's avatar.
+     *
+     * @param array{userId: string, reason: ?string} $args
+     */
+    public function __invoke(null $_, array $args): AvatarReport
+    {
+        /** @var \App\Models\User|null $reporter */
+        $reporter = Auth::user();
+        if ($reporter === null) {
+            throw new Error('Authentication required.');
+        }
+
+        $reportedUser = User::findOrFail($args['userId']);
+
+        if ((string)$reportedUser->id === (string)$reporter->id) {
+            throw new Error('You cannot report your own avatar.');
+        }
+
+        if ($reportedUser->getAvatarMedia() === null) {
+            throw new Error('This user does not have an uploaded avatar to report.');
+        }
+
+        // Idempotent: one pending report per (reporter, reported) pair.
+        $existing = AvatarReport::where('user_id', $reportedUser->id)
+            ->where('reporter_user_id', $reporter->id)
+            ->where('status', AvatarReport::STATUS_PENDING)
+            ->first();
+        if ($existing !== null) {
+            return $existing;
+        }
+
+        return AvatarReport::create([
+            'user_id' => $reportedUser->id,
+            'reporter_user_id' => $reporter->id,
+            'reason' => $args['reason'] ?? null,
+            'status' => AvatarReport::STATUS_PENDING,
+        ]);
+    }
+}

backend/app/GraphQL/Mutations/ResolveAvatarReport.php

@@ -0,0 +1,86 @@
+<?php
+declare(strict_types=1);
+
+namespace App\GraphQL\Mutations;
+
+use App\Models\AvatarReport;
+use App\Models\Permission;
+use App\Models\User;
+use GraphQL\Error\Error;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Auth;
+
+class ResolveAvatarReport
+{
+    /**
+     * Dismiss a report without removing the avatar.
+     *
+     * @param array{id: string, notes: ?string} $args
+     */
+    public function dismiss(null $_, array $args): AvatarReport
+    {
+        return $this->resolve($args, AvatarReport::STATUS_DISMISSED, false);
+    }
+
+    /**
+     * Resolve a report and remove the reported user's avatar.
+     *
+     * @param array{id: string, notes: ?string, blockFutureUploads?: ?bool} $args
+     */
+    public function resolveAndRemove(null $_, array $args): AvatarReport
+    {
+        return $this->resolve($args, AvatarReport::STATUS_REMOVED, true);
+    }
+
+    /**
+     * @param array{
+     *     id: string,
+     *     notes: ?string,
+     *     blockFutureUploads?: ?bool
+     * } $args
+     */
+    private function resolve(array $args, string $status, bool $removeAvatar): AvatarReport
+    {
+        /** @var \App\Models\User|null $admin */
+        $admin = Auth::user();
+        if ($admin === null) {
+            throw new Error('Authentication required.');
+        }
+
+        /** @var \App\Models\AvatarReport $report */
+        $report = AvatarReport::findOrFail($args['id']);
+
+        if ($report->status !== AvatarReport::STATUS_PENDING) {
+            throw new Error('This report has already been resolved.');
+        }
+
+        if ($removeAvatar) {
+            $report->user->clearMediaCollection(User::AVATAR_COLLECTION);
+
+            if (!empty($args['blockFutureUploads'])) {
+                $report->user->revokePermissionTo(Permission::UPLOAD_AVATAR);
+            }
+
+            // Close out other pending reports against the same user — the
+            // avatar is gone, so they no longer need moderator attention.
+            AvatarReport::where('user_id', $report->user_id)
+                ->where('status', AvatarReport::STATUS_PENDING)
+                ->where('id', '!=', $report->id)
+                ->update([
+                    'status' => AvatarReport::STATUS_REMOVED,
+                    'resolved_by_user_id' => $admin->id,
+                    'resolved_at' => Carbon::now(),
+                    'resolution_notes' => 'Closed automatically when avatar was removed.',
+                ]);
+        }
+
+        $report->fill([
+            'status' => $status,
+            'resolved_by_user_id' => $admin->id,
+            'resolved_at' => Carbon::now(),
+            'resolution_notes' => $args['notes'] ?? null,
+        ])->save();
+
+        return $report->refresh();
+    }
+}

backend/app/GraphQL/Mutations/SetUserAvatarUploadBlocked.php

@@ -0,0 +1,31 @@
+<?php
+declare(strict_types=1);
+
+namespace App\GraphQL\Mutations;
+
+use App\Models\Permission;
+use App\Models\User;
+
+class SetUserAvatarUploadBlocked
+{
+    /**
+     * Grant or revoke the avatar-upload block on a user.
+     *
+     * @param array{userId: string, blocked: bool} $args
+     */
+    public function __invoke(null $_, array $args): User
+    {
+        /** @var \App\Models\User $user */
+        $user = User::findOrFail($args['userId']);
+
+        // "Blocking" means revoking the default UPLOAD_AVATAR permission;
+        // "unblocking" grants it back directly on the user.
+        if ($args['blocked']) {
+            $user->revokePermissionTo(Permission::UPLOAD_AVATAR);
+        } else {
+            $user->givePermissionTo(Permission::UPLOAD_AVATAR);
+        }
+
+        return $user->refresh();
+    }
+}

backend/app/GraphQL/Mutations/UpdateUserAvatar.php

@@ -0,0 +1,101 @@
+<?php
+declare(strict_types=1);
+
+namespace App\GraphQL\Mutations;
+
+use App\Models\Permission;
+use App\Models\User;
+use GraphQL\Error\Error;
+use Illuminate\Support\Facades\Validator;
+use Intervention\Image\Drivers\Gd\Driver;
+use Intervention\Image\ImageManager;
+use Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded;
+
+class UpdateUserAvatar
+{
+    /**
+     * Max upload size in kilobytes (5 MB).
+     */
+    private const MAX_SIZE_KB = 5 * 1024;
+
+    /**
+     * Upload or replace a user's avatar.
+     *
+     * @param array{id: string, avatar: \Illuminate\Http\UploadedFile} $args
+     */
+    public function upload(null $_, array $args): User
+    {
+        $user = User::findOrFail($args['id']);
+
+        if (!$user->hasPermissionTo(Permission::UPLOAD_AVATAR)) {
+            throw new Error('This user is not permitted to upload an avatar.');
+        }
+
+        $file = $args['avatar'];
+
+        Validator::make(
+            ['avatar' => $file],
+            ['avatar' => [
+                'required',
+                'file',
+                'mimetypes:' . implode(',', User::AVATAR_MIME_TYPES),
+                'max:' . self::MAX_SIZE_KB,
+            ]]
+        )->validate();
+
+        // Re-encode the image to strip EXIF (which may contain GPS
+        // coordinates or device info) and anything a crafted file might
+        // carry beyond pixel data.
+        $ext = strtolower($file->getClientOriginalExtension());
+        $cleanPath = $this->stripMetadata($file->getRealPath(), $ext);
+
+        try {
+            $user->addMedia($cleanPath)
+                ->usingFileName("avatar.{$ext}")
+                ->toMediaCollection(User::AVATAR_COLLECTION);
+        } catch (FileCannotBeAdded $e) {
+            throw new Error('Unable to store avatar: ' . $e->getMessage());
+        } finally {
+            if (file_exists($cleanPath)) {
+                unlink($cleanPath);
+            }
+        }
+
+        return $user->refresh();
+    }
+
+    /**
+     * Decode → re-encode an image using intervention/image, which drops
+     * EXIF and any ancillary metadata. Returns a path to a temp file the
+     * caller must clean up.
+     */
+    private function stripMetadata(string $sourcePath, string $extension): string
+    {
+        $manager = new ImageManager(new Driver());
+        $image = $manager->read($sourcePath);
+
+        $encoded = match ($extension) {
+            'jpg', 'jpeg' => $image->toJpeg(90),
+            'webp' => $image->toWebp(90),
+            default => $image->toPng(),
+        };
+
+        $tempPath = tempnam(sys_get_temp_dir(), 'avatar_');
+        file_put_contents($tempPath, (string)$encoded);
+
+        return $tempPath;
+    }
+
+    /**
+     * Remove a user's avatar.
+     *
+     * @param array{id: string} $args
+     */
+    public function delete(null $_, array $args): User
+    {
+        $user = User::findOrFail($args['id']);
+        $user->clearMediaCollection(User::AVATAR_COLLECTION);
+
+        return $user->refresh();
+    }
+}