Upload images through the API, and from the MCP server

POST /api/v1/media stores an image where the panel keeps a page's and answers with the path to send as `featured_image`. Without it the MCP server could create a page but never give it a picture. The file goes through Media::for(), so it is processed, served and pruned like one uploaded in the panel. Two ways in, one per request: a multipart `file`, or JSON with a `url` the API downloads itself. JPEG, PNG, WebP, GIF or AVIF only, decided from the bytes; no SVG, which is a document that can carry script. The URL is fetched from inside the stack's network, so RemoteImage guards it: HTTPS only, every resolved address must be public, the connection is pinned to the checked address with CURLOPT_RESOLVE so a changing DNS answer cannot swap in a private one, redirects are not followed, and the body is read to a ceiling whatever its headers say. Uploading needs permission to write pages. MediaPolicy::create stays false, so the panel gains no free-standing "new file" button. In the MCP server a multipart binary field becomes `<field>_path` over stdio: the server reads the file from the caller's disk and sends it as multipart, instead of the model pushing base64 through its context. Over HTTP the server's disk is not the caller's, so only `body.url` is offered. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 11:16:33 +02:00
parent daf6098203
commit a49816eb46
21 changed files with 1008 additions and 11 deletions
--- a/app/Services/Media/RemoteImage.php
+++ b/app/Services/Media/RemoteImage.php
@@ -0,0 +1,130 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Media;
+
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Downloads an image from a URL someone handed the API, without letting that
+ * URL reach anything it should not.
+ *
+ * The request is made by this server, from inside the stack's network, so an
+ * unchecked URL is a way to make it fetch `http://postgres:5432`, the cloud
+ * metadata service, or the application itself. Hence:
+ *
+ * - HTTPS only.
+ * - Every address the host resolves to must be a public one — a single private
+ *   address among several is enough to refuse.
+ * - The connection is pinned to the address that was checked (CURLOPT_RESOLVE),
+ *   so a DNS answer that changes between the check and the request — DNS
+ *   rebinding — cannot swap in a private one.
+ * - Redirects are not followed: the target of one would need all of the above
+ *   again, and "use the final address" is an easy thing to ask for.
+ * - The body is read to a ceiling and no further, whatever the headers claim.
+ */
+class RemoteImage
+{
+    public function __construct(protected HostResolver $resolver) {}
+
+    /**
+     * @return string The file's bytes.
+     *
+     * @throws ValidationException With the reason, on the `url` field.
+     */
+    public function fetch(string $url): string
+    {
+        $parts = parse_url($url);
+        $host = $parts['host'] ?? null;
+
+        if (($parts['scheme'] ?? null) !== 'https' || blank($host)) {
+            $this->fail('https_only');
+        }
+
+        $host = trim((string) $host, '[]');
+        $port = (int) ($parts['port'] ?? 443);
+        $address = $this->publicAddressFor($host);
+        $maxBytes = (int) config('media.upload.max_kb') * 1024;
+
+        try {
+            $response = Http::withOptions([
+                'allow_redirects' => false,
+                'stream' => true,
+                'connect_timeout' => 5,
+                'timeout' => (int) config('media.upload.remote_timeout', 15),
+                'curl' => [CURLOPT_RESOLVE => [sprintf(
+                    '%s:%d:%s',
+                    $host,
+                    $port,
+                    str_contains($address, ':') ? "[{$address}]" : $address,
+                )]],
+            ])
+                ->withHeaders(['Accept' => 'image/*'])
+                ->get($url);
+        } catch (ConnectionException) {
+            $this->fail('unreachable');
+        }
+
+        if ($response->redirect()) {
+            $this->fail('redirect');
+        }
+
+        if ($response->status() !== 200) {
+            $this->fail('status', ['status' => $response->status()]);
+        }
+
+        if ((int) $response->header('Content-Length') > $maxBytes) {
+            $this->fail('too_large', ['max' => (int) config('media.upload.max_kb')]);
+        }
+
+        $body = $response->toPsrResponse()->getBody();
+        $contents = '';
+
+        while (! $body->eof()) {
+            $contents .= $body->read(65536);
+
+            if (strlen($contents) > $maxBytes) {
+                $this->fail('too_large', ['max' => (int) config('media.upload.max_kb')]);
+            }
+        }
+
+        return $contents;
+    }
+
+    /**
+     * The address to connect to, once every address the host has is known to
+     * be public.
+     */
+    protected function publicAddressFor(string $host): string
+    {
+        $addresses = filter_var($host, FILTER_VALIDATE_IP) ? [$host] : $this->resolver->resolve($host);
+
+        if ($addresses === []) {
+            $this->fail('unresolvable');
+        }
+
+        foreach ($addresses as $address) {
+            // GLOBAL_RANGE is the strict one: besides the private and reserved
+            // blocks it refuses shared (100.64/10), link-local and the
+            // IPv4-mapped IPv6 spelling of any of them.
+            if (! filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE)) {
+                $this->fail('private');
+            }
+        }
+
+        return $addresses[0];
+    }
+
+    /**
+     * @param  array<string, mixed>  $replace
+     */
+    protected function fail(string $reason, array $replace = []): never
+    {
+        throw ValidationException::withMessages([
+            'url' => [__("rules.media.remote.{$reason}", $replace)],
+        ]);
+    }
+}