From 014bc528ebefb4d114074330a5c852a6c2ac0178 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 27 Apr 2024 12:14:03 -0500 Subject: [PATCH] move server implementation to bud-01 write draft bud-02 --- Client.md | 13 ----------- README.md | 30 ++++--------------------- Server.md => buds/bud-01.md | 44 +++++++++++++++++++++++++++---------- buds/bud-02.md | 21 ++++++++++++++++++ 4 files changed, 57 insertions(+), 51 deletions(-) delete mode 100644 Client.md rename Server.md => buds/bud-01.md (79%) create mode 100644 buds/bud-02.md diff --git a/Client.md b/Client.md deleted file mode 100644 index 6d4e560..0000000 --- a/Client.md +++ /dev/null @@ -1,13 +0,0 @@ -# Blossom Client Implementation - -## Upload Blob - -Clients should perform the following steps when uploading blobs - -1. Prompt the user to sign an [Authorization event](./Server.md#upload-authorization-required) for the blob -2. Get the users [Server Discovery](./Nostr.md#user-server-discovery) -3. Make a `PUT /upload` request with the authorization event to each server on the list - -## Implementations - -Example implementation (Typescript) [blossom-client](https://github.com/hzrd149/blossom-client) diff --git a/README.md b/README.md index a5c2968..af5cb74 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,4 @@ -# 🌸 Blossom WIP - -Blobs stored simply on mediaservers +# 🌸 Blossom - Blobs stored simply on mediaservers ## What is it? @@ -25,31 +23,11 @@ Blossom Servers expose four endpoints for managing blobs - `DELETE /` - `Authentication`: Signed [nostr event](./Server.md#delete-authorization-required) -## Blob Descriptor +## Protocol specification -A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, and `created` fields +BUDs stand for Blossom Upgrade Possibilities. -- `url` A public facing url this blob can retrieved from -- `sha256` The sha256 hash of the blob -- `size` The size of the blob in bytes -- `type` (optional) The MIME type of the blob -- `created` 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 - -## Nostr Identities - -Blossom uses nostr public / private keys for identities. Users are expected to sign authorization events to prove their identity when interacting with servers - -See [Nostr](./Nostr.md) - -## Server Implementation - -See [Server](./Server.md) - -## Client Implementation - -See [Client](./Client.md) +See the [BUDs](./buds) folder and specifically [BUD-01](./buds/bud-01.md) for a detailed explanation of the endpoints ## License diff --git a/Server.md b/buds/bud-01.md similarity index 79% rename from Server.md rename to buds/bud-01.md index b4a5086..37b18fc 100644 --- a/Server.md +++ b/buds/bud-01.md @@ -1,14 +1,20 @@ -# Blossom Server Implementation +# BUD-01 + +## Core endpoint outline + +`draft` `mandatory` + +Blossom uses [nostr](https://github.com/nostr-protocol/nostr) public / private keys for identities. Users are expected to sign authorization events to prove their identity when interacting with servers _All pubkeys MUST be in hex format_ -## CORS +## Cross origin headers -Servers MUST set `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Headers: Authorization,*` and `Access-Control-Allow-Methods: GET, PUT, DELETE` headers on all endpoint to ensure compatibility with apps hosted on other domains +Servers MUST set the `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Headers: Authorization,*` and `Access-Control-Allow-Methods: GET, PUT, DELETE` headers on all endpoints to ensure compatibility with apps hosted on other domains ## Authorization events -Authorization events are used to identify the users pubkey with the server +Authorization events are used to identify the users to the server Authorization events must be generic and must NOT be scoped to specific servers. This allows pubkeys to sign a single event and interact the same way with multiple servers. @@ -52,6 +58,18 @@ Example HTTP Authorization header: Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQxNDA5ZDhiOTBjY2RiNGI0M2Y4ZjBmYzlkMGMiLCJwdWJrZXkiOiI5ZjBjYzE3MDIzYjJjZjUwOWUwZjFkMzA1NzkzZDIwZTdjNzIyNzY5MjhmZDliZjg1NTM2ODg3YWM1NzBhMjgwIiwiY3JlYXRlZF9hdCI6MTcwODc3MTIyNywia2luZCI6MjQyNDIsInRhZ3MiOltbInQiLCJnZXQiXSxbImV4cGlyYXRpb24iLCIxNzA4ODU3NTQwIl1dLCJjb250ZW50IjoiR2V0IEJsb2JzIiwic2lnIjoiMDJmMGQyYWIyM2IwNDQ0NjI4NGIwNzFhOTVjOThjNjE2YjVlOGM3NWFmMDY2N2Y5NmNlMmIzMWM1M2UwN2I0MjFmOGVmYWRhYzZkOTBiYTc1NTFlMzA4NWJhN2M0ZjU2NzRmZWJkMTVlYjQ4NTFjZTM5MGI4MzI4MjJiNDcwZDIifQ== ``` +## Blob Descriptor + +A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, and `created` fields + +- `url` A public facing url this blob can retrieved from +- `sha256` The sha256 hash of the blob +- `size` The size of the blob in bytes +- `type` (optional) The MIME type of the blob +- `created` 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 + ## 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 fetching blobs @@ -68,6 +86,8 @@ content-type: application/json; charset=utf-8 content-length: 32 access-control-allow-origin: * access-control-expose-headers: * +access-control-allow-headers: authorization,* +access-control-allow-methods: get, put, delete {"message":"Missing Auth event"} ``` @@ -117,14 +137,14 @@ The `PUT /upload` endpoint should expect the `Content-Type` header of the reques The endpoint MUST return a [Blob Descriptor](./README.md#blob-descriptor) if the upload was successful or an error object if not. -Servers may reject an upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +Servers MAY reject an upload for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection #### Upload Authorization (required) -Servers must accept an authorization event when uploading blobs and should perform additional checks +Servers MUST accept an authorization event when uploading blobs and should perform additional checks -1. The `t` tag must be set to `upload` -2. A `size` tag must be present and set to the total size of the uploaded blob +1. The `t` tag MUST be set to `upload` +2. A `size` tag MUST be present and set to the total size of the uploaded blob Example Authorization event: @@ -146,11 +166,11 @@ Example Authorization event: ### GET /list/pubkey - List Blobs -The `/list/` endpoint must return a JSON array of [Blob Descriptor](./README.md#blob-descriptor) that where uploaded by the specified pubkey +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 blob descriptors by the `created` field +The endpoint MUST support a `since` and `until` query parameter to limit the returned blob descriptors by the `created` field -Servers may reject an upload for any reason and MUST respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +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 #### List Authorization (optional) @@ -185,7 +205,7 @@ Servers may reject a delete request for any reason and should respond with the a #### Delete Authorization (required) -Servers must accept an authorization event when deleting blobs +Servers MUST accept an authorization event when deleting blobs Servers should perform additional checks on the authorization event diff --git a/buds/bud-02.md b/buds/bud-02.md new file mode 100644 index 0000000..6c04d25 --- /dev/null +++ b/buds/bud-02.md @@ -0,0 +1,21 @@ +# BUD-02 + +## Media processing endpoint + +`draft` `optional` + +### PUT /process + +A server MAY expose a `/process` endpoint for the purpose of processing and/or optimizing any blob the user uploads + +The endpoint MUST accept the `Content-Type` of `multipart/form-data` with the field `blob` containing the raw binary of the blob being upload + +Similar to the `/upload` endpoint the server MUST respond with a [Blob Descriptor](./bud-01.md#blob-descriptor) + +The server MUST also require authentication for the endpoint. in which case it MUST accept the same `upload` [authorization event](./bud-01#upload-authorization-required) as the `/upload` endpoint + +### HEAD /process + +If a server is exposing a `PUT /process` endpoint is MUST also expose a `HEAD /process` endpoint to allow clients to check if the `PUT /process` endpoint is available + +The endpoint MUST respond with the `200` status code