laantungir
/
blossom
mirror of https://github.com/hzrd149/blossom.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into BUD07-paid-storage

This commit is contained in:
Quentin 2024-11-19 10:45:46 +01:00 committed by GitHub
parent 970fc2b072 afa1290a6a
commit 18a57e361c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 126 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -16,9 +16,10 @@ Blossom Servers expose four endpoints for managing blobs
- `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)
- `PUT /upload` [BUD-02](./buds/02.md#put-upload---upload-blob)
- `Authentication`: Signed [nostr event](./buds/02.md#upload-authorization-required)
- Return a blob descriptor
- `HEAD /upload` [BUD-06](./buds/06.md#head-upload---upload-requirements)
- `GET /list/<pubkey>` [BUD-02](./buds/02.md#get-listpubkey---list-blobs)
- Returns an array of blob descriptors
- `Authentication` _(optional)_: Signed [nostr event](./buds/02.md#list-authorization-optional)
@ -40,6 +41,8 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0
- [BUD-03: User Server List](./buds/03.md)
- [BUD-04: Mirroring blobs](./buds/04.md)
- [BUD-07: Paid storage](./buds/07.md)
- [BUD-06: Upload requirements](./buds/06.md)
- [BUD-08: Nostr File Metadata Tags](./buds/08.md)
## Event kinds

32
buds/01.md
View File

@ -8,7 +8,17 @@ _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
Servers MUST set the `Access-Control-Allow-Origin: *` header on all responses to ensure compatibility with applications hosted on other domains.
For [preflight](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests) (`OPTIONS`) requests,
servers MUST also set, at minimum, the `Access-Control-Allow-Headers: Authorization, *` and `Access-Control-Allow-Methods: GET, PUT,
DELETE` headers.
The header `Access-Control-Max-Age: 86400` MAY be set to cache the results of a preflight request for 24 hours.
## Error responses
Every time a server sends an error response (HTTP status codes >=400), it may include a human-readable header `X-Reason` that can be displayed to the user.
## Authorization events
@ -63,26 +73,6 @@ Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQ
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
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

6
buds/02.md
View File

@ -42,9 +42,9 @@ The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the upload was
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)
### Upload Authorization (Optional)
Servers MUST accept an authorization event when uploading blobs and should perform additional checks
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
@ -67,7 +67,7 @@ Example Authorization event:
}
```
## GET /list/pubkey - List Blobs
## 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

73
buds/06.md Normal file
View File

@ -0,0 +1,73 @@
# BUD-06
## Upload requirements
`draft` `optional`
Defines how clients can verify if the upload can be completed before sending the blob to the server. This mechanism helps prevent unnecessary traffic to other endpoints by rejecting files based on their hash, size, MIME type or other server-specific requirements.
## HEAD /upload - Upload requirements
The `HEAD /upload` endpoint `MUST` use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the SHA-256 hash, MIME type and size of the blob that will be uploaded, returning a HTTP status code and a custom header `X-Reason` to indicate some human readable message about the upload requirements.
### Headers
- `X-SHA-256`: A string that represents the blob's SHA-256 hash.
- `X-Content-Length`: An integer that represents the blob size in bytes.
- `X-Content-Type`: A string that specifies the blob's MIME type, like `application/pdf` or `image/png`.
### Upload Authorization
The `HEAD /upload` endpoint MAY accept an `upload` authorization event using the `Authorization` header similar to what is used in the [`PUT /upload`](./02.md#upload-authorization-required) endpoint
If the server requires authorization to upload it may respond with the `401` status code, or if authorization was provided and is invalid or not permitted it may respond with `403` status code
### Examples
Example request from the client:
```http
X-Content-Type: application/pdf
X-Content-Length: 184292
X-SHA-256: 88a74d0b866c8ba79251a11fe5ac807839226870e77355f02eaf68b156522576
```
Example response from the server if the upload can be done:
```http
HTTP/1.1 200 OK
```
If the upload cannot proceed, the server `MUST` return an appropriate `4xx` HTTP status code and a custom header `X-Reason` with a human readable error message.
Some examples of error messages:
```http
HTTP/1.1 400 Bad Request
X-Reason: Invalid X-SHA-256 header format. Expected a string.
```
```http
HTTP/1.1 401 Unauthorized
X-Reason: Authorization required for uploading video files.
```
```http
HTTP/1.1 403 Forbidden
X-Reason: SHA-256 hash banned.
```
```http
HTTP/1.1 411 Length Required
X-Reason: Missing X-Content-Length header.
```
```http
HTTP/1.1 413 Content Too Large
X-Reason: File too large. Max allowed size is 100MB.
```
```http
HTTP/1.1 415 Unsupported Media Type
X-Reason: Unsupported file type.
```

35
buds/08.md Normal file
View File

@ -0,0 +1,35 @@
# BUD-08
## Nostr File Metadata Tags
`draft` `optional`
Describes how a server could return nostr [NIP-94 File Metadata](https://github.com/nostr-protocol/nips/blob/master/94.md) tags from the `/upload` and `/mirror` endpoints
### Returning tags
As described in [BUD-02](./02.md#blob-descriptor) servers MAY add any additional fields to a blob descriptor
Servers MAY return an additional `nip94` field in the [blob descriptor](./02.md#blob-descriptor) from the `/upload` or `/mirror` endpoints
The `nip94` field should contain a JSON object with the keys being the tag names defined in [NIP-94](https://github.com/nostr-protocol/nips/blob/master/94.md)
An example response would look like:
```json
{
"url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
"sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
"size": 184292,
"type": "application/pdf",
"uploaded": 1725909682,
"nip94": {
"url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
"m": "application/pdf",
"x": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
"size": 184292,
"magnet": "magnet:?xt=urn:btih:9804c5286a3fb07b2244c968b39bc3cc814313bc&dn=bitcoin.pdf",
"i": "9804c5286a3fb07b2244c968b39bc3cc814313bc"
}
}
```