NAME

Net::Blossom::Server::Authorization - BUD-11 server authorization verifier

SYNOPSIS

use Net::Blossom::Server::Authorization;

my $auth = Net::Blossom::Server::Authorization->new(
    domains => ['cdn.example.com'],
);

my $pubkey = $auth->authorize_request($request);
my $result = $auth->authorize($request);

DESCRIPTION

Net::Blossom::Server::Authorization validates BUD-11 Blossom authorization tokens. It parses Nostr authorization headers, verifies the Nostr event ID and signature with Net::Nostr::Event, checks the BUD-11 tags, and returns the event pubkey.

Authorization failures throw Net::Blossom::Server::Error with status 401 and WWW-Authenticate: Nostr.

CONSTRUCTOR

new

my $auth = Net::Blossom::Server::Authorization->new(%args);

Optional arguments:

• domains

  Array reference of lowercase server domain names. These are used to validate BUD-11 server tags. They are domains only, not URLs.

• clock

  Code reference returning the current Unix timestamp. Defaults to time.

• clock_skew_seconds

  Non-negative integer number of seconds by which created_at may be ahead of the verifier clock. Defaults to 30. Set to 0 to require created_at to be strictly in the past.

Unknown arguments or invalid values croak.

ACCESSORS

domains

Returns a copy array reference of configured server domains.

clock

Returns the clock code reference.

clock_skew_seconds

Returns the accepted created_at clock skew in seconds.

METHODS

authorize_request

my $pubkey = $auth->authorize_request($request);

Validates the request's BUD-11 Authorization header and returns the verified event pubkey. The request must be a Net::Blossom::Server::Request.

authorize

my $result = $auth->authorize($request);

Validates the request and returns a Net::Blossom::Server::AuthorizationResult. This method is useful for endpoints such as PUT /mirror, where the authorized hash is not known until after the server fetches and hashes the origin blob.

Implemented endpoint requirements are GET /<sha256>, HEAD /<sha256>, PUT /upload, HEAD /upload, DELETE /<sha256>, GET /list/<pubkey>, PUT /mirror, PUT /media, and HEAD /media. Unknown routes return undef so the server core can return its normal routing response.