feat(033): implement upload trust level feature

Co-authored-by: ildyria <627094+ildyria@users.noreply.github.com>

Author: Copilot

app/Actions/Photo/Create.php

@@ -145,6 +145,7 @@ private function handleDuplicate(InitDTO $init_dto): Photo
 		}
 		$pipes[] = Duplicate\ThrowSkipDuplicate::class;
 		$pipes[] = Shared\SetHighlighted::class;
+		$pipes[] = Shared\SetUploadValidated::class;
 		$pipes[] = Shared\Save::class;
 		$pipes[] = Shared\SetParent::class;
 		$pipes[] = Shared\SaveStatistics::class;
@@ -171,16 +172,8 @@ private function handleStandalone(InitDTO $init_dto): Photo
 			Shared\HydrateMetadata::class,
 			Shared\SetHighlighted::class,
 			Shared\SetOwnership::class,
+			Shared\SetUploadValidated::class,
 			Standalone\SetOriginalChecksum::class,
-			Standalone\FetchSourceImage::class,
-			Standalone\ExtractGoogleMotionPictures::class,
-			Standalone\PlacePhoto::class,
-			Standalone\PlaceGoogleMotionVideo::class,
-			Standalone\SetChecksum::class,
-			Standalone\AutoRenamer::class,
-			Shared\Save::class,
-			Shared\SetParent::class,
-			Shared\SaveStatistics::class,
 			Standalone\CreateOriginalSizeVariant::class,
 			Standalone\CreateRawSizeVariant::class,
 			Standalone\CreateSizeVariants::class,
@@ -267,6 +260,7 @@ private function handlePhotoLivePartner(InitDTO $init_dto): Photo
 			Shared\HydrateMetadata::class,
 			Shared\SetHighlighted::class,
 			Shared\SetOwnership::class,
+			Shared\SetUploadValidated::class,
 			Standalone\SetOriginalChecksum::class,
 			Standalone\FetchSourceImage::class,
 			Standalone\ExtractGoogleMotionPictures::class,

app/Actions/Photo/Pipes/Shared/SetUploadValidated.php

@@ -0,0 +1,71 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Actions\Photo\Pipes\Shared;
+
+use App\Contracts\PhotoCreate\SharedPipe;
+use App\DTO\PhotoCreate\DuplicateDTO;
+use App\DTO\PhotoCreate\StandaloneDTO;
+use App\Enum\UserUploadTrustLevel;
+use App\Models\User;
+use App\Repositories\ConfigManager;
+
+/**
+ * Determines and sets the `is_upload_validated` flag on the photo being created.
+ *
+ * Rules (evaluated in order):
+ *  1. If the intended owner exists and is an admin (`may_administrate`), always validated (true).
+ *  2. If there is no authenticated owner (guest upload), use the `guest_upload_trust_level` config.
+ *  3. Otherwise use the owner's `upload_trust_level`.
+ *
+ * Trust level mapping:
+ *  - CHECK   → not validated (false)
+ *  - MONITOR → validated (true)  — behaves as TRUSTED in this iteration
+ *  - TRUSTED → validated (true)
+ */
+class SetUploadValidated implements SharedPipe
+{
+	public function __construct(
+		protected readonly ConfigManager $config_manager,
+	) {
+	}
+
+	public function handle(DuplicateDTO|StandaloneDTO $state, \Closure $next): DuplicateDTO|StandaloneDTO
+	{
+		$state->photo->is_upload_validated = $this->resolveIsValidated($state->intended_owner_id);
+
+		return $next($state);
+	}
+
+	private function resolveIsValidated(int $intended_owner_id): bool
+	{
+		// No authenticated owner → guest upload
+		if ($intended_owner_id === 0) {
+			$trust_level = $this->config_manager->getValueAsEnum('guest_upload_trust_level', UserUploadTrustLevel::class)
+				?? UserUploadTrustLevel::CHECK;
+
+			return $trust_level !== UserUploadTrustLevel::CHECK;
+		}
+
+		$owner = User::find($intended_owner_id);
+
+		// Owner not found → fail-open for backward compatibility
+		if ($owner === null) {
+			return true;
+		}
+
+		// Admin always bypasses trust level (Q-033-03 → A)
+		if ($owner->may_administrate === true) {
+			return true;
+		}
+
+		$trust_level = $owner->upload_trust_level;
+
+		return $trust_level !== UserUploadTrustLevel::CHECK;
+	}
+}

app/Actions/User/Create.php

@@ -8,6 +8,7 @@
 
 namespace App\Actions\User;
 
