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>

public/openapi.yaml

@@ -108,6 +108,8 @@ tags:
     description: Translatable page categories
   - name: Users
     description: Local user administration
+  - name: Media
+    description: Images uploaded for a record to point at
   - name: Roles
     description: Local authorisation model (read-only)
 
@@ -1172,6 +1174,61 @@ paths:
         "204": { description: Deleted }
         "403": { $ref: "#/components/responses/Forbidden" }
 
+  /v1/media:
+    post:
+      tags: [Media]
+      summary: Upload an image
+      description: |
+        Stores an image and answers with the `path` a record points at — send
+        it as a page's `featured_image`. Two ways in, exactly one per request:
+
+        - **`multipart/form-data`** with the image as `file`.
+        - **`application/json`** with a `url`, which the API downloads itself.
+          HTTPS only, from a public address — anything resolving to a private,
+          reserved or loopback address is refused — and redirects are not
+          followed: send the image's final address.
+
+        JPEG, PNG, WebP, GIF or AVIF, decided from the file's bytes rather than
+        its name or declared type; SVG is not accepted here. 20 MB at most.
+
+        The smaller versions and the placeholder are derived afterwards, on the
+        queue: `processed` says whether that has happened, and the image serves
+        either way. Requires permission to create or edit pages.
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: The image.
+          application/json:
+            schema:
+              type: object
+              required: [url]
+              properties:
+                url:
+                  type: string
+                  format: uri
+                  description: An `https://` address the API downloads the image from.
+                  example: https://images.example.org/hero.jpg
+      responses:
+        "201":
+          description: Image stored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { $ref: "#/components/schemas/Media" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+
   /v1/users:
     get:
       tags: [Users]
@@ -2124,6 +2181,24 @@ components:
           nullable: true
           description: Must be after `published_at`. When it arrives the record leaves the site on its own.
 
+    Media:
+      type: object
+      properties:
+        path:
+          type: string
+          description: What a record stores, e.g. as a page's `featured_image`.
+          example: pages/Xk3fQ9sLw2PmN8vR1tY6uZ0aB4cD7eF5gH2jK9mN.jpg
+        url: { type: string, format: uri, description: Absolute. }
+        mime: { type: string, nullable: true, example: image/jpeg }
+        size: { type: integer, nullable: true, description: Bytes. }
+        width: { type: integer, nullable: true }
+        height: { type: integer, nullable: true }
+        processed:
+          type: boolean
+          description: |
+            Whether the queue has derived the smaller versions and the
+            placeholder yet. The image serves either way.
+
     Category:
       type: object
       properties: