Merge pull request #118 from conorbronsdon/feat/remote-image-55

Accept image_url in upload_image with connection-time SSRF checks (#55)

Author: conorbronsdon

CHANGELOG.md

@@ -15,6 +15,13 @@ and the git tag history (`v0.1.0`–`v0.5.0`).
   Substack editor. Repeated, nested, formatted and multi-paragraph forms keep their Markdown with
   diagnostics. Draft export maps footnotes back and reports any layout that would not round-trip.
   Notes still reject footnotes.
+- `upload_image` accepts `image_url` (#55). The server downloads a PNG, JPEG, GIF, WebP or AVIF image
+  over HTTPS, without Substack cookies, and uploads it through the existing path. Destinations are
+  checked at connection time and after every redirect, so loopback, private, link-local, metadata and
+  reserved addresses (including IPv4-mapped and tunnelled IPv6 forms) are refused and DNS rebinding
+  is covered. Downloads are limited to 3 redirects, 5 MB and 15 seconds, and the bytes must match the
+  declared type. Failures return a typed `code` with `upload_attempts: 0`. The Cloudflare Worker returns
+  `remote_image_unavailable`. See [docs/remote-images.md](docs/remote-images.md).
 
 ## [1.1.1] - 2026-09-14
 

README.md

@@ -266,7 +266,7 @@ Both tools require `publication` when multiple publications are configured.
 |------|-------------|
 | `create_draft` | Create a new draft from markdown (private) |
 | `update_draft` | Apply a reviewed change receipt; recheck unpublished state and report readback outcomes |
-| `upload_image` | Upload an image to Substack's CDN — returns a publicly-fetchable (unlisted) URL |
+| `upload_image` | Upload an image to Substack's CDN from a file, data URI or [public HTTPS URL](docs/remote-images.md) — returns a publicly-fetchable (unlisted) URL |
 
 ### Review before changing a draft
 

docs/remote-images.md

@@ -0,0 +1,61 @@
+# Remote image URLs
+
+`upload_image` accepts exactly one of `image_path`, `image_base64` or
+`image_url`. With `image_url`, the server downloads the image and then uploads
+it through the same Substack endpoint as the other two. The result is the same:
+a hosted image URL that anyone with the link can fetch.
+
+```json
+{ "image_url": "https://images.example.com/chart.png" }
+```
+
+## What is refused
+
+The download is a plain request made by the server, separate from the Substack
+client. It sends no Substack cookies, session token, `Authorization` or
+`Referer` header.
+
+| Rule | Error `code` |
+| --- | --- |
+| Not an absolute `https` URL, contains credentials, or uses a non-default port | `invalid_url` |
+| Resolves to or names a loopback, private, carrier-grade NAT, link-local (including `169.254.169.254`), multicast, documentation or other reserved address | `blocked_destination` |
+| Host does not resolve | `dns_failed` |
+| More than 3 redirects, or a redirect without `Location` | `too_many_redirects`, `http_status` |
+| Any status other than 200 | `http_status` |
+| Compressed or otherwise encoded body | `unsupported_encoding` |
+| Declared or streamed size above 5 MB | `too_large` |
+| Whole download, including redirects, takes longer than 15 seconds | `timeout` |
+| Bytes are not PNG, JPEG, GIF, WebP or AVIF (SVG and HEIC included) | `unsupported_type` |
+| `Content-Type` missing or different from the detected format | `type_mismatch` |
+| Connection failed or ended early | `network` |
+
+A refused download returns `isError: true` with
+`{ "code", "message", "upload_attempts": 0 }`, and nothing is uploaded.
+
+## Address checks
+
+IPv4 addresses must be outside the special-purpose ranges listed above. IPv6
+addresses must be global unicast (`2000::/3`). The server also refuses 6to4,
+Teredo, NAT64 and documentation prefixes, which can embed IPv4 destinations.
+IPv4-mapped forms such as `::ffff:169.254.169.254`, unique-local addresses such
+as `fd00:ec2::254`, and addresses with a zone ID are refused.
+
+The check happens when each connection is made, including after every
+redirect. The server does not look the host up in advance and connect later, so
+DNS rebinding can't swap in a private address between check and connection. If
+a host resolves to several addresses and any one is refused, the whole request
+is refused. Literal IP addresses in a URL or `Location` header are checked
+before connecting.
+
+Proxy environment variables are not used for this download.
+
+## Deployments
+
+The stdio and self-hosted HTTP servers include remote downloads. The Cloudflare
+Worker shares the tool list but not the Node network stack these checks depend
+on. There, `image_url` returns `remote_image_unavailable`; use `image_path` or
+`image_base64` instead.
+
+Local file and data URI uploads are unchanged: `image_path` still infers the
+type from the file extension. The byte-signature and address checks above apply
+only to `image_url`.

src/__tests__/__snapshots__/output-contracts.test.ts.snap

@@ -2808,11 +2808,16 @@ exports[`stable output contracts > classifies any public schema drift as potenti
       "additionalProperties": false,
       "properties": {
         "image_base64": {
-          "description": "Base64-encoded image with data URI prefix (e.g., "data:image/png;base64,..."). Mutually exclusive with image_path.",
+          "description": "Base64-encoded image with data URI prefix (e.g., "data:image/png;base64,..."). Mutually exclusive with image_path and image_url.",
           "type": "string",
         },
         "image_path": {
-          "description": "Absolute path to a local image file (e.g., "/Users/me/pic.png"). Read and encoded automatically; MIME type inferred from the extension. Mutually exclusive with image_base64.",
+          "description": "Absolute path to a local image file (e.g., "/Users/me/pic.png"). Read and encoded automatically; MIME type inferred from the extension. Mutually exclusive with image_base64 and image_url.",
+          "type": "string",
+        },
+        "image_url": {
+          "description": "HTTPS URL of a PNG, JPEG, GIF, WebP or AVIF image to download and upload. Sent without Substack cookies; private, loopback, link-local, metadata and reserved destinations are refused at connection time and on every redirect (at most 3). Limits: 5 MB and 15 seconds; the bytes must match the declared type. Not available on every deployment. Mutually exclusive with image_base64 and image_path.",
+          "maxLength": 2048,
           "type": "string",
         },
         "publication": {
@@ -5427,11 +5432,16 @@ exports[`stable output contracts > classifies any public schema drift as potenti
       "additionalProperties": false,
       "properties": {
         "image_base64": {
-          "description": "Base64-encoded image with data URI prefix (e.g., "data:image/png;base64,..."). Mutually exclusive with image_path.",
+          "description": "Base64-encoded image with data URI prefix (e.g., "data:image/png;base64,..."). Mutually exclusive with image_path and image_url.",
           "type": "string",
         },
         "image_path": {
-          "description": "Absolute path to a local image file (e.g., "/Users/me/pic.png"). Read and encoded automatically; MIME type inferred from the extension. Mutually exclusive with image_base64.",
+          "description": "Absolute path to a local image file (e.g., "/Users/me/pic.png"). Read and encoded automatically; MIME type inferred from the extension. Mutually exclusive with image_base64 and image_url.",
+          "type": "string",
+        },
+        "image_url": {
+          "description": "HTTPS URL of a PNG, JPEG, GIF, WebP or AVIF image to download and upload. Sent without Substack cookies; private, loopback, link-local, metadata and reserved destinations are refused at connection time and on every redirect (at most 3). Limits: 5 MB and 15 seconds; the bytes must match the declared type. Not available on every deployment. Mutually exclusive with image_base64 and image_path.",
+          "maxLength": 2048,
           "type": "string",
         },
       },