laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2026-08-10 16:13:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Format markdown with prettier

Browse Source
This commit is contained in:
hzrd149
2026-03-08 11:03:39 -03:00
parent 40c152d857
commit d14e24d5da
10 changed files with 65 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
buds/01.md
+2 -2
View File
@@ -46,8 +46,8 @@ guarantee this are:
1. Proxying the blob through the Blossom server, allowing it to override headers such as `Content-Type`.
2. Manipulating the redirect URL to include a file extension that matches the blob type, such as `.pdf`, `.png`, etc. If
the server is unable to determine the MIME type of the blob, it MUST default to `application/octet-stream` and MAY
include a file extension in the URL that reflects the blob type (e.g. `.bin`, `.dat`, etc.).
the server is unable to determine the MIME type of the blob, it MUST default to `application/octet-stream` and MAY
include a file extension in the URL that reflects the blob type (e.g. `.bin`, `.dat`, etc.).
### Get Authorization (optional)
buds/04.md
+1 -1
View File
@@ -15,7 +15,7 @@ Clients MUST pass the URL of the remote blob as a stringified JSON object in the
```jsonc
// request body...
{
"url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf"
"url": "https://cdn.satellite.earth/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
}
```
buds/07.md
+4 -6
View File
@@ -1,8 +1,6 @@
BUD-07
======
# BUD-07
Paid upload and download
---------------
## Paid upload and download
`draft` `optional`
@@ -46,7 +44,7 @@ When using the X-Cashu header, the server MUST adhere to the [NUT-24](https://gi
Example for cashu:
```http
```http
HTTP/1.1 402 Payment Required
X-Cashu: creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF4Imh0dHBzOi8vbm9mZWVzLnRlc3RudXQuY2FzaHUuc3BhY2U
```
@@ -71,7 +69,7 @@ The client MUST provide the payment proof when re-trying the request using the s
- For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md).
Schema:
```http
X-{payment_method}: "<encoded_payment_proof_according_to_{payment_method}_spec>"
```
buds/08.md
+19 -13
View File
@@ -18,18 +18,24 @@ 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"]
]
"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"]
]
}
```
buds/09.md
+1 -1
View File
@@ -17,7 +17,7 @@ Example:
"kind": 1984,
"tags": [
["x", "<blob-sha256>", "<type-based-on-nip-56>"],
["x", "<another-blob-sha256>", "<type-based-on-nip-56>"]
["x", "<another-blob-sha256>", "<type-based-on-nip-56>"],
],
"content": "<human readable report details>",
// other fields...
buds/10.md
+13
View File
@@ -41,11 +41,13 @@ The `as` parameter specifies the hex pubkey of a user who uploaded the blob. Thi
Clients can use this parameter to lookup the author's [BUD-03](./03.md) server list (`kind:10063`) and attempt to retrieve the blob from those servers.
Example:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0
```
Multiple authors:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036
```
@@ -57,16 +59,19 @@ The `xs` parameter specifies a server domain where the blob may be available. Th
The value SHOULD be a domain name only. Clients MUST assume the server operates at the root of the domain as per [BUD-01](./01.md#endpoints). The protocol scheme (http/https) MAY be included but is optional. When no scheme is specified, clients SHOULD try both `https://` and `http://` with preference given to `https://`.
Example:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth
```
With optional scheme:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth
```
Multiple servers:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net
```
@@ -81,6 +86,7 @@ The `sz` parameter MAY be used to specify the size of the blob in bytes. This ca
- Pre-allocate storage space
Example:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?sz=184292
```
@@ -131,6 +137,7 @@ When downloading is complete, if the `sz` parameter was provided, clients SHOULD
### Example Resolution Flow
Given this URI:
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
```
@@ -176,31 +183,37 @@ The `blossom:` URI schema enables several use cases:
## Examples
### Minimal URI
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
```
### Unknown File Type
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin
```
### With Single Server Hint
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth
```
### With Size and Author
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
```
### Full Featured URI
```
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
```
### Image with Multiple Authors and Servers
```
blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831
```
buds/11.md
+22 -22
View File
@@ -35,13 +35,13 @@ Example authorization token:
"pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
"created_at": 1772019044,
"tags": [
["t","upload"],
["expiration","1708858680"],
["t", "upload"],
["expiration", "1708858680"],
// Authorization token MAY have multiple "x" tags
["x","b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
],
"content": "",
"sig": "4b57c22b1797b109530ffe5d04cabac468b1a5942873a5141334ecbc77694fc968a1b941979ba13602fceb1dad8014ab6469c6ae9cef0b5668cc23ad1449e103"
"sig": "4b57c22b1797b109530ffe5d04cabac468b1a5942873a5141334ecbc77694fc968a1b941979ba13602fceb1dad8014ab6469c6ae9cef0b5668cc23ad1449e103",
}
```
@@ -70,17 +70,17 @@ To validate an authorization token, a server MUST perform the following checks:
The table below defines, for each endpoint, the required `t` tag action, the implied blob hash (if any), and whether at least one matching `x` tag is required.
| Endpoint | Required `t` | Implied Blob Hash | `x` Tag Requirement |
|----------------------|--------------|-------------------------------|---------------------|
| `GET /<sha256>` | `get` | `<sha256>` from the URL | optional |
| `HEAD /<sha256>` | `get` | `<sha256>` from the URL | optional |
| `PUT /upload` | `upload` | `X-SHA-256` request header | required |
| `HEAD /upload` | `upload` | `X-SHA-256` request header | required |
| `DELETE /<sha256>` | `delete` | `<sha256>` from the URL | required |
| `GET /list/<pubkey>` | `list` | — | not applicable |
| `PUT /mirror` | `upload` | SHA-256 of the mirrored blob | required |
| `PUT /media` | `media` | `X-SHA-256` request header | required |
| `HEAD /media` | `media` | `X-SHA-256` request header | required |
| Endpoint | Required `t` | Implied Blob Hash | `x` Tag Requirement |
| -------------------- | ------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /<sha256>` | `get` | `<sha256>` from the URL | optional |
| `HEAD /<sha256>` | `get` | `<sha256>` from the URL | optional |
| `PUT /upload` | `upload` | `X-SHA-256` request header | required |
| `HEAD /upload` | `upload` | `X-SHA-256` request header | required |
| `DELETE /<sha256>` | `delete` | `<sha256>` from the URL | required |
| `GET /list/<pubkey>` | `list` | — | not applicable |
| `PUT /mirror` | `upload` | SHA-256 of the mirrored blob | required |
| `PUT /media` | `media` | `X-SHA-256` request header | required |
| `HEAD /media` | `media` | `X-SHA-256` request header | required |
| `PATCH /upload` | `upload` | `X-SHA-256` request header | required (one `x` tag per chunk hash plus a final `x` tag for the complete blob hash; MAY be split across multiple auth events when chunk count is large) |
## Authorization Header Size Limits
@@ -89,13 +89,13 @@ HTTP servers impose limits on the size of individual request headers. Because th
A baseline kind-24242 event with one `x` tag encodes to approximately **636 bytes** as a header line. Each additional `x` tag (a 64-character hex sha256 hash) adds approximately **97 bytes** after base64url encoding.
| Server / proxy | Header limit | Max `x` tags |
|-----------------------------------------|-------------:|-------------:|
| Nginx (`large_client_header_buffers`) | 8,192 B | 78 |
| Apache (`LimitRequestFieldSize`) | 8,190 B | 78 |
| Cloudflare (max single header) | 16,384 B | 163 |
| IIS (`MaxRequestBytes`) | 16,384 B | 163 |
| Node.js / undici default | 16,384 B | 163 |
| Server / proxy | Header limit | Max `x` tags |
| ------------------------------------- | -----------: | -----------: |
| Nginx (`large_client_header_buffers`) | 8,192 B | 78 |
| Apache (`LimitRequestFieldSize`) | 8,190 B | 78 |
| Cloudflare (max single header) | 16,384 B | 163 |
| IIS (`MaxRequestBytes`) | 16,384 B | 163 |
| Node.js / undici default | 16,384 B | 163 |
The conservative safe limit across common deployments is **8,192 bytes**, which allows up to **78 `x` tags** per authorization event.
buds/12.md
+1 -1
View File
@@ -8,7 +8,7 @@ This bud defines a new `PATCH` method for the `/upload` endpoint to allow client
### Signaling support for multi-part uploads
The server SHOULD respond to an `OPTIONS /upload` request with a `204` "No Content" response according to [RFC-9110](https://httpwg.org/specs/rfc9110.html#rfc.section.9.3.7) including the [`Allow`](https://httpwg.org/specs/rfc9110.html#field.allow) header with `PATCH`
The server SHOULD respond to an `OPTIONS /upload` request with a `204` "No Content" response according to [RFC-9110](https://httpwg.org/specs/rfc9110.html#rfc.section.9.3.7) including the `[Allow](https://httpwg.org/specs/rfc9110.html#field.allow)` header with `PATCH`
### Upload requirements
implementations/README.md
-1
View File
@@ -10,4 +10,3 @@ This directory contains possible uses and implementations of the Blossom protoco
## Contributions
Contributions are welcome! Documents in this directory MUST be compatible with the existing [BUDs](../buds) and should be focused on a single use case or implementation.
implementations/hls-video-formatting.md
+2
View File
@@ -5,6 +5,7 @@ This document explains how to format [HLS](https://datatracker.ietf.org/doc/html
## Overview
HLS videos consist of multiple files:
- A master playlist (`.m3u8`) that references variant playlists
- Variant playlists (`.m3u8`) that reference media segments
- Media segment files (typically `.ts` files)
@@ -61,6 +62,7 @@ cd2a98d055eef5ec3aca73bd136a40340539138da73144d589d9de5a3a52149a.ts
Media segment files (typically `.ts` files) MUST be uploaded as separate blobs. Each segment MUST be retrievable via the [BUD-01](../buds/01.md#get-sha256---get-blob) `GET /<sha256>` endpoint.
The server SHOULD set the `Content-Type` header appropriately:
- `.ts` files: `video/mp2t` or `video/MP2T`
- `.m4s` files: `video/iso.segment` or `video/mp4`