Merge pull request #17 from hzrd149/mirror-blobs

Mirroring blobs

README.md

@@ -24,6 +24,8 @@ Blossom Servers expose four endpoints for managing blobs
   - `Authentication` _(optional)_: Signed [nostr event](./buds/01.md#list-authorization-optional)
 - `DELETE /<sha256>` [BUD-2](./buds/02.md#delete-sha256---delete-blob)
   - `Authentication`: Signed [nostr event](./buds/01.md#delete-authorization-required)
+- `PUT /mirror` [BUD-04](./buds/04.md#put-mirror---mirror-blob)
+  - `Authentication`: Signed [nostr event](./buds/01.md#upload-authorization-required)
 
 ## Protocol specification (BUDs)
 

buds/01.md

@@ -2,7 +2,7 @@ BUD-01
 ======
 
 Server requirements and blob reterival
----------------------
+--------------------------------------
 
 `draft` `mandatory`
 

buds/02.md

@@ -2,7 +2,7 @@ BUD-02
 ======
 
 Blob upload and management
----------------------
+--------------------------
 
 `draft` `optional`
 

buds/04.md

@@ -0,0 +1,39 @@
+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
+
+```json
+// request body
+{ "url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf" }
+```
+
+Clients MUST set the `Authorization` header to an upload authorization event defined in [BUD-02](./02.md#upload-authorization-required)
+
+The `/mirror` endpoint MUST download the blob from the specified URL and verify the sha256 hash matches the `x` tag in the upload authorization event
+
+The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the mirroring was successful or an error object if it was not
+
+Servers should re-use the `Content-Type` header returned from the URL to discover the mime type of the blob. if none is returned it may use the file extension in the URL
+
+Servers MAY reject a mirror request for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection
+
+## Example Flow
+
+1. Client signs authorization event and uploads blob to Server A
+1. Server A returns blob descriptor with `url`
+1. Client sends the `url` to Server B `/mirror` using the original authorization event
+1. Server B downloads blob from Server A using the url
+1. Server B verifies downloaded blob hash matches `x` tag in authorization event
+1. Server B returns [Blob Descriptor](./02.md#blob-descriptor)