From 79d1543358d07456ae5d5de32a3a6475dd8fe651 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 18 May 2024 07:38:27 -0500 Subject: [PATCH 01/11] Add bud-02 User Server List --- Nostr.md | 26 -------------------------- README.md | 11 +++++++++++ buds/bud-02.md | 40 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 26 deletions(-) delete mode 100644 Nostr.md create mode 100644 buds/bud-02.md diff --git a/Nostr.md b/Nostr.md deleted file mode 100644 index 9206007..0000000 --- a/Nostr.md +++ /dev/null @@ -1,26 +0,0 @@ -# Blossom nostr integration - -Blossom uses nostr for public / private key identities. Users are expected to sign authentication events to prove their identity when uploading or deleting blobs - -See [Authorization events](./Server.md#authorization-events) - -## User Server Discovery - -Users should publish a kind `10063` event with a list of ordered `server` tags indicating servers that others users should use when getting their blobs - -### Example - -```json -{ - "id": "e4bee088334cb5d38cff1616e964369c37b6081be997962ab289d6c671975d71", - "pubkey": "781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036", - "content": "", - "kind": 10063, - "created_at": 1708774162, - "tags": [ - ["server", "https://cdn.self.hosted"], - ["server", "https://cdn.satellite.earth"] - ], - "sig": "cc5efa74f59e80622c77cacf4dd62076bcb7581b45e9acff471e7963a1f4d8b3406adab5ee1ac9673487480e57d20e523428e60ffcc7e7a904ac882cfccfc653" -} -``` diff --git a/README.md b/README.md index e532dc6..baf58bf 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,17 @@ BUDs stand for **Blossom Upgrade Documents**. See the [BUDs](./buds) folder and specifically [BUD-01](./buds/bud-01.md) for a detailed explanation of the endpoints +## BUDs + + - [Core endpoint description](./buds/bud-01.md) + - [User Server List](./buds/bud-02.md) + +## Event kinds +| kind | description | NIP | +| ------------- | -------------------------- | ------------------------ | +| `24242` | Authorization event | [01](./buds/bud-01.md.md)| +| `10063` | User Server List | [02](./buds/bud-02.md.md)| + ## License Public domain. diff --git a/buds/bud-02.md b/buds/bud-02.md new file mode 100644 index 0000000..aff4fd7 --- /dev/null +++ b/buds/bud-02.md @@ -0,0 +1,40 @@ +BUD-02 +====== + +User Server List +------------------------- + +`draft` `optional` + +Defines a replaceable event using `kind:10063` to advertise the blossom servers for downloading a user's blobs from. + +The event MUST include an ordered list of `server` tags with the server URL including the `http://` or `https://`. + +The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers coming first. + +The `.content` is not used. + +```json +{ + "id": "e4bee088334cb5d38cff1616e964369c37b6081be997962ab289d6c671975d71", + "pubkey": "781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036", + "content": "", + "kind": 10063, + "created_at": 1708774162, + "tags": [ + ["server", "https://cdn.self.hosted"], + ["server", "https://cdn.satellite.earth"] + ], + "sig": "cc5efa74f59e80622c77cacf4dd62076bcb7581b45e9acff471e7963a1f4d8b3406adab5ee1ac9673487480e57d20e523428e60ffcc7e7a904ac882cfccfc653" +} +``` + +## Client Integration + +When uploading blobs clients should attempt to upload the blob to all or at least the top 3 server on the list event. + +This ensures that the blob is available in multiple locations in the case one of the servers goes offline. + +## Server Integration + +Servers may use this event kind to discover other servers that a user is uploading to in order to download specific blobs from. From eb85eef7d447fca573095fa4f1a8d1bfef065ba9 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Wed, 22 May 2024 09:32:17 -0500 Subject: [PATCH 02/11] small fixes for wording --- buds/{bud-02.md => 02.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename buds/{bud-02.md => 02.md} (87%) diff --git a/buds/bud-02.md b/buds/02.md similarity index 87% rename from buds/bud-02.md rename to buds/02.md index aff4fd7..42345a3 100644 --- a/buds/bud-02.md +++ b/buds/02.md @@ -6,9 +6,9 @@ User Server List `draft` `optional` -Defines a replaceable event using `kind:10063` to advertise the blossom servers for downloading a user's blobs from. +Defines a replaceable event using `kind:10063` to advertise the blossom servers a user uses to host their blobs. -The event MUST include an ordered list of `server` tags with the server URL including the `http://` or `https://`. +The event MUST include at least one `server` tag containing the full server URL including the `http://` or `https://`. The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers coming first. From 7d61cd96d2e6a074cf51008c2e120686d2c5a8b1 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 8 Jun 2024 09:25:12 -0500 Subject: [PATCH 03/11] add client implementation details --- buds/03.md | 50 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/buds/03.md b/buds/03.md index 42345a3..e52d010 100644 --- a/buds/03.md +++ b/buds/03.md @@ -10,9 +10,9 @@ Defines a replaceable event using `kind:10063` to advertise the blossom servers The event MUST include at least one `server` tag containing the full server URL including the `http://` or `https://`. -The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers coming first. +The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers being first. -The `.content` is not used. +The `.content` field is not used. ```json { @@ -29,12 +29,50 @@ The `.content` is not used. } ``` -## Client Integration +## Client Upload Implementation -When uploading blobs clients should attempt to upload the blob to all or at least the top 3 server on the list event. +When uploading blobs clients MUST attempt to upload the blob to at least the first `server` listed in the users server list. + +Optionally clients MAY upload the blob to all the servers or mirror the blob to the other servers if they support [BUD-04](./04.md) This ensures that the blob is available in multiple locations in the case one of the servers goes offline. -## Server Integration +## Client Retrieval Implementation -Servers may use this event kind to discover other servers that a user is uploading to in order to download specific blobs from. +When extracting the SHA256 hash from the URL clients MUST use the last occurrence of a 64 char hex string. This allows clients to extract hashes from blossom URLs and SOME non-blossom URLs. + +In all the following examples, the hash `b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553` should be selected + +- Blossom URLs + - `https://blossom.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + - `https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553` +- Non Blossom URLs + - `https://cdn.example.com/user/ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0/media/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + - `https://cdn.example.com/media/user-name/documents/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + - `http://download.example.com/downloads/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553` + - `http://media.example.com/documents/b1/67/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + +In the context of nostr events, clients SHOULD use the author's server list when looking for blobs that are no longer available at the original URL. + +Take the following event as an example + +```json +{ + "id": "834185269f4ab72539193105060dbb1c8b2efd702d14481cea345c47beefe6eb", + "pubkey": "ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0", + "content": "I've developed a new open source P2P e-cash system called Bitcoin. check it out\nhttps://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf", + "kind": 1, + "created_at": 1297484820, + "tags": [], + "sig": "bd4bb200bdd5f7ffe5dbc3e539052e27b05d6f9f528e255b1bc4261cc16b8f2ad85c89eef990c5f2eee756ef71b4c571ecf6a88ad12f7338e321dd60c6a903b5" +} +``` + +Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` is no longer available. It should perform the following steps to find the blob: + +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 + +This ensures clients can quickly find missing blobs using the users list of trusted servers. From 2e2abe2678e4221880d7968ffa833e4c3c33997f Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 8 Jun 2024 09:34:16 -0500 Subject: [PATCH 04/11] update readme --- README.md | 15 +++++++++------ buds/03.md | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 05812b5..78f67e8 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,17 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0 ## BUDs - - [Core endpoint description](./buds/bud-01.md) - - [User Server List](./buds/bud-02.md) +- [Server requirements and blob retrieval](./buds/01.md) +- [Blob upload and management](./buds/02.md) +- [User Server List](./buds/03.md) +- [Mirroring blobs](./buds/04.md) ## Event kinds -| kind | description | NIP | -| ------------- | -------------------------- | ------------------------ | -| `24242` | Authorization event | [01](./buds/bud-01.md.md)| -| `10063` | User Server List | [02](./buds/bud-02.md.md)| + +| kind | description | BUD | +| ------- | ------------------- | ------------------ | +| `24242` | Authorization event | [01](./buds/01.md) | +| `10063` | User Server List | [03](./buds/03.md) | ## License diff --git a/buds/03.md b/buds/03.md index e52d010..b98404b 100644 --- a/buds/03.md +++ b/buds/03.md @@ -1,4 +1,4 @@ -BUD-02 +BUD-03 ====== User Server List From e181ff8081def391b86ae88c686d353d5386ab1b Mon Sep 17 00:00:00 2001 From: sebas Date: Sat, 20 Jul 2024 13:42:55 -0600 Subject: [PATCH 05/11] fix typo in 01.md --- buds/01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/01.md b/buds/01.md index 25bd4ba..3c77e12 100644 --- a/buds/01.md +++ b/buds/01.md @@ -60,7 +60,7 @@ Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQ ## Endpoints -All endpoints MUST be served from the root path (eg. `https://cdn.example.com/upload`, etc). This allows clients to talk to servers interchangeably when uploading or reteriving blobs +All endpoints MUST be served from the root path (eg. `https://cdn.example.com/upload`, etc). This allows clients to talk to servers interchangeably when uploading or retrieving blobs ## Error Responses From 402e11fd38f64fa25d9c062e07645f38a5614e9a Mon Sep 17 00:00:00 2001 From: sebas Date: Sat, 20 Jul 2024 16:41:25 -0600 Subject: [PATCH 06/11] spelling check 01.md --- buds/01.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buds/01.md b/buds/01.md index 3c77e12..f181405 100644 --- a/buds/01.md +++ b/buds/01.md @@ -101,7 +101,7 @@ In this case the server MUST perform additional checks on the authorization even If the client did not send an `Authorization` header the server must respond with the appropriate HTTP status code `401` (Unauthorized) -Example event for retreiving a single blob: +Example event for retrieving a single blob: ```json { @@ -119,7 +119,7 @@ Example event for retreiving a single blob: } ``` -Example event for retreiving multiple blobs from single server: +Example event for retrieving multiple blobs from single server: ```json { From 968324214c845ed1929335b3dc45b85ce875285f Mon Sep 17 00:00:00 2001 From: 0xtr Date: Mon, 22 Jul 2024 00:05:04 +0200 Subject: [PATCH 07/11] Fix spelling mistake and extra whitespace in BUD-02 --- buds/02.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buds/02.md b/buds/02.md index e645943..9ac8540 100644 --- a/buds/02.md +++ b/buds/02.md @@ -61,7 +61,7 @@ Example Authorization event: The `/list/` endpoint MUST return a JSON array of [Blob Descriptor](#blob-descriptor) that where uploaded by the specified pubkey -The endpoint MUST support a `since` and `until` query parameter to limit the returned blobs by thier `uploaded` date +The endpoint MUST support a `since` and `until` query parameter to limit the returned blobs by their `uploaded` date Servers may reject a list for any reason and MUST respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection @@ -116,7 +116,7 @@ Example Authorization event: "created_at": 1708774469, "tags": [ ["t", "delete"], - ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553 "], + ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"], ["expiration", "1708858680"] ], "sig": "2ba9af680505583e3eb289a1624a08661a2f6fa2e5566a5ee0036333d517f965e0ffba7f5f7a57c2de37e00a2e85fd7999076468e52bdbcfad8abb76b37a94b0" From 559c0274b93b28695f422cddef3e44ad1a286fdc Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Mon, 22 Jul 2024 09:39:19 -0500 Subject: [PATCH 08/11] small spelling fix --- buds/03.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/03.md b/buds/03.md index b98404b..0cf971a 100644 --- a/buds/03.md +++ b/buds/03.md @@ -68,7 +68,7 @@ Take the following event as an example } ``` -Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` is no longer available. It should perform the following steps to find the blob: +Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` is no longer available. It can perform the following steps to find the blob: 1. Get the SHA256 has from the URL 2. Look for the authors server list `kind:10063` From ea53e0b389593fc3872266dac446162ca76109b9 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Mon, 22 Jul 2024 09:40:19 -0500 Subject: [PATCH 09/11] update bud list --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 78f67e8..9c9c85c 100644 --- a/README.md +++ b/README.md @@ -35,10 +35,10 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0 ## BUDs -- [Server requirements and blob retrieval](./buds/01.md) -- [Blob upload and management](./buds/02.md) -- [User Server List](./buds/03.md) -- [Mirroring blobs](./buds/04.md) +- [BUD-01: Server requirements and blob retrieval](./buds/01.md) +- [BUD-02: Blob upload and management](./buds/02.md) +- [BUD-03: User Server List](./buds/03.md) +- [BUD-04: Mirroring blobs](./buds/04.md) ## Event kinds From ebe1bcc4e2e090577143c07c92b6808a73d2a369 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Tue, 30 Jul 2024 20:17:02 -0500 Subject: [PATCH 10/11] spelling fixes --- buds/02.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buds/02.md b/buds/02.md index 9ac8540..b9afce6 100644 --- a/buds/02.md +++ b/buds/02.md @@ -8,7 +8,7 @@ Blob upload and management _All pubkeys MUST be in hex format_ -Defines the `/upload`, `/list` and `DELETE /` enpoints +Defines the `/upload`, `/list` and `DELETE /` endpoints ## Blob Descriptor @@ -94,7 +94,7 @@ Example Authorization event: Servers MUST accept `DELETE` requests to the `/` endpoint -Servers may reject a delete request for any reason and should respond with the aproperate HTTP `4xx` status code and an error message explaining the reason for the rejection +Servers may reject a delete request for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection ### Delete Authorization (required) From 9f5b440ec37cb517ab4c4ed63cf784d950984bca Mon Sep 17 00:00:00 2001 From: 0xtr Date: Fri, 2 Aug 2024 01:38:21 +0200 Subject: [PATCH 11/11] 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