laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2026-01-24 14:18:50 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
6fbc2e05da49625eacc1884d61071e96c182abdc
blossom/buds/04.md
hzrd149 6fbc2e05da M ove authorization to BUD-11 and clarify
2026-01-13 19:48:31 -08:00

2.3 KiB
Raw Blame History

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

// request body...
{
  "url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf"
}

The endpoint MUST return a 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, 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).

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
  2. Server A returns a Blob Descriptor with the url
  3. Client sends the url to Server B /mirror using the original upload authorization token
  4. Server B downloads the blob from Server A using the url
  5. Server B verifies the downloaded blob hash matches the x tag in the authorization token
  6. Server B returns a Blob Descriptor