mirror of
https://github.com/hzrd149/blossom.git
synced 2026-08-08 23:34:41 +00:00
specified the header "X-SHA-256" and its use in authorization in both
/upload and /media.
This commit is contained in:
pippellia-btc
+9
-12
@@ -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 /<sha256>` 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 /<sha256>` 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.**
|
||||
|
||||
+11
-14
@@ -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.
|
||||
|
||||
+2
-2
@@ -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`.
|
||||
|
||||
|
||||
+7
-5
@@ -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 /<sha256>` | `get` | The `<sha256>` in the URL |
|
||||
| `HEAD /<sha256>` | `get` | The `<sha256>` 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 /<sha256>` | `delete` | The `<sha256>` in the URL |
|
||||
| `GET /list/<pubkey>` | `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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user