laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2025-12-08 14:58:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #15 from hzrd149/split-core-spec

Browse Source 
split upload, list, and delete endpoints into bud-02
This commit is contained in:
hzrd149
2024-05-24 10:08:03 -05:00
committed by GitHub
parent 08ef9cb7d0 6ed1d28d7f
commit 2280d4280f
3 changed files with 141 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@@ -1,5 +1,7 @@
# 🌸 Blossom - Blobs stored simply on mediaservers
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
## What is it?
Blossom is a spec for a set of HTTP endpoints that allow users to store blobs of data on publicly accessible servers
@@ -12,22 +14,22 @@ Blobs are packs of binary data addressed by their sha256 hash
Blossom Servers expose four endpoints for managing blobs
- `GET /<sha256>` (optional file `.ext`)
- `HEAD /<sha256>` (optional file `.ext`)
- `PUT /upload`
- `GET /<sha256>` (optional file `.ext`) [BUD-01](./buds/01.md#get-sha256---get-blob)
- `HEAD /<sha256>` (optional file `.ext`) [BUD-01](./buds/01.md#head-sha256---has-blob)
- `PUT /upload` [BUD-2](./buds/02.md#put-upload---upload-blob)
- `Authentication`: Signed [nostr event](./buds/01.md#upload-authorization-required)
- Return a blob descriptor
- `GET /list/<pubkey>`
- `GET /list/<pubkey>` [BUD-02](./buds/02.md#get-listpubkey---list-blobs)
- Returns an array of blob descriptors
- `Authentication` _(optional)_: Signed [nostr event](./buds/01.md#list-authorization-optional)
- `DELETE /<sha256>`
- `DELETE /<sha256>` [BUD-2](./buds/02.md#delete-sha256---delete-blob)
- `Authentication`: Signed [nostr event](./buds/01.md#delete-authorization-required)
## Protocol specification (BUDs)
BUDs stand for **Blossom Upgrade Documents**.
See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) for a detailed explanation of the endpoints
See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-02](./buds/02.md) for a detailed explanation of the endpoints
## License

132
buds/01.md
View File

@@ -1,13 +1,11 @@
BUD-01
======
Core endpoint outline
Server requirements and blob reterival
---------------------
`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_
## Cross origin headers
@@ -60,28 +58,17 @@ Example HTTP Authorization header:
Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQxNDA5ZDhiOTBjY2RiNGI0M2Y4ZjBmYzlkMGMiLCJwdWJrZXkiOiI5ZjBjYzE3MDIzYjJjZjUwOWUwZjFkMzA1NzkzZDIwZTdjNzIyNzY5MjhmZDliZjg1NTM2ODg3YWM1NzBhMjgwIiwiY3JlYXRlZF9hdCI6MTcwODc3MTIyNywia2luZCI6MjQyNDIsInRhZ3MiOltbInQiLCJnZXQiXSxbImV4cGlyYXRpb24iLCIxNzA4ODU3NTQwIl1dLCJjb250ZW50IjoiR2V0IEJsb2JzIiwic2lnIjoiMDJmMGQyYWIyM2IwNDQ0NjI4NGIwNzFhOTVjOThjNjE2YjVlOGM3NWFmMDY2N2Y5NmNlMmIzMWM1M2UwN2I0MjFmOGVmYWRhYzZkOTBiYTc1NTFlMzA4NWJhN2M0ZjU2NzRmZWJkMTVlYjQ4NTFjZTM5MGI4MzI4MjJiNDcwZDIifQ==
```
## Blob Descriptor
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
- `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
## 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
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
Servers MUST repond with `Content-Type: application/json` and a JSON object containing `message` for all error responses
## Error Responses
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.
For HTTP `4xx` and `5xx` status codes servers MUST repond with `Content-Type: application/json` and a JSON object containing `message`
### Example Error response
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
@@ -94,7 +81,7 @@ access-control-allow-methods: get, put, delete
{"message":"Missing Auth event"}
```
### GET /sha256 - Get Blob
## GET /sha256 - Get Blob
The `GET /<sha256>` endpoint MUST return the contents of the blob with the `Content-Type` header set to the appropriate MIME type
@@ -103,7 +90,7 @@ The endpoint MUST accept an optional file extension in the URL. ie. `.pdf`, `.pn
If the endpoints returns a 301 or 302 redirect it MUST redirect to a URL containing the same sha256 hash as requested blob.
This ensures that if a user was to copy or reuse the redirect URL it would still contain the original sha256 hash
#### Get Authorization (optional)
### Get Authorization (optional)
The server may optionally require authorization when fetching blobs from the `GET /<sha256>` endpoint
@@ -130,109 +117,8 @@ Example Authorization event:
}
```
### HEAD /sha256 - Has Blob
## HEAD /sha256 - Has Blob
The `HEAD /<sha256>` endpoint MUST respond with either a `200` or `404` status code
The endpoint MUST accept an optional file extension in the URL similar to the `GET /<sha256>` endpoint. ie. `.pdf`, `.png`, etc
### PUT /upload - Upload Blob
The `PUT /upload` endpoint MUST accept binary data in the body of the request and MAY use the `Content-Type` header to get the MIME type of the data
The endpoint MUST NOT modify the blob in any way and should return the exact same sha256 that was uploaded. This is critical to allow users to re-upload their blobs to new servers
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
#### Upload Authorization (required)
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
Example Authorization event:
```json
{
"id": "bb653c815da18c089f3124b41c4b5ec072a40b87ca0f50bbbc6ecde9aca442eb",
"pubkey": "b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e",
"kind": 24242,
"content": "Upload bitcoin.pdf",
"created_at": 1708773959,
"tags": [
["t", "upload"],
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
["expiration", "1708858680"]
],
"sig": "d0d58c92afb3f4f1925120b99c39cffe77d93e82f488c5f8f482e8f97df75c5357175b5098c338661c37d1074b0a18ab5e75a9df08967bfb200930ec6a76562f"
}
```
### GET /list/pubkey - List Blobs
The `/list/<pubkey>` 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
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)
The server may optionally require Authorization when listing blobs uploaded by the pubkey
In this case the server must perform additional checks on the authorization event
1. The `t` tag must be set to `list`
Example Authorization event:
```json
{
"id": "cbb1cab9566355bfdf04e1f1fc1e655fe903ecc193e8a750092ee53beec2a0e8",
"pubkey": "a5fc3654296e6de3cda6ba3e8eba7224fac8b150fd035d66b4c3c1dc2888b8fc",
"kind": 24242,
"content": "List Blobs",
"created_at": 1708772350,
"tags": [
["t", "list"],
["expiration", "1708858680"]
],
"sig": "ff9c716f8de0f633738036472be553ce4b58dc71d423a0ef403f95f64ef28582ef82129b41d4d0ef64d2338eb4aeeb66dbc03f8b3a3ed405054ea8ecb14fa36c"
}
```
### DELETE /sha256 - Delete Blob
Servers MUST accept `DELETE` requests to the `/<sha256>` 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
#### Delete Authorization (required)
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
Example Authorization event:
```json
{
"id": "a92868bd8ea740706d931f5d205308eaa0e6698e5f8026a990e78ee34ce47fe8",
"pubkey": "ae0063dd2c81ec469f2291ac029a19f39268bfc40aea7ab4136d7a858c3a06de",
"kind": 24242,
"content": "Delete bitcoin.pdf",
"created_at": 1708774469,
"tags": [
["t", "delete"],
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553 "],
["expiration", "1708858680"]
],
"sig": "2ba9af680505583e3eb289a1624a08661a2f6fa2e5566a5ee0036333d517f965e0ffba7f5f7a57c2de37e00a2e85fd7999076468e52bdbcfad8abb76b37a94b0"
}
```

124
buds/02.md Normal file
View File

@@ -0,0 +1,124 @@
BUD-02
======
Blob upload and management
---------------------
`draft` `optional`
_All pubkeys MUST be in hex format_
Defines the `/upload`, `/list` and `DELETE /<sha256>` enpoints
## Blob Descriptor
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
- `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
## PUT /upload - Upload Blob
The `PUT /upload` endpoint MUST accept binary data in the body of the request and MAY use the `Content-Type` and `Content-Length` headers to get the MIME type and size of the data
The endpoint MUST NOT modify the blob in any way and should return the exact same sha256 that was uploaded. This is critical to allow users to re-upload their blobs to new servers
The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the upload was successful or an error object if it was 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
### Upload Authorization (required)
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
Example Authorization event:
```json
{
"id": "bb653c815da18c089f3124b41c4b5ec072a40b87ca0f50bbbc6ecde9aca442eb",
"pubkey": "b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e",
"kind": 24242,
"content": "Upload bitcoin.pdf",
"created_at": 1708773959,
"tags": [
["t", "upload"],
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
["expiration", "1708858680"]
],
"sig": "d0d58c92afb3f4f1925120b99c39cffe77d93e82f488c5f8f482e8f97df75c5357175b5098c338661c37d1074b0a18ab5e75a9df08967bfb200930ec6a76562f"
}
```
## GET /list/pubkey - List Blobs
The `/list/<pubkey>` 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
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)
The server may optionally require Authorization when listing blobs uploaded by the pubkey
In this case the server must perform additional checks on the authorization event
1. The `t` tag must be set to `list`
Example Authorization event:
```json
{
"id": "cbb1cab9566355bfdf04e1f1fc1e655fe903ecc193e8a750092ee53beec2a0e8",
"pubkey": "a5fc3654296e6de3cda6ba3e8eba7224fac8b150fd035d66b4c3c1dc2888b8fc",
"kind": 24242,
"content": "List Blobs",
"created_at": 1708772350,
"tags": [
["t", "list"],
["expiration", "1708858680"]
],
"sig": "ff9c716f8de0f633738036472be553ce4b58dc71d423a0ef403f95f64ef28582ef82129b41d4d0ef64d2338eb4aeeb66dbc03f8b3a3ed405054ea8ecb14fa36c"
}
```
## DELETE /sha256 - Delete Blob
Servers MUST accept `DELETE` requests to the `/<sha256>` 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
### Delete Authorization (required)
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
Example Authorization event:
```json
{
"id": "a92868bd8ea740706d931f5d205308eaa0e6698e5f8026a990e78ee34ce47fe8",
"pubkey": "ae0063dd2c81ec469f2291ac029a19f39268bfc40aea7ab4136d7a858c3a06de",
"kind": 24242,
"content": "Delete bitcoin.pdf",
"created_at": 1708774469,
"tags": [
["t", "delete"],
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553 "],
["expiration", "1708858680"]
],
"sig": "2ba9af680505583e3eb289a1624a08661a2f6fa2e5566a5ee0036333d517f965e0ffba7f5f7a57c2de37e00a2e85fd7999076468e52bdbcfad8abb76b37a94b0"
}
```