feat: attach images to commits from the API

KNOWLEDGE_BASE.md

@@ -219,7 +219,7 @@ Sources: [stash hook](resources/js/hooks/use-stash.ts), [image storage](resource
 
 ### Images and descriptions
 
-Attach up to **three JPEG, PNG, or WebP images** to a commit or reply. Each image can be at most **10 MB** and **6,000 pixels in either dimension**. Add an image description of up to **1,000 characters** for accessibility. Add images with the picker, by pasting, or by dropping them on the composer. Every image is re-encoded to WebP, at most 1,600 pixels wide, which strips metadata such as location. Images can be posted without accompanying text. Images on a pending commit are visible only to its author and admins. Image attachments and a poll cannot be combined in the same commit. Open an attached photo to view it in the photo viewer, move through the commit's images, read its description, or download it. Terminal commits can attach images without descriptions; the signed API cannot attach images.
+Attach up to **three JPEG, PNG, or WebP images** to a commit or reply. Each image can be at most **10 MB** and **6,000 pixels in either dimension**. Add an image description of up to **1,000 characters** for accessibility. Add images with the picker, by pasting, or by dropping them on the composer. Every image is re-encoded to WebP, at most 1,600 pixels wide, which strips metadata such as location. Images can be posted without accompanying text. Images on a pending commit are visible only to its author and admins. Image attachments and a poll cannot be combined in the same commit. Open an attached photo to view it in the photo viewer, move through the commit's images, read its description, or download it. Terminal commits can attach images without descriptions, and signed API commits with them.
 
 Sources: [image picker](resources/js/components/commit-image-picker.tsx), [image limits](app/Actions/CreateCommitImages.php), [attachment validation](app/Http/Requests/CreateCommitRequest.php), [photo controller](app/Http/Controllers/CommitPhotoController.php).
 
@@ -436,15 +436,15 @@ An app can use the same `/api/v1` for you with signed requests. It keeps an SSH
 A signed request sees what the web shows you, such as your own pending commits. It can also, with the web's validation, moderation, and rate limits:
 
 - read your account, logs, replies, notifications, and saved commits;
-- commit, reply, and quote, and delete your commits;
+- commit, reply, and quote, with images, and delete your commits;
 - follow or unfollow, mute or unmute, and block or unblock, and list who you muted and blocked;
 - star or unstar, and save or unsave;
 - switch Pastéis mode and give pastéis;
 - report commits;
 - sync from GitHub and save your lane color;
 - delete your account.
 
-Signed request bodies are JSON, so app commits are text only: no images, polls, or link-card choice. Pinning, Remotes, scheduling, search, and translations are web-only for now. Signed requests are limited to **120 requests per minute per user**. Settings → Devices lists your approved devices with when each was last used, and revokes them.
+Signed request bodies are JSON, or multipart when they carry images, so app commits can have images but no polls or link-card choice. Pinning, Remotes, scheduling, search, and translations are web-only for now. Signed requests are limited to **120 requests per minute per user**. Settings → Devices lists your approved devices with when each was last used, and revokes them.
 
 Sources: [signed requests](app/Services/SignedRequests.php), [sign-in page](app/Http/Controllers/MobileAuthorizationController.php), [devices settings](resources/js/pages/device/index.tsx), [API routes](routes/api.php).
 

app/Http/Controllers/Api/CommitController.php

@@ -45,7 +45,7 @@ public function show(ShowApiCommitRequest $request, #[CurrentUser] ?User $curren
      */
     public function store(CreateApiCommitRequest $request, #[CurrentUser] User $user, CreateCommit $action, CommitPageQuery $page): JsonResponse
     {
-        $commit = $action->handle($user, $request->string('body')->value(), $request->parent(), $request->quotedCommit());
+        $commit = $action->handle($user, $request->string('body')->value(), $request->parent(), $request->quotedCommit(), $request->images(), $request->imageDescriptions());
 
         return CommitResource::make($page->get($commit, $user))
             ->response()

app/Http/Requests/CreateApiCommitRequest.php

@@ -9,10 +9,14 @@
 use App\Rules\VisibleCommit;
 use Illuminate\Contracts\Validation\ValidationRule;
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Validation\Rules\Dimensions;
+use Illuminate\Validation\Rules\Enum;
+use Illuminate\Validation\Rules\File;
 
 /**
- * A commit from the mobile app, sent as JSON. It may reply to a commit or quote one, as on the web, but not both. It has
- * no images or poll yet.
+ * A commit from the mobile app, sent as JSON, or with images as multipart (see SignedRequests). It may reply to a commit
+ * or quote one, as on the web, but not both. The images are checked as the web checks them. It has no poll yet.
  */
 final class CreateApiCommitRequest extends FormRequest
 {
@@ -30,17 +34,32 @@ public function prepareForValidation(): void
     }
 
     /**
-     * @return array<string, array<int, string|ValidationRule>>
+     * @return array<string, array<int, string|ValidationRule|File|Dimensions|Enum>>
      */
     public function rules(): array
     {
         $user = $this->user();
         assert($user instanceof User);
+        $attachmentRules = CreateCommitRequest::attachmentRules();
 
         return [
-            'body' => CreateCommitRequest::bodyRules(),
+            'body' => CreateCommitRequest::bodyRules($this->hasFile('images')),
             'parent_id' => ['bail', 'nullable', 'uuid', new VisibleCommit($user)],
             'quoted_commit_id' => ['bail', 'nullable', 'uuid', 'prohibits:parent_id', new VisibleCommit($user, __('That commit is no longer available to quote.'))],
+            'images' => $attachmentRules['images'],
+            'images.*' => $attachmentRules['images.*'],
+            'image_descriptions' => $attachmentRules['image_descriptions'],
+            'image_descriptions.*' => $attachmentRules['image_descriptions.*'],
+        ];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function attributes(): array
+    {
+        return [
+            'image_descriptions.*' => 'image description',
         ];
     }
 
@@ -66,4 +85,25 @@ public function quotedCommit(): ?Commit
             ? Commit::query()->visibleTo($user)->find($this->string('quoted_commit_id')->value())
             : null;
     }
+
+    /**
+     * @return list<UploadedFile>
+     */
+    public function images(): array
+    {
+        $images = $this->file('images');
+
+        return is_array($images) ? array_values($images) : [];
+    }
+
+    /**
+     * @return list<string|null>
+     */
+    public function imageDescriptions(): array
+    {
+        /** @var list<string|null> $descriptions */
+        $descriptions = $this->array('image_descriptions');
+
+        return $descriptions;
+    }
 }

app/Http/Requests/ShowCommitImageRequest.php

@@ -13,7 +13,8 @@
 final class ShowCommitImageRequest extends FormRequest
 {
     /**
-     * Pending and rejected images never leave the server for anyone but their author and moderators.
+     * Pending and rejected images never leave the server for anyone but their author and moderators, or the temporary
+     * URL the API gave one of them, until the commit is deleted.
      */
     public function authorize(): Response
     {
@@ -22,7 +23,7 @@ public function authorize(): Response
 
         $commit = Commit::query()->find($commitImage->commit_id);
 
-        return $commit instanceof Commit && $commit->imagesAreVisibleTo($this->user()) && Storage::disk()->exists($commitImage->path)
+        return $commit instanceof Commit && ($commit->imagesAreVisibleTo($this->user()) || (! $commit->trashed() && $this->hasValidSignature())) && Storage::disk()->exists($commitImage->path)
             ? Response::allow()
             : Response::denyAsNotFound();
     }

app/Http/Resources/CommitResource.php

@@ -4,7 +4,9 @@
 
 namespace App\Http\Resources;
 
+use App\Enums\CommitStatus;
 use App\Models\Commit;
+use App\Models\CommitImage;
 use App\Models\Poll;
 use App\Models\User;
 use App\Services\CommitBodies;
@@ -24,7 +26,8 @@
  * its votes, and the commit it quotes, or null once the user may no longer see that one, while quoted_commit_id still
  * says it quoted something. In a list, reply_preview is the newest reply or quote the web shows under it. As on the
  * web, the counts, link_preview, images, starred, parent, poll, quoted_commit and reply_preview are only
- * there when they were loaded, so ancestors and the commits of notifications come without some of them.
+ * there when they were loaded, so ancestors and the commits of notifications come without some of them. The images of
+ * a commit that isn't published yet have temporary URLs, since the app has no web session to load them with.
  *
  * A deleted commit that still has replies stays in its thread as a tombstone: its id, parent_id, deleted_at and
  * replies_count, but never its author or body. Only signed requests are ever sent one.
@@ -59,7 +62,9 @@ public function toArray(Request $request): array
             'stars_count' => $this->whenCounted('stars'),
             'replies_count' => $this->whenCounted('replies'),
             'link_preview' => $this->whenLoaded('linkPreview'),
-            'images' => $this->whenLoaded('images'),
+            'images' => $this->whenLoaded('images', fn (): mixed => $this->status === CommitStatus::Approved || ! $this->imagesAreVisibleTo($request->user())
+                ? $this->images
+                : $this->images->map(fn (CommitImage $image): array => [...$image->toArray(), 'url' => $image->temporaryUrl()])),
             'author' => UserResource::make($this->user),
         ];
 

app/Models/CommitImage.php

@@ -11,6 +11,7 @@
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Support\Facades\URL;
 
 /**
  * @property-read string $id
@@ -78,4 +79,14 @@ public function url(): string
     {
         return route('commit-image.show', $this);
     }
+
+    /**
+     * Serves the image to anyone who has the URL, until it expires. The API hands it to the author of a pending commit,
+     * since the mobile app has no web session to load their own pending images with. It stays the same for an hour at
+     * a time, so the app can keep the image it loaded.
+     */
+    public function temporaryUrl(): string
+    {
+        return URL::temporarySignedRoute('commit-image.show', now()->startOfHour()->addHours(2), ['commitImage' => $this]);
+    }
 }

app/Services/SignedRequests.php

@@ -7,22 +7,33 @@
 use App\Actions\UpdateDeviceLastUsedAt;
 use App\Dto\SshPublicKey;
 use App\Models\Device;
+use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;
+use Illuminate\Foundation\Http\Middleware\TrimStrings;
 use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
 use InvalidArgumentException;
+use Symfony\Component\HttpFoundation\File\UploadedFile;
 
 /**
  * Verifies a request to the API, signed by the mobile app with an SSH key it keeps on the device.
  *
  * The signed message is "<unix timestamp>\n<nonce>\n<METHOD>\n<path and query>\n<body>". The timestamp and nonce
  * are also sent in the X-Devnull-Timestamp and X-Devnull-Nonce headers, and the signature in X-SSH-Signature.
  *
+ * A request with images is sent as multipart, like a commit with images from the `devnull commit` script: the JSON
+ * body goes in a payload part, the images in images[], and the signed message carries one more line before the body,
+ * the comma-separated SHA-256 of each image in the order they are attached. It is signed under its own namespace, so
+ * the signature states which format it covers.
+ *
  * A key signs in as a user once that user approved it as a device on the web. The key doesn't have to be on their
  * GitHub account: the approval is the proof. So a key made for something else, like committing from CI, can't sign in.
  */
 final readonly class SignedRequests
 {
     public const string Namespace = 'devnull-api';
 
+    public const string ImagesNamespace = 'devnull-api-images';
+
     private const array Headers = ['X-Devnull-Timestamp', 'X-Devnull-Nonce', 'X-SSH-Signature'];
 
     public function __construct(private SshSignatures $sshSignatures, private UpdateDeviceLastUsedAt $updateDeviceLastUsedAt)
@@ -40,29 +51,31 @@ public function isSigned(Request $request): bool
 
     /**
      * Checks the signature, its timestamp and its nonce, which it spends, and returns the key that signed the request,
-     * whether or not it is approved as a device yet.
+     * whether or not it is approved as a device yet. A request with images reads its fields from its payload from
+     * then on.
      */
     public function verifySignature(Request $request): SshPublicKey
     {
-        // Only the raw body is signed, so it has to be JSON. PHP hands a multipart body over as fields and files and
-        // keeps no raw body, and the same signed bytes read as a form would give the endpoint other fields...
-        throw_if(
-            $request->files->count() > 0 || ($request->getContent() === '' ? $request->request->count() > 0 : ! $request->isJson()),
-            InvalidArgumentException::class,
-            'Send the body of a signed request as JSON.',
-        );
+        $withImages = $request->files->count() > 0;
+        $body = $withImages ? $this->payload($request) : $this->body($request);
+
+        throw_if($body === null, InvalidArgumentException::class, 'Send the body of a signed request as JSON.');
 
         $timestamp = $request->headers->get('X-Devnull-Timestamp', '') ?? '';
         $nonce = $request->headers->get('X-Devnull-Nonce', '') ?? '';
 
         $publicKey = $this->sshSignatures->verify(
-            implode("\n", [$timestamp, $nonce, $request->getMethod(), $request->getRequestUri(), $request->getContent()]),
+            implode("\n", [$timestamp, $nonce, $request->getMethod(), $request->getRequestUri(), ...($withImages ? [implode(',', $this->imageHashes($request))] : []), $body]),
             $request->headers->get('X-SSH-Signature', '') ?? '',
-            self::Namespace,
+            $withImages ? self::ImagesNamespace : self::Namespace,
         );
 
         $this->sshSignatures->checkFreshness($timestamp, $nonce);
 
+        if ($withImages) {
+            $this->readPayload($request, $body);
+        }
+
         return $publicKey;
     }
 
@@ -86,4 +99,72 @@ public function verify(Request $request): array
             'device' => $device,
         ];
     }
+
+    /**
+     * The raw body, which is all that is signed, so it has to be JSON. PHP hands a multipart body over as fields and
+     * files and keeps no raw body, and the same signed bytes read as a form would give the endpoint other fields.
+     */
+    private function body(Request $request): ?string
+    {
+        $content = $request->getContent();
+
+        if ($content === '') {
+            return $request->request->count() > 0 ? null : '';
+        }
+
+        return $request->isJson() ? $content : null;
+    }
+
+    /**
+     * The JSON body of a request with images, or null unless it came as a payload part beside a list of images, with
+     * no other fields or files.
+     */
+    private function payload(Request $request): ?string
+    {
+        $files = $request->files->all();
+        $payload = $files['payload'] ?? null;
+        $images = $files['images'] ?? null;
+
+        $isMultipart = $request->request->count() === 0
+            && count($files) === 2
+            && $payload instanceof UploadedFile && $payload->isValid()
+            && is_array($images) && array_is_list($images) && array_all($images, fn (mixed $image): bool => $image instanceof UploadedFile);
+
+        $contents = $isMultipart ? file_get_contents($payload->getPathname()) : false;
+
+        return is_string($contents) && is_array(json_decode($contents, true)) ? $contents : null;
+    }
+
+    /**
+     * An image PHP couldn't take, too big for its upload limit for one, can't be hashed, and is a validation error,
+     * as on the web, rather than a bad signature.
+     *
+     * @return list<string>
+     */
+    private function imageHashes(Request $request): array
+    {
+        /** @var list<UploadedFile> $images */
+        $images = $request->files->all()['images'];
+
+        return array_map(function (UploadedFile $image): string {
+            throw_unless($image->isValid(), ValidationException::withMessages(['images' => __('validation.uploaded', ['attribute' => 'image'])]));
+
+            return (string) hash_file('sha256', $image->getPathname());
+        }, $images);
+    }
+
+    /**
+     * The payload becomes the request's fields, cleaned the way every request's fields are before it gets here.
+     */
+    private function readPayload(Request $request, string $payload): void
+    {
+        /** @var array<string, mixed> $fields */
+        $fields = json_decode($payload, true);
+
+        $request->request->replace($fields);
+
+        foreach ([TrimStrings::class, ConvertEmptyStringsToNull::class] as $middleware) {
+            resolve($middleware)->handle($request, fn (Request $request): Request => $request);
+        }
+    }
 }