mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-11 07:48:49 +00:00
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
BUD-01
|
|
======
|
|
|
|
Server requirements and blob reterival
|
|
---------------------
|
|
|
|
`draft` `mandatory`
|
|
|
|
_All pubkeys MUST be in hex format_
|
|
|
|
## Cross origin headers
|
|
|
|
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 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.
|
|
|
|
Events MUST be kind `24242` and have a `t` tag with a verb of `get`, `upload`, `list`, or `delete`
|
|
|
|
Events MUST have the `content` set to a human readable string explaining to the user what the events inteded use is. For example `Upload Blob`, `Delete dog-picture.png`, `List Images`, etc
|
|
|
|
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.
|
|
|
|
Example event:
|
|
|
|
```json
|
|
{
|
|
"id": "bb653c815da18c089f3124b41c4b5ec072a40b87ca0f50bbbc6ecde9aca442eb",
|
|
"pubkey": "b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e",
|
|
"kind": 24242,
|
|
"content": "Upload bitcoin.pdf",
|
|
"created_at": 1708773959,
|
|
"tags": [
|
|
["t", "upload"],
|
|
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
|
|
["expiration", "1708858680"]
|
|
],
|
|
"sig": "d0d58c92afb3f4f1925120b99c39cffe77d93e82f488c5f8f482e8f97df75c5357175b5098c338661c37d1074b0a18ab5e75a9df08967bfb200930ec6a76562f"
|
|
}
|
|
```
|
|
|
|
Servers must perform the following checks in order to validate the event
|
|
|
|
1. The `kind` must be `24242`
|
|
2. `created_at` must be in the past
|
|
3. The `expiration` tag must be set to a Unix timespamp in the future
|
|
4. The `t` tag must have a verb matching the intended action of the endpoint
|
|
5. Additional checks for specific endpoints. `/upload`, `/delete`, etc
|
|
|
|
Using the `Authorization` HTTP header, the kind `24242` event MUST be base64 encoded and use the Authorization scheme Nostr
|
|
|
|
Example HTTP Authorization header:
|
|
|
|
```
|
|
Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQxNDA5ZDhiOTBjY2RiNGI0M2Y4ZjBmYzlkMGMiLCJwdWJrZXkiOiI5ZjBjYzE3MDIzYjJjZjUwOWUwZjFkMzA1NzkzZDIwZTdjNzIyNzY5MjhmZDliZjg1NTM2ODg3YWM1NzBhMjgwIiwiY3JlYXRlZF9hdCI6MTcwODc3MTIyNywia2luZCI6MjQyNDIsInRhZ3MiOltbInQiLCJnZXQiXSxbImV4cGlyYXRpb24iLCIxNzA4ODU3NTQwIl1dLCJjb250ZW50IjoiR2V0IEJsb2JzIiwic2lnIjoiMDJmMGQyYWIyM2IwNDQ0NjI4NGIwNzFhOTVjOThjNjE2YjVlOGM3NWFmMDY2N2Y5NmNlMmIzMWM1M2UwN2I0MjFmOGVmYWRhYzZkOTBiYTc1NTFlMzA4NWJhN2M0ZjU2NzRmZWJkMTVlYjQ4NTFjZTM5MGI4MzI4MjJiNDcwZDIifQ==
|
|
```
|
|
|
|
## 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
|
|
|
|
## Error Responses
|
|
|
|
For HTTP `4xx` and `5xx` status codes servers MUST repond with `Content-Type: application/json` and a JSON object containing `message`
|
|
|
|
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
|
|
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"}
|
|
```
|
|
|
|
## 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
|
|
|
|
The endpoint MUST accept an optional file extension in the URL. ie. `.pdf`, `.png`, etc
|
|
|
|
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)
|
|
|
|
The server may optionally require authorization when fetching blobs from the `GET /<sha256>` endpoint
|
|
|
|
In this case the server MUST perform additional checks on the authorization event
|
|
|
|
1. The `t` tag must be set to `get`
|
|
|
|
If the client did not send an `Authorization` header the server must respond with the appropriate HTTP status code `401` (Unauthorized)
|
|
|
|
Example Authorization event:
|
|
|
|
```json
|
|
{
|
|
"id": "3a2c0a58f88f86ab81ce7d111df57096e8cd9f41a75731a021e06e07c6df9d0e",
|
|
"pubkey": "96ddb0e7c4a5786a842094fee014d4c6cbb1f1627a8d75ef6fb601baeb6c5054",
|
|
"kind": 24242,
|
|
"content": "Get Blobs",
|
|
"created_at": 1708771927,
|
|
"tags": [
|
|
["t", "get"],
|
|
["expiration", "1708857340"]
|
|
],
|
|
"sig": "2f279b2ac0a5d5f7551f5612b69a111e038ab6b31233a78bfc98f63bd5e38ae8cb5929cf7427f0b7b2dd5eff29e769df23d93926326b0d059dc475701a41d6d3"
|
|
}
|
|
```
|
|
|
|
## 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
|