# BUD-04 ## Mirroring blobs `draft` `optional` `unrecommended` Defines the `/mirror` endpoint. New clients and servers SHOULD use [`POST /` from BUD-13](./13.md#post-sha256---mirror-blob) instead. That flow uses the blob hash in the path, accepts one or more HTTP URLs or [BUD-10](./10.md) Blossom URIs in the request body, cleanly separates mirroring from direct uploads, and reuses the same [BUD-11](./11.md) `upload` authorization token that a direct `PUT /` upload uses. ## PUT /mirror - Mirror Blob A server MAY expose a `PUT /mirror` endpoint to allow users to copy a blob from a URL instead of uploading it. Clients MUST pass the URL of the remote blob as a stringified JSON object in the request body ```jsonc // request body... { "url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf" } ``` If the blob was newly mirrored and stored, the endpoint MUST respond with `201 Created` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body. If the blob already exists, the endpoint MUST respond with `200 OK` and a [Blob Descriptor](./02.md#blob-descriptor) in the response body. The destination server SHOULD use the `Content-Type` header returned from the origin server to infer the mime type of the blob. If the `Content-Type` header is not present the destination server SHOULD attempt to detect the `Content-Type` from the blob contents and file extension, falling back to `application/octet-stream` if it cannot determine the type. Servers MAY use the `Content-Length` header to determine the size of the blob. Servers MAY reject a mirror request for any reason and MUST respond with the appropriate HTTP status code and an error message explaining the reason for the rejection. ### Checking support Clients SHOULD send `OPTIONS /mirror` as defined in [BUD-01](./01.md#feature-discovery). This legacy mirroring endpoint is supported when both `Allow` and `Access-Control-Allow-Methods` include `PUT`; new clients SHOULD still prefer `POST /` when available. ### Status codes Servers SHOULD use the following status codes for `PUT /mirror` responses: | Status Code | Meaning | | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | | `200 OK` | The blob already exists and the server is returning the existing [Blob Descriptor](./02.md#blob-descriptor). | | `201 Created` | The blob was mirrored and stored successfully and the server is returning its [Blob Descriptor](./02.md#blob-descriptor). | | `400 Bad Request` | The request body is malformed or the `url` is invalid. | | `401 Unauthorized` | Authorization is required and missing or invalid. See [BUD-11](./11.md#endpoint-authorization-requirements). | | `402 Payment Required` | Payment is required before mirroring can proceed. See [BUD-07](./07.md). | | `403 Forbidden` | The request is understood but not allowed by server policy. | | `409 Conflict` | The mirrored blob hash does not match the authorized `x` tag. | | `413 Content Too Large` | The mirrored blob exceeds server size limits. | | `415 Unsupported Media Type` | The mirrored blob type is not supported. | | `429 Too Many Requests` | The client has exceeded a rate limit or quota. | | `502 Bad Gateway` | The server could not fetch the blob from the origin URL or the origin response was unusable. | If included, `X-Reason` MUST be treated as a human readable diagnostic message only and clients MUST NOT parse it for control flow. ### Upload Authorization Servers MAY require authorization when mirroring blobs as defined by [BUD-11](./11.md#endpoint-authorization-requirements). ### Security considerations The `/mirror` endpoint fetches a user-supplied URL, which can expose the server to server-side request forgery (SSRF) attacks. Implementations SHOULD restrict URLs to HTTP and HTTPS and prevent requests to internal services, including loopback, private, and link-local addresses (such as cloud metadata endpoints), for both IPv4 and IPv6. These protections SHOULD apply to the actual destination IP address used for each connection, including after DNS resolution and on every redirect, to prevent bypasses through DNS rebinding or redirects. Requiring upload authorization does not replace SSRF protections. ## Example Flow 1. Client signs an `upload` authorization token and uploads blob to Server A 1. Server A returns a [Blob Descriptor](./02.md#blob-descriptor) with the `url` 1. Client sends the `url` to Server B `/mirror` using the original `upload` authorization token 1. Server B downloads the blob from Server A using the `url` 1. Server B verifies the downloaded blob hash matches the `x` tag in the authorization token 1. Server B returns a [Blob Descriptor](./02.md#blob-descriptor)