# BUD-04

## Mirroring blobs

`draft` `optional`

Defines the `/mirror` endpoint

## 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"
}
```

The endpoint MUST return a [Blob Descriptor](#blob-descriptor) and a `2xx` status code if the mirroring was successful
or a `4xx` status code and error message if it was not.

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 `4xx` status code and an error message explaining the reason for the rejection.

### Upload Authorization

Servers MAY require an `upload` authorization token when mirroring blobs. The server MUST first perform the base validation checks defined in [BUD-11](./11.md#base-validation), then MUST perform the following additional checks:

1. The `t` tag MUST be set to `upload`
2. The authorization token MUST contain at least one `x` tag matching the sha256 hash of the downloaded blob. The `x` tag scopes the token to specific blob hashes (see [BUD-11](./11.md#tag-scoping)).

**Multiple `x` tags in the authorization token MUST NOT be interpreted as the user requesting to mirror multiple blobs.**

## 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)