blossom/buds/02.md

BUD-02

Blob upload and management

draft optional

All pubkeys MUST be in hex format

Defines the /upload, /list and DELETE /<sha256> endpoints

Blob Descriptor

A blob descriptor is a JSON object containing url, sha256, size, type, and uploaded fields

• url A public facing url this blob can retrieved from
• sha256 The sha256 hash of the blob
• size The size of the blob in bytes
• type (optional) The MIME type of the blob
• uploaded The unix timestamp of when the blob was uploaded to the server

Servers may include additional fields in the descriptor like magnet, infohash, or ipfs depending on other protocols they support

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

The endpoint MUST return a 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

Upload Authorization (required)

Servers MUST accept an authorization event when uploading blobs and should perform additional checks

1. The t tag MUST be set to upload
2. The x tag MUST be present and set to the sha256 hash of the blob

Example Authorization event:

{
  "id": "bb653c815da18c089f3124b41c4b5ec072a40b87ca0f50bbbc6ecde9aca442eb",
  "pubkey": "b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e",
  "kind": 24242,
  "content": "Upload bitcoin.pdf",
  "created_at": 1708773959,
  "tags": [
    ["t", "upload"],
    ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
    ["expiration", "1708858680"]
  ],
  "sig": "d0d58c92afb3f4f1925120b99c39cffe77d93e82f488c5f8f482e8f97df75c5357175b5098c338661c37d1074b0a18ab5e75a9df08967bfb200930ec6a76562f"
}

GET /list/pubkey - List Blobs

The /list/<pubkey> endpoint MUST return a JSON array of Blob Descriptor that where uploaded by the specified pubkey

The endpoint MUST support a since and until query parameter to limit the returned blobs by their uploaded date

Servers may reject a list for any reason and MUST respond with the appropriate HTTP 4xx status code and an error message explaining the reason for the rejection

List Authorization (optional)

The server may optionally require Authorization when listing blobs uploaded by the pubkey

In this case the server must perform additional checks on the authorization event

1. The t tag must be set to list

Example Authorization event:

{
  "id": "cbb1cab9566355bfdf04e1f1fc1e655fe903ecc193e8a750092ee53beec2a0e8",
  "pubkey": "a5fc3654296e6de3cda6ba3e8eba7224fac8b150fd035d66b4c3c1dc2888b8fc",
  "kind": 24242,
  "content": "List Blobs",
  "created_at": 1708772350,
  "tags": [
    ["t", "list"],
    ["expiration", "1708858680"]
  ],
  "sig": "ff9c716f8de0f633738036472be553ce4b58dc71d423a0ef403f95f64ef28582ef82129b41d4d0ef64d2338eb4aeeb66dbc03f8b3a3ed405054ea8ecb14fa36c"
}

DELETE /sha256 - Delete Blob

Servers MUST accept DELETE requests to the /<sha256> endpoint

Servers may reject a delete request for any reason and should respond with the appropriate HTTP 4xx status code and an error message explaining the reason for the rejection

Delete Authorization (required)

Servers MUST accept an authorization event when deleting blobs

Servers should perform additional checks on the authorization event

1. The t tag must be set to delete
2. A x tag must be present and set to the sha256 hash of the blob being deleted

Example Authorization event:

{
  "id": "a92868bd8ea740706d931f5d205308eaa0e6698e5f8026a990e78ee34ce47fe8",
  "pubkey": "ae0063dd2c81ec469f2291ac029a19f39268bfc40aea7ab4136d7a858c3a06de",
  "kind": 24242,
  "content": "Delete bitcoin.pdf",
  "created_at": 1708774469,
  "tags": [
    ["t", "delete"],
    ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
    ["expiration", "1708858680"]
  ],
  "sig": "2ba9af680505583e3eb289a1624a08661a2f6fa2e5566a5ee0036333d517f965e0ffba7f5f7a57c2de37e00a2e85fd7999076468e52bdbcfad8abb76b37a94b0"
}