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"
```

### 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.