diff --git a/buds/02.md b/buds/02.md index 8046326..549fc35 100644 --- a/buds/02.md +++ b/buds/02.md @@ -20,7 +20,7 @@ A blob descriptor is a JSON object containing `url`, `sha256`, `size`, `type`, a Servers MUST include a file extension in the URL in the `url` field to allow clients to easily embed the URL in social posts or other content -Servers MAY include additional fields in the descriptor like `magnet`, `infohash`, or `ipfs` depending on other protocols they support +Servers MAY include additional fields in the descriptor like `magnet`, `infohash`, or `ipfs` depending on other protocols they support. Example: @@ -36,20 +36,17 @@ Example: ## PUT /upload - Upload Blob -The `PUT /upload` endpoint MUST accept binary data in the body of the request and MAY use the `Content-Type` and `Content-Length` headers to get the MIME type and size of the data +The `PUT /upload` endpoint MUST accept binary data in the request body. +The server MUST NOT modify the blob in any way and MUST compute the sha256 hash over the exact bytes received. This requirement ensures that users can re-upload blobs to other servers without discrepancies. -The endpoint MUST NOT modify the blob in any way and SHOULD return the exact same sha256 that was uploaded. This is critical to allow users to re-upload their blobs to new servers +Clients SHOULD include `Content-Type` and `Content-Length` headers specifying the MIME type and size of the data. Clients MAY provide an `X-SHA-256` header containing the lowercase hex-encoded sha256 of the request body. A server MAY use this value to enforce rejection policies or perform authorization checks prior to persisting the blob. -The endpoint MUST return a [Blob Descriptor](#blob-descriptor) if the upload was successful or an error object if it was not - -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 +On success, the endpoint MUST respond with a `2xx` status code with a [Blob Descriptor](#blob-descriptor) in the response body. +On failure, the endpoint MUST return an appropriate `4xx` status code and an error message explaining the reason for the rejection. ### File extension normalization (Optional) -When storing blobs, servers MAY normalise the file extension to a standard format (e.g. `.pdf`, `.png`, etc.) based on -the MIME type of the blob. This can be especially useful when the `GET /` endpoint is redirected to an external -URL (see the [proxying and redirection section from BUD-01](./01.md#proxying-and-redirection-optional)), as external -servers may rely on the file extension to serve the blob correctly. +When storing blobs, servers MAY normalise the file extension to a standard format (e.g. `.pdf`, `.png`, etc.) based on the MIME type of the blob. This can be especially useful when the `GET /` endpoint is redirected to an external URL (see the [proxying and redirection section from BUD-01](./01.md#proxying-and-redirection-optional)), as external servers may rely on the file extension to serve the blob correctly. ### Upload Authorization (Optional) @@ -69,7 +66,7 @@ Servers MAY reject a list request for any reason and MUST respond with the appro ### List Authorization -Servers MAY require authorization when listing blobs. See [BUD-11](./11.md#endpoint-authorization-requirements) for the required action and implied blob hash. +Servers MAY require authorization when listing blobs as defined by [BUD-11](./11.md#endpoint-authorization-requirements). ## DELETE /sha256 - Delete Blob @@ -79,4 +76,4 @@ Servers MAY reject a delete request for any reason and SHOULD respond with the a ### Delete Authorization -Servers MAY require authorization when deleting blobs. **Multiple `x` tags in the authorization token MUST NOT be interpreted as the user requesting to delete multiple blobs.** See [BUD-11](./11.md#endpoint-authorization-requirements) for the required action and implied blob hash. +Servers MAY require authorization when deleting blobs as defined by [BUD-11](./11.md#endpoint-authorization-requirements). **Multiple `x` tags in the authorization token MUST NOT be interpreted as the user requesting to delete multiple blobs.** diff --git a/buds/05.md b/buds/05.md index 72cdabc..4e3647f 100644 --- a/buds/05.md +++ b/buds/05.md @@ -8,13 +8,13 @@ Defines the `PUT /media` endpoint for processing and optimizing media ## PUT /media -The `PUT /media` endpoint MUST accept binary data in the body of the request and MAY use the `Content-Type` and `Content-Length` headers to get the MIME type and size of the media +The `PUT /media` endpoint MUST accept binary data in the request body. +The server SHOULD perform any optimizations or conversions it deems necessary in order to make the media more suitable for distribution. -The server should preform any optimizations or conversions it deems necessary in order to make the media more suitable for distribution +Clients SHOULD include `Content-Type` and `Content-Length` headers specifying the MIME type and size of the data. Clients MAY provide an `X-SHA-256` header containing the lowercase hex-encoded sha256 of the request body. A server MAY use this value to enforce rejection policies or perform authorization checks prior to persisting the blob. -The endpoint MUST respond with a `2xx` status and a [blob descriptor](./02.md#blob-descriptor) of the new processed blob - -Servers MAY reject media uploads for any reason and should respond with the appropriate HTTP `4xx` status code and an error message explaining the reason for the rejection +On success, the endpoint MUST respond with a `2xx` status code with a [Blob Descriptor](#blob-descriptor) in the response body. +On failure, the endpoint MUST return an appropriate `4xx` status code and an error message explaining the reason for the rejection. ### Upload Authorization @@ -26,18 +26,15 @@ Servers MUST respond to `HEAD` requests on the `/media` endpoint in a similar wa ## Limitations -This endpoint is intentionally limited to optimizing a single blob with the goal of making it easier to distribute +The goal of this endpoint is to provide a simple "trusted" optimization endpoint clients can use to optimize media for distribution. +How the blob is optimized is the sole responsibility of the server and the client should have no say in what optimization process is used. -How the blob is optimized is the sole responsibility of the server and the client should have no say in what optimization process is used - -The goal of this endpoint is to provide a simple "trusted" optimization endpoint clients can use to optimize media for distribution - -If a longer optimization or transformation process is needed, or if the client needs to specify how a blob should be transformed. there are other tools and protocol that should be used. +If a longer optimization or transformation process is needed, or if the client needs to specify how a blob should be transformed, other protocols should be used. ## Client Implementation -Clients MAY let a user selected a "trusted processing" server for uploading images or short videos +Clients MAY let a user selected a "trusted processing" server for uploading images or short videos. -Once a server has been selected, the client uploads the original media to the `/media` endpoint of the trusted server and get the optimized blob back +Once a server has been selected, the client uploads the original media to the `/media` endpoint of the trusted server and get the optimized blob back. -Then the client can ask the user to sign another `upload` authorization token for the new optimized blob and call the `/mirror` endpoint on other servers to distribute the blob +Then the client can call the `/mirror` endpoint on other servers to distribute the blob. diff --git a/buds/06.md b/buds/06.md index dfb7cc7..691c0e9 100644 --- a/buds/06.md +++ b/buds/06.md @@ -8,11 +8,11 @@ Defines how clients can verify if the upload can be completed before sending the ## 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. +The `HEAD /upload` endpoint MUST use the `X-SHA-256`, `X-Content-Type` and `X-Content-Length` headers sent by client to get the sha256 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-SHA-256`: A lowercase hex-encoded sha256 string that represents the blob's 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`. diff --git a/buds/11.md b/buds/11.md index f75b06a..bd98469 100644 --- a/buds/11.md +++ b/buds/11.md @@ -67,19 +67,21 @@ Servers must perform the following checks in order to validate the authorization ## Endpoint Authorization Requirements -The following table defines, for each endpoint, the required `t` tag action and the implied blob hash (if any). If an endpoint has an implied blob hash, the token MUST include at least one `x` tag whose value matches that hash. +The following table defines, for each endpoint, the required `t` tag action and the implied blob hash (if any). The token MUST include at least one `x` tag whose value matches the implied blob hash. +If an endpoint has an implied blob hash and it cannot be determined (e.g. missing `X-SHA-256` header), authorization MUST fail. + | Endpoint | Action | Implied blob hash | | -------------------- | -------- | ------------------------------------------ | | `GET /` | `get` | The `` in the URL | | `HEAD /` | `get` | The `` in the URL | -| `PUT /upload` | `upload` | sha256 of the request body | -| `HEAD /upload` | `upload` | sha256 from the `X-SHA-256` request header | +| `PUT /upload` | `upload` | `X-SHA-256` request header | +| `HEAD /upload` | `upload` | `X-SHA-256` request header | | `DELETE /` | `delete` | The `` in the URL | | `GET /list/` | `list` | — | | `PUT /mirror` | `upload` | sha256 of the mirrored blob | -| `PUT /media` | `media` | sha256 of the request body | -| `HEAD /media` | `media` | sha256 from the `X-SHA-256` request header | +| `PUT /media` | `media` | `X-SHA-256` request header | +| `HEAD /media` | `media` | `X-SHA-256` request header | ## Security Considerations