+use App\Enum\UserUploadTrustLevel;
 use App\Exceptions\ConflictingPropertyException;
 use App\Exceptions\InvalidPropertyException;
 use App\Exceptions\ModelDBException;
@@ -35,6 +36,7 @@ public function do(
 		bool $may_administrate = false,
 		?int $quota_kb = null,
 		?string $note = null,
+		?UserUploadTrustLevel $upload_trust_level = null,
 	): User {
 		if (User::query()->where('username', '=', $username)->count() !== 0) {
 			throw new ConflictingPropertyException('Username already exists');
@@ -52,6 +54,9 @@ public function do(
 		$user->password = Hash::make($password);
 		$user->quota_kb = $quota_kb;
 		$user->note = $note;
+		$user->upload_trust_level = $upload_trust_level
+			?? $this->config_manager->getValueAsEnum('default_user_trust_level', UserUploadTrustLevel::class)
+			?? UserUploadTrustLevel::TRUSTED;
 		$user->save();
 
 		return $user;

app/Actions/User/Save.php

@@ -8,6 +8,7 @@
 
 namespace App\Actions\User;
 
+use App\Enum\UserUploadTrustLevel;
 use App\Exceptions\ConflictingPropertyException;
 use App\Exceptions\InvalidPropertyException;
 use App\Exceptions\ModelDBException;
@@ -42,6 +43,7 @@ public function do(User $user,
 		bool $may_administrate = false,
 		?int $quota_kb = null,
 		?string $note = null,
+		?UserUploadTrustLevel $upload_trust_level = null,
 	): void {
 		if (User::query()
 			->where('username', '=', $username)
@@ -62,6 +64,9 @@ public function do(User $user,
 		$user->may_administrate = $may_administrate;
 		$user->note = $note;
 		$user->quota_kb = $quota_kb;
+		if ($upload_trust_level !== null) {
+			$user->upload_trust_level = $upload_trust_level;
+		}
 		if ($password !== null && $password !== '') {
 			$user->password = Hash::make($password);
 		}

app/Contracts/Http/Requests/RequestAttribute.php

@@ -100,6 +100,7 @@ class RequestAttribute
 	public const MAY_UPLOAD_ATTRIBUTE = 'may_upload';
 	public const MAY_EDIT_OWN_SETTINGS_ATTRIBUTE = 'may_edit_own_settings';
 	public const MAY_ADMINISTRATE = 'may_administrate';
+	public const UPLOAD_TRUST_LEVEL_ATTRIBUTE = 'upload_trust_level';
 	public const SHARED_ALBUMS_VISIBILITY_ATTRIBUTE = 'shared_albums_visibility';
 
 	/**

app/Enum/UserUploadTrustLevel.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Enum;
+
+/**
+ * Enum UserUploadTrustLevel.
+ *
+ * Per-user trust level controlling whether newly uploaded photos are
+ * immediately visible to the public or require admin approval first.
+ *
+ * - CHECK:   Uploads are hidden from the public until an admin approves them.
+ * - MONITOR: Reserved for future use; currently behaves identically to TRUSTED.
+ * - TRUSTED: Uploads are immediately publicly visible (subject to album visibility).
+ */
+enum UserUploadTrustLevel: string
+{
+	case CHECK = 'check';
+	case MONITOR = 'monitor';
+	case TRUSTED = 'trusted';
+}

app/Http/Controllers/Admin/ModerationController.php

@@ -0,0 +1,66 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Requests\Moderation\ApproveModerationRequest;
+use App\Http\Requests\Moderation\ListModerationRequest;
+use App\Http\Resources\Collections\PaginatedModerationResource;
+use App\Models\Photo;
+use Illuminate\Http\Response;
+use Illuminate\Routing\Controller;
+
+/**
+ * Controller for the admin moderation panel.
+ *
+ * Lists photos awaiting validation (is_upload_validated = false) and
+ * supports bulk-approval by setting is_upload_validated = true.
+ *
+ * Both endpoints are restricted to administrators only.
+ */
+class ModerationController extends Controller
+{
+	/**
+	 * List all photos that have not yet been validated.
+	 *
+	 * @param ListModerationRequest $request
+	 *
+	 * @return PaginatedModerationResource
+	 */
+	public function list(ListModerationRequest $request): PaginatedModerationResource
+	{
+		$per_page = min((int) $request->query('per_page', 30), 100);
+
+		/** @var \Illuminate\Pagination\LengthAwarePaginator<Photo> $paginated */
+		$paginated = Photo::where('is_upload_validated', false)
+			->with(['owner', 'albums', 'size_variants'])
+			->orderBy('created_at', 'desc')
+			->paginate($per_page);
+
+		return new PaginatedModerationResource($paginated);
+	}
+
+	/**
+	 * Bulk-approve a set of photos by marking them as validated.
+	 *
+	 * @param ApproveModerationRequest $request
+	 *
+	 * @return Response
+	 */
+	public function approve(ApproveModerationRequest $request): Response
+	{
+		$ids = $request->photoIds();
+
+		// Process in chunks to avoid potential query size issues (NFR-033-04)
+		collect($ids)->chunk(100)->each(function ($chunk): void {
+			Photo::whereIn('id', $chunk)->update(['is_upload_validated' => true]);
+		});
+
+		return response()->noContent();
+	}
+}

app/Http/Controllers/Admin/UserManagementController.php

@@ -40,7 +40,7 @@ class UserManagementController extends Controller
 	public function list(ManagmentListUsersRequest $request, Spaces $spaces): Collection
 	{
 		/** @var Collection<int,User> $users */
-		$users = User::select(['id', 'username', 'may_administrate', 'may_upload', 'may_edit_own_settings', 'quota_kb', 'description', 'note'])->orderBy('id', 'asc')->get();
+		$users = User::select(['id', 'username', 'may_administrate', 'may_upload', 'may_edit_own_settings', 'quota_kb', 'description', 'note', 'upload_trust_level'])->orderBy('id', 'asc')->get();
 		$spaces_per_user = $spaces->getFullSpacePerUser();
 		$zipped = $users->zip($spaces_per_user);
 
@@ -61,7 +61,8 @@ public function save(SetUserSettingsRequest $request, Save $save): void
 			may_edit_own_settings: $request->mayEditOwnSettings(),
 			may_administrate: $request->mayAdministrate(),
 			quota_kb: $request->quota_kb(),
-			note: $request->note()
+			note: $request->note(),
+			upload_trust_level: $request->uploadTrustLevel(),
 		);
 
 		TaggedRouteCacheUpdated::dispatch(CacheTag::USERS);
@@ -95,7 +96,8 @@ public function create(AddUserRequest $request, Create $create): UserManagementR
 			may_edit_own_settings: $request->mayEditOwnSettings(),
 			may_administrate: $request->mayAdministrate(),
 			quota_kb: $request->quota_kb(),
-			note: $request->note()
+			note: $request->note(),
+			upload_trust_level: $request->uploadTrustLevel(),
 		);
 
 		TaggedRouteCacheUpdated::dispatch(CacheTag::USERS);

app/Http/Requests/Moderation/ApproveModerationRequest.php

@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Moderation;
+
+use App\Contracts\Http\Requests\RequestAttribute;
+use App\Http\Requests\BaseApiRequest;
+use App\Models\User;
+use App\Rules\RandomIDRule;
+use Illuminate\Support\Facades\Auth;
+
+/**
+ * Authorization guard and validation for the bulk-approve moderation endpoint.
+ *
+ * Only administrators may approve photos.
+ */
+class ApproveModerationRequest extends BaseApiRequest
+{
+	/** @var string[] */
+	protected array $photo_ids = [];
+
+	public function authorize(): bool
+	{
+		/** @var User|null */
+		$user = Auth::user();
+
+		return $user?->may_administrate === true;
+	}
+
+	public function rules(): array
+	{
+		return [
+			RequestAttribute::PHOTO_IDS_ATTRIBUTE => 'required|array|min:1|max:500',
+			RequestAttribute::PHOTO_IDS_ATTRIBUTE . '.*' => ['required', new RandomIDRule(false)],
+		];
+	}
+
+	protected function processValidatedValues(array $values, array $files): void
+	{
+		$this->photo_ids = $values[RequestAttribute::PHOTO_IDS_ATTRIBUTE];
+	}
+
+	/**
+	 * @return string[]
+	 */
+	public function photoIds(): array
+	{
+		return $this->photo_ids;
+	}
+}

app/Http/Requests/Moderation/ListModerationRequest.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Moderation;
+
+use App\Http\Requests\AbstractEmptyRequest;
+use App\Models\User;
+use Illuminate\Support\Facades\Auth;
+
+/**
+ * Authorization guard for the moderation list endpoint.
+ *
+ * Only administrators may access the moderation queue.
+ */
+class ListModerationRequest extends AbstractEmptyRequest
+{
+	public function authorize(): bool
+	{
+		/** @var User|null */
+		$user = Auth::user();
+
+		return $user?->may_administrate === true;
+	}
+}