refactor: API Resources and Form Requests for SecretAttachment (#180)

CHANGELOG.md

@@ -14,6 +14,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **File Attachments API (Phase 2)** (#175)
+  - Upload encrypted file attachments to secrets (POST `/v1/secrets/{secret}/attachments`)
+  - List attachments for a secret (GET `/v1/secrets/{secret}/attachments`)
+  - Download decrypted attachments (GET `/v1/attachments/{attachment}/download`)
+  - Delete attachments (DELETE `/v1/attachments/{attachment}`)
+  - Files encrypted at rest using tenant DEK encryption
+  - Configurable file size limits and MIME type restrictions
+  - Owner-based authorization via `SecretAttachmentPolicy`
+  - OpenAPI documentation for all attachment endpoints
+  - Comprehensive test coverage: 13 Controller tests, 3 Service tests, 2 Model tests, 8 Policy tests
+
 - **Code Coverage Integration** (#170)
   - Integrated Codecov for automated coverage tracking
   - PHPUnit now generates Clover XML coverage reports

app/Http/Controllers/Api/V1/SecretAttachmentController.php

@@ -0,0 +1,107 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: 2025 SecPal Contributors
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\StoreSecretAttachmentRequest;
+use App\Http\Resources\SecretAttachmentResource;
+use App\Models\Secret;
+use App\Models\SecretAttachment;
+use App\Models\User;
+use App\Services\AttachmentStorageService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Response;
+use Illuminate\Support\Facades\Gate;
+
+/**
+ * Secret attachment API controller.
+ *
+ * Handles file upload, listing, download, and deletion for secret attachments.
+ * All files are encrypted at rest using tenant DEK.
+ */
+class SecretAttachmentController extends Controller
+{
+    /**
+     * Create controller instance.
+     */
+    public function __construct(
+        private readonly AttachmentStorageService $storageService
+    ) {}
+
+    /**
+     * Upload attachment to secret.
+     */
+    public function store(StoreSecretAttachmentRequest $request, Secret $secret): JsonResponse
+    {
+        Gate::authorize('create', [SecretAttachment::class, $secret]);
+
+        /** @var \Illuminate\Http\UploadedFile $file */
+        $file = $request->validated()['file'];
+
+        $user = $request->user();
+        assert($user instanceof User, 'User must be authenticated');
+
+        $attachment = $this->storageService->store($file, $secret, $user);
+
+        return SecretAttachmentResource::make($attachment)
+            ->response()
+            ->setStatusCode(201);
+    }
+
+    /**
+     * List attachments for secret.
+     */
+    public function index(Secret $secret): JsonResponse
+    {
+        Gate::authorize('viewAny', [SecretAttachment::class, $secret]);
+
+        $attachments = $secret->attachments()->latest()->get();
+
+        return response()->json([
+            'data' => SecretAttachmentResource::collection($attachments),
+        ]);
+    }
+
+    /**
+     * Download attachment.
+     */
+    public function download(SecretAttachment $attachment): Response
+    {
+        Gate::authorize('view', $attachment);
+
+        $content = $this->storageService->retrieve($attachment);
+        $filename = $attachment->filename_plain;
+
+        // Ensure filename is present; attachments should always have a filename.
+        if ($filename === null) {
+            abort(500, 'Attachment is missing a filename.');
+        }
+
+        // Escape filename for Content-Disposition header (RFC 2231/5987)
+        $safeFilename = str_replace(['"', '\\'], ['', ''], $filename);
+
+        return response($content, 200, [
+            'Content-Type' => $attachment->mime_type,
+            'Content-Disposition' => 'attachment; filename="'.$safeFilename.'"',
+            'Content-Length' => (string) $attachment->file_size,
+        ]);
+    }
+
+    /**
+     * Delete attachment.
+     */
+    public function destroy(SecretAttachment $attachment): Response
+    {
+        Gate::authorize('delete', $attachment);
+
+        $this->storageService->delete($attachment);
+
+        return response()->noContent();
+    }
+}

app/Http/Requests/StoreSecretAttachmentRequest.php

@@ -0,0 +1,67 @@
+<?php
+
+// SPDX-FileCopyrightText: 2025 SecPal Contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * Form Request for storing SecretAttachment.
+ *
+ * Validates file uploads for secret attachments.
+ */
+class StoreSecretAttachmentRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     *
+     * Authorization is handled by SecretAttachmentPolicy, not here.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        /** @var int $maxSize */
+        $maxSize = config('attachments.max_file_size');
+        /** @var array<int, string> $allowedMimes */
+        $allowedMimes = config('attachments.allowed_mime_types');
+
+        return [
+            'file' => [
+                'required',
+                'file',
+                'max:'.($maxSize / 1024), // Convert bytes to KB for Laravel validation
+                'mimetypes:'.implode(',', $allowedMimes),
+            ],
+        ];
+    }
+
+    /**
+     * Get custom error messages for validation rules.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        /** @var int $maxSizeBytes */
+        $maxSizeBytes = config('attachments.max_file_size');
+        $maxSize = $maxSizeBytes / (1024 * 1024); // Convert bytes to MB
+
+        return [
+            'file.required' => 'Please select a file to upload.',
+            'file.file' => 'The uploaded file is not valid.',
+            'file.max' => 'The file size must not exceed '.$maxSize.' MB.',
+            'file.mimetypes' => 'The file type is not allowed. Only certain file types are permitted.',
+        ];
+    }
+}

app/Http/Resources/SecretAttachmentResource.php

@@ -0,0 +1,42 @@
+<?php
+
+// SPDX-FileCopyrightText: 2025 SecPal Contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * API Resource for SecretAttachment model.
+ *
+ * Transforms attachment metadata for JSON responses.
+ *
+ * @property \App\Models\SecretAttachment $resource
+ *
+ * @mixin \App\Models\SecretAttachment
+ */
+class SecretAttachmentResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        /** @var \App\Models\SecretAttachment $attachment */
+        $attachment = $this->resource;
+
+        return [
+            'id' => $attachment->id,
+            'filename' => $attachment->filename_plain,
+            'file_size' => $attachment->file_size,
+            'mime_type' => $attachment->mime_type,
+            'download_url' => $attachment->download_url,
+            'uploaded_by' => $attachment->uploaded_by,
+            'created_at' => $attachment->created_at->toIso8601String(),
+        ];
+    }
+}

app/Models/Secret.php

@@ -252,6 +252,39 @@ public function owner(): BelongsTo
         return $this->belongsTo(User::class, 'owner_id');
     }
 
+    /**
+     * Relation to SecretAttachment (file attachments).
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\HasMany<SecretAttachment, $this>
+     */
+    public function attachments(): \Illuminate\Database\Eloquent\Relations\HasMany
+    {
+        return $this->hasMany(SecretAttachment::class);
+    }
+
+    /**
+     * Get count of attachments for this secret.
+     *
+     * Uses the aggregated count from withCount('attachments') if available,
+     * otherwise performs a count query. To avoid N+1 queries, use:
+     * Secret::withCount('attachments')->get()
+     *
+     * @return int Number of attachments
+     */
+    public function getAttachmentCountAttribute(): int
+    {
+        // Use aggregated count if available (from withCount())
+        if (isset($this->attributes['attachments_count'])) {
+            /** @var int|numeric-string $count */
+            $count = $this->attributes['attachments_count'];
+
+            return (int) $count;
+        }
+
+        // Fallback to query (may cause N+1 if used in a loop)
+        return $this->attachments()->count();
+    }
+
     /**
      * Scope to filter by owner.
      *