mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-13 07:58:49 +00:00
67 lines
4.1 KiB
Markdown
67 lines
4.1 KiB
Markdown
BUD-07
|
|
======
|
|
|
|
Paid storage
|
|
---------------
|
|
|
|
`draft` `optional`
|
|
|
|
Payment requirements for blob storage.
|
|
|
|
## Payment Required
|
|
|
|
Some servers MAY require payment for file storage. In that case, these endpoints MUST return a **402 Payment Required** status code and a `Www-Authenticate` header when the payment is required.
|
|
|
|
- [HEAD /upload](./01.md#head-sha256---has-blob)
|
|
- [PUT /upload](./02.md#put-upload---upload-blob)
|
|
- [HEAT /<sha256>](./01.md#head-sha256---has-blob)
|
|
- [GET /<sha256>](./01.md#get-sha256---get-blob)
|
|
|
|
|
|
## Authenticate header
|
|
|
|
The `Www-Authenticate` header is a standard HTTP header field that defines the authentication method that should be used to gain access to a resource. It is used by the server to challenge the client to authenticate itself. Using the [L402 protocol](https://github.com/lightninglabs/L402), the `Www-Authenticate` header can be used to request payment for specific blobs.
|
|
|
|
The `Www-Authenticate` header contains the `macaroon` and `invoice` fields for servers and the `macaroon` and `preimage` fields for clients.
|
|
|
|
- `macaroon` A base64 encoded string containing the macaroon, see [L402 macaroons](https://github.com/lightninglabs/L402/blob/master/macaroons.md).
|
|
- `invoice` A string containing LN the payment request.
|
|
- `preimage` A string containing the payment preimage.
|
|
|
|
### Server implementation
|
|
|
|
Servers MUST return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the `macaroon` and `invoice` fields using the [L402 protocol](https://github.com/lightninglabs/L402) for all requests related to the blob:
|
|
|
|
Schema:
|
|
|
|
```http
|
|
HTTP/1.1 402 Payment Required
|
|
Www-Authenticate: L402 macaroon="<macaroon>",invoice="<invoice>"
|
|
```
|
|
|
|
Example:
|
|
|
|
```http
|
|
HTTP/1.1 402 Payment Required
|
|
Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",invoice="lnbc30n1pnvscg5pp56rft56xqcdamm59epsvmes06ymctq7gjt3nfnu3mjaw6fmfuhweqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5a5tz8qqf897a2psdh3gc8m72tkpfwf03p8j95tgvkwm0jx97ypqs9qxpqysgqxuv6h48rzmguqkyxdyegrwf2m9890st2mty7z68acvcp9s8ukpx5daja0tdfq4tn2lmt443kua45zh6dzuy90grz02hcfauqx999g4gpf9lqhw"
|
|
```
|
|
|
|
### Client implementation
|
|
|
|
Clients SHOULD check the `Www-Authenticate` header received from the server and display the payment request to the user. When the payment is complete the client should use *the same macaroon* and the payment `preimage` to create a new `Www-Authenticate` header to be used in the next request.
|
|
|
|
Schema:
|
|
|
|
```http
|
|
Www-Authenticate: L402 macaroon="<macaroon>",preimage="<preimage>"
|
|
```
|
|
|
|
Example:
|
|
|
|
```http
|
|
Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",preimage="3e590d1336f241e858359c865802b4883ca91d47379c840af66785e2143bad22"
|
|
```
|
|
|
|
### Backward compatibility
|
|
|
|
For backward compatibility, when a client requests an unpaid blob, the server SHOULD return alternative information, such as a QR code, a JSON file, or other useful data in the response body. This serves as a placeholder, clearly indicating that the actual file is unavailable until payment is made. Once the payment is completed, the server MUST replace this placeholder with the actual blob in subsequent requests. This ensures that legacy clients still receive meaningful responses without breaking functionality, while supporting the new payment logic. |