BUD-11

Nostr Authorization

draft optional

Defines the authorization token format used by blossom servers to identify users. Authorization tokens are optional and servers MAY require them for various endpoints.

Authorization tokens

Authorization tokens are signed nostr events proving to a server that the user (pubkey) has permitted an application to take an action on their behalf.

The authorization token MUST be a nostr event of kind 24242 and have a t tag with a verb of get, upload, list, delete, or media

Authorization tokens MUST have the content set to a human readable string explaining intended use. For example Upload Blob, Delete old blobs, List Images, etc

All authorization tokens MUST have a NIP-40 expiration tag set to a unix timestamp at which the token should be considered expired.

Tag scoping

Authorization tokens MAY include server and x tags to scope the token to specific servers or blob hashes.

server tag: Limits the token to specific servers by domain name. If no server tags are present, the token is valid for all servers. Multiple server tags may be present to allow the token to be used on multiple servers. The value MUST be a domain name only (e.g., cdn.example.com), not a full URL.
x tag: Scopes the token to specific blob hashes (similar to how server scopes to servers). Multiple x tags may be present for endpoints that require a sha256 hash. When x tags are present, the token is only valid for operations on the specified blob hashes.

Example authorization token:

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

Base validation

Servers must perform the following checks in order to validate the authorization token

The kind must be 24242
created_at must be in the past
The expiration tag must be set to a Unix timestamp in the future
The t tag must have a verb matching the intended action of the endpoint
If server tags are present, the server MUST verify that its domain name is present in at least one server tag. If no server tags are present, the token is valid for all servers.

HTTP Authorization header

Using the Authorization HTTP header, the authorization token (kind 24242) MUST be base64 encoded and use the Authorization scheme Nostr

Example HTTP Authorization header:

Authorization: Nostr eyJpZCI6IjhlY2JkY2RkNTMyOTIwMDEwNTUyNGExNDI4NzkxMzg4MWIzOWQxNDA5ZDhiOTBjY2RiNGI0M2Y4ZjBmYzlkMGMiLCJwdWJrZXkiOiI5ZjBjYzE3MDIzYjJjZjUwOWUwZjFkMzA1NzkzZDIwZTdjNzIyNzY5MjhmZDliZjg1NTM2ODg3YWM1NzBhMjgwIiwiY3JlYXRlZF9hdCI6MTcwODc3MTIyNywia2luZCI6MjQyNDIsInRhZ3MiOltbInQiLCJnZXQiXSxbImV4cGlyYXRpb24iLCIxNzA4ODU3NTQwIl1dLCJjb250ZW50IjoiR2V0IEJsb2JzIiwic2lnIjoiMDJmMGQyYWIyM2IwNDQ0NjI4NGIwNzFhOTVjOThjNjE2YjVlOGM3NWFmMDY2N2Y5NmNlMmIzMWM1M2UwN2I0MjFmOGVmYWRhYzZkOTBiYTc1NTFlMzA4NWJhN2M0ZjU2NzRmZWJkMTVlYjQ4NTFjZTM5MGI4MzI4MjJiNDcwZDIifQ==

Endpoint-specific requirements (example)

Individual endpoints may extend the base validation with additional requirements. The following are examples of how endpoints use authorization tokens:

/upload (BUD-02): May requires at least one x tag matching the sha256 hash of the blob being uploaded
DELETE /<sha256> (BUD-02): May requires at least one x tag matching the sha256 hash of the blob being deleted
PUT /media (BUD-05): May requires at least one x tag matching the sha256 hash of the media being uploaded
GET /<sha256> (BUD-01): May require either a server tag or at least one x tag matching the sha256 hash of the blob being retrieved
GET /list/<pubkey> (BUD-02): May require a server tag limiting the token to specific servers
PUT /mirror (BUD-04): May requires at least one x tag matching the sha256 hash of the blob being mirrored

See the respective BUD documents for the exact requirements for each endpoint. All endpoints that accept authorization tokens MUST perform the base validation checks defined above before performing any endpoint-specific checks.

4.7 KiB Raw Blame History