mirror of https://github.com/hzrd149/blossom.git
139 lines
5.0 KiB
Markdown
139 lines
5.0 KiB
Markdown
# BUD-02
|
|
|
|
## Blob upload and management
|
|
|
|
`draft` `optional`
|
|
|
|
_All pubkeys MUST be in hex format_
|
|
|
|
Defines the `/upload`, `/list` and `DELETE /<sha256>` endpoints
|
|
|
|
## Blob Descriptor
|
|
|
|
A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, and `uploaded` fields
|
|
|
|
- `url` A publicly accessible URL to the [BUD-01](./01.md#get-sha256---get-blob) `GET /<sha256>` 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
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
|
|
"sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
|
|
"size": 184292,
|
|
"type": "application/pdf",
|
|
"uploaded": 1725105921
|
|
}
|
|
```
|
|
|
|
## 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 (Optional)
|
|
|
|
Servers MAY accept an authorization event when uploading blobs and should perform additional checks
|
|
|
|
1. The `t` tag MUST be set to `upload`
|
|
2. MUST contain at least one `x` tag matching the sha256 hash of the blob being uploaded
|
|
|
|
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 (Optional)
|
|
|
|
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 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
|
|
|
|
### 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 appropriate 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. 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
|
|
{
|
|
"id": "a92868bd8ea740706d931f5d205308eaa0e6698e5f8026a990e78ee34ce47fe8",
|
|
"pubkey": "ae0063dd2c81ec469f2291ac029a19f39268bfc40aea7ab4136d7a858c3a06de",
|
|
"kind": 24242,
|
|
"content": "Delete bitcoin.pdf",
|
|
"created_at": 1708774469,
|
|
"tags": [
|
|
["t", "delete"],
|
|
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
|
|
["expiration", "1708858680"]
|
|
],
|
|
"sig": "2ba9af680505583e3eb289a1624a08661a2f6fa2e5566a5ee0036333d517f965e0ffba7f5f7a57c2de37e00a2e85fd7999076468e52bdbcfad8abb76b37a94b0"
|
|
}
|
|
```
|