From 9f5b440ec37cb517ab4c4ed63cf784d950984bca Mon Sep 17 00:00:00 2001 From: 0xtr Date: Fri, 2 Aug 2024 01:38:21 +0200 Subject: [PATCH 1/6] Fix a spelling mistake in BUD-01 --- buds/01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/01.md b/buds/01.md index f181405..a9c3016 100644 --- a/buds/01.md +++ b/buds/01.md @@ -92,7 +92,7 @@ This ensures that if a user was to copy or reuse the redirect URL it would still ### Get Authorization (optional) -The server may optionally require authorization when reteriving blobs from the `GET /` endpoint +The server may optionally require authorization when retrieving blobs from the `GET /` endpoint In this case the server MUST perform additional checks on the authorization event From 2de7c0dd25e05646c83c3622a350d75b6beaade3 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Tue, 27 Aug 2024 13:26:02 +0300 Subject: [PATCH 2/6] update wording to allow authorization events to include multiple x tags --- buds/01.md | 12 +++++++----- buds/02.md | 10 ++++------ buds/03.md | 8 +++----- buds/04.md | 10 +++++----- 4 files changed, 19 insertions(+), 21 deletions(-) diff --git a/buds/01.md b/buds/01.md index a9c3016..86110d8 100644 --- a/buds/01.md +++ b/buds/01.md @@ -1,8 +1,6 @@ -BUD-01 -====== +# BUD-01 -Server requirements and blob retrieval --------------------------------------- +## Server requirements and blob retrieval `draft` `mandatory` @@ -24,6 +22,8 @@ Events MUST have the `content` set to a human readable string explaining to the All events MUST have a [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md) `expiration` tag set to a unix timestamp at which the event should be considered expired. +Authorization events MAY have multiple `x` tags for endpoints that require a sha256 hash. + Example event: ```json @@ -35,6 +35,7 @@ Example event: "created_at": 1708773959, "tags": [ ["t", "upload"], + // Authorization events MAY have multiple "x" tags ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"], ["expiration", "1708858680"] ], @@ -69,6 +70,7 @@ For HTTP `4xx` and `5xx` status codes servers MUST repond with `Content-Type: ap The `message` field MUST be human readable and should explain the reason for the error. Optionally servers may include other fields for the client with more information about the error Example Error response: + ``` HTTP/2 401 content-type: application/json; charset=utf-8 @@ -97,7 +99,7 @@ The server may optionally require authorization when retrieving blobs from the ` In this case the server MUST perform additional checks on the authorization event 1. A `t` tag MUST be present and set to `get` -2. The event MUST contain either a `server` tag containing the full URL to the server or MUST contain an `x` tag with the sha256 of the blob being retrieved +2. The event MUST contain either a `server` tag containing the full URL to the server or MUST contain at least one `x` tag matching sha256 hash of the blob being retrieved If the client did not send an `Authorization` header the server must respond with the appropriate HTTP status code `401` (Unauthorized) diff --git a/buds/02.md b/buds/02.md index b9afce6..8ddc18f 100644 --- a/buds/02.md +++ b/buds/02.md @@ -1,8 +1,6 @@ -BUD-02 -====== +# BUD-02 -Blob upload and management --------------------------- +## Blob upload and management `draft` `optional` @@ -37,7 +35,7 @@ Servers MAY reject an upload for any reason and should respond with the appropri Servers MUST accept an authorization event when uploading blobs and should perform additional checks 1. The `t` tag MUST be set to `upload` -2. The `x` tag MUST be present and set to the sha256 hash of the blob +2. MUST contain at least one `x` tag matching the sha256 hash of the blob being uploaded Example Authorization event: @@ -103,7 +101,7 @@ Servers MUST accept an authorization event when deleting blobs Servers should perform additional checks on the authorization event 1. The `t` tag must be set to `delete` -2. A `x` tag must be present and set to the sha256 hash of the blob being deleted +2. MUST contain at least one `x` tag matching the sha256 hash of the blob being deleted Example Authorization event: diff --git a/buds/03.md b/buds/03.md index 0cf971a..c6a1730 100644 --- a/buds/03.md +++ b/buds/03.md @@ -1,8 +1,6 @@ -BUD-03 -====== +# BUD-03 -User Server List -------------------------- +## User Server List `draft` `optional` @@ -73,6 +71,6 @@ Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a8 1. Get the SHA256 has from the URL 2. Look for the authors server list `kind:10063` 3. If found, Attempt to retrieve the blob from each `server` listed started with the first -3. If not found, the client MAY fallback to using a well-known popular blossom server to retrieve the blob +4. If not found, the client MAY fallback to using a well-known popular blossom server to retrieve the blob This ensures clients can quickly find missing blobs using the users list of trusted servers. diff --git a/buds/04.md b/buds/04.md index 0b0191b..6c4de31 100644 --- a/buds/04.md +++ b/buds/04.md @@ -1,8 +1,6 @@ -BUD-04 -====== +# BUD-04 -Mirroring blobs ---------------- +## Mirroring blobs `draft` `optional` @@ -16,7 +14,9 @@ Clients MUST pass the URL of the remote blob as a stringified JSON object in the ```json // request body -{ "url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf" } +{ + "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) From 632c0ce82392e563a8f66bcafea7f6646353affa Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Tue, 27 Aug 2024 13:32:17 +0300 Subject: [PATCH 3/6] clarify that multiple x tags are not a bulk delete --- buds/02.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/buds/02.md b/buds/02.md index 8ddc18f..3461f45 100644 --- a/buds/02.md +++ b/buds/02.md @@ -103,6 +103,10 @@ Servers should perform additional checks on the authorization event 1. The `t` tag must be set to `delete` 2. MUST contain at least one `x` tag matching the sha256 hash of the blob being deleted +When multiple `x` tags are present on the authorization event the server MUST only delete the blob listed in the URL. + +**Multiple `x` tags MUST NOT be interpreted as the user requesting a bulk delete.** + Example Authorization event: ```json From 4325aa79891cb4d68448ce16e5fa5519058eae4b Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Tue, 27 Aug 2024 13:44:35 +0300 Subject: [PATCH 4/6] update BUD-04 to allow multiple x tags --- buds/01.md | 2 +- buds/04.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/buds/01.md b/buds/01.md index 86110d8..146717f 100644 --- a/buds/01.md +++ b/buds/01.md @@ -99,7 +99,7 @@ The server may optionally require authorization when retrieving blobs from the ` In this case the server MUST perform additional checks on the authorization event 1. A `t` tag MUST be present and set to `get` -2. The event MUST contain either a `server` tag containing the full URL to the server or MUST contain at least one `x` tag matching sha256 hash of the blob being retrieved +2. The event MUST contain either a `server` tag containing the full URL to the server or MUST contain at least one `x` tag matching the sha256 hash of the blob being retrieved If the client did not send an `Authorization` header the server must respond with the appropriate HTTP status code `401` (Unauthorized) diff --git a/buds/04.md b/buds/04.md index 6c4de31..b3952d2 100644 --- a/buds/04.md +++ b/buds/04.md @@ -21,7 +21,7 @@ Clients MUST pass the URL of the remote blob as a stringified JSON object in the 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 `/mirror` endpoint MUST download the blob from the specified URL and verify that there is at least one `x` tag in the authorization event matching the sha256 hash of the download blob The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the mirroring was successful or an error object if it was not From 3d3b1b6e2fcfef0b0b8ac5d3f19389bfa7d4891f Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Tue, 27 Aug 2024 13:46:30 +0300 Subject: [PATCH 5/6] clarify multiple x tags and bulk mirror --- buds/04.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/buds/04.md b/buds/04.md index b3952d2..92559c0 100644 --- a/buds/04.md +++ b/buds/04.md @@ -23,6 +23,8 @@ Clients MUST set the `Authorization` header to an upload authorization event def The `/mirror` endpoint MUST download the blob from the specified URL and verify that there is at least one `x` tag in the authorization event matching the sha256 hash of the download blob +**Multiple `x` tags MUST NOT be interpreted as the user requesting a bulk mirror.** + 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 From 95eb92e70768b0a2d5bab3dc42a5e3418f9055ec Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 31 Aug 2024 07:06:18 -0500 Subject: [PATCH 6/6] clarify Blob Descriptor and add example --- buds/02.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/buds/02.md b/buds/02.md index 3461f45..3b9b7f0 100644 --- a/buds/02.md +++ b/buds/02.md @@ -12,13 +12,25 @@ Defines the `/upload`, `/list` and `DELETE /` endpoints A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, and `uploaded` fields -- `url` A public facing url this blob can retrieved from +- `url` A publicly accessible URL to the [BUD-01](./01.md#get-sha256---get-blob) `GET /` endpoint (optionally with a file extension) - `sha256` The sha256 hash of the blob - `size` The size of the blob in bytes - `type` (optional) The MIME type of the blob - `uploaded` The unix timestamp of when the blob was uploaded to the server -Servers may include additional fields in the descriptor like `magnet`, `infohash`, or `ipfs` depending on other protocols they support +Servers MAY include additional fields in the descriptor like `magnet`, `infohash`, or `ipfs` depending on other protocols they support + +Example: + +```json +{ + "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf", + "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553", + "size": 184292, + "type": "application/pdf", + "uploaded": 1725105921 +} +``` ## PUT /upload - Upload Blob