Paid storage

README.md

@@ -39,6 +39,7 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0
 - [BUD-02: Blob upload and management](./buds/02.md)
 - [BUD-03: User Server List](./buds/03.md)
 - [BUD-04: Mirroring blobs](./buds/04.md)
+- [BUD-07: Paid storage](./buds/07.md)
 
 ## Event kinds
 

buds/07.md

@@ -0,0 +1,69 @@
+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 recieved from the server and display the payment request to the user. If the payment is done, the client `SHOULD` use *the same macaroon* and the payment `preimage`to create a new `Www-Authenticate` header to be used in the next requests.
+
+Schema:
+
+```http
+Www-Authenticate: L402 macaroon="<macaroon>",preimage="<preimage>"
+```
+
+Example:
+
+```http
+Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",preimage="3e590d1336f241e858359c865802b4883ca91d47379c840af66785e2143bad22"
+```
+
+### Unpaid Uploads
+
+Some servers `MAY` accept unpaid uploads and require payment after the upload is completed. In this case, the server `MUST` return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the macaroon and payment request fields using the [L402 protocol](https://github.com/lightninglabs/L402) for the endpoints described in [#payment-required](#payment-required).
+
+For backward compatibility, the server `SHOULD` display a QR code, JSON file, or other useful information instead of the blob in the response body. When the payment is completed, the server `MUST` replace this information with the actual uploaded file.