Blossom/AuthToken.pm

filter: Statementstmt 82.6% 19 / 23 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 77.7% 7 / 9 Podpod n/a totaltotal 81.2% 26 / 32 CC 1 SCAR 2.3
CC
1
Cov
83%
__ANON__
2.0
__ANON__
2.0
BEGIN
1.3
CRAP 1.3
« Blossom/PaymentRequired.pm ↑ Summary Blossom.pm »
1 package Net::Blossom::AuthToken;
2  
3 4 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 4 ▶use Net::Blossom::_ConstructorArgs ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 4 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 4 ▶use Class::Tiny qw(key action content expiration server servers), {
Subroutine BEGIN: called CC=1 SCAR=0.6
9 0 ▶ hashes => sub { [] },
Subroutine __ANON__: not called CC=1 SCAR=6.9
10 0 ▶ created_at => sub { time() - 1 },
Subroutine __ANON__: not called CC=1 SCAR=6.9
11 4 };
12 4 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
13 4 ▶use MIME::Base64 qw(encode_base64);
Subroutine BEGIN: called CC=1 SCAR=0.0
14 0 ▶use Net::Nostr::Event;
Subroutine BEGIN: called CC=1 SCAR=2.6
15 use Scalar::Util qw(blessed);
16  
17 my $HEX64 = qr/\A[0-9a-f]{64}\z/;
18 my %ACTION = map { $_ => 1 } qw(get upload list delete media);
19 my $JSON = JSON->new->utf8->canonical;
20  
21 sub BUILDARGS {
22 my $class = shift;
23 my %args = Net::Blossom::_ConstructorArgs::normalize(@_);
24 my %known = map { $_ => 1 } qw(key action content expiration server servers hashes created_at);
25 my @unknown = grep { !exists $known{$_} } keys %args;
26 croak "unknown argument(s): " . join(', ', sort @unknown) if @unknown;
27  
28 return \%args;
29 }
30  
31 sub BUILD {
32 my ($self) = @_;
33  
34 croak "key is required" unless defined $self->key;
35 croak "key must provide pubkey_hex and sign_event"
36 unless blessed($self->key) && $self->key->can('pubkey_hex') && $self->key->can('sign_event');
37 croak "action is required" unless defined $self->action;
38 croak "action must be one of get, upload, list, delete, media"
39 unless $ACTION{$self->action};
40 croak "content is required" unless defined $self->content && length $self->content;
41 croak "expiration is required" unless defined $self->expiration;
42 croak "expiration must be a non-negative integer"
43 unless $self->expiration =~ /\A\d+\z/;
44 croak "expiration must be in the future"
45 unless $self->expiration > time;
46  
47 my @servers;
48 push @servers, $self->server if defined $self->server;
49 if (defined $self->servers) {
50 croak "servers must be an array reference" unless ref($self->servers) eq 'ARRAY';
51 push @servers, @{$self->servers};
52 }
53 for my $server (@servers) {
54 croak "server must be a lowercase domain name"
55 unless defined $server && !ref($server) && _valid_server_domain($server);
56 }
57 $self->servers(\@servers);
58  
59 $self->hashes([]) unless defined $self->hashes;
60 croak "hashes must be an array reference" unless ref($self->hashes) eq 'ARRAY';
61 for my $hash (@{$self->hashes}) {
62 croak "hash must be 64-char lowercase hex"
63 unless defined $hash && $hash =~ $HEX64;
64 }
65 croak $self->action . " authorization requires at least one hash"
66 if $self->action =~ /\A(?:upload|delete|media)\z/ && !@{$self->hashes};
67  
68 $self->created_at(time() - 1) unless defined $self->created_at;
69 croak "created_at must be a non-negative integer"
70 unless $self->created_at =~ /\A\d+\z/;
71  
72 return;
73 }
74  
75 sub to_event {
76 my ($self) = @_;
77 my @tags = (
78 ['t', $self->action],
79 ['expiration', '' . $self->expiration],
80 );
81 push @tags, map { ['server', $_] } @{$self->servers};
82 push @tags, map { ['x', $_] } @{$self->hashes};
83  
84 my $event = Net::Nostr::Event->new(
85 pubkey => $self->key->pubkey_hex,
86 kind => 24242,
87 created_at => $self->created_at,
88 tags => \@tags,
89 content => $self->content,
90 );
91 $self->key->sign_event($event);
92 return $event;
93 }
94  
95 sub authorization_header {
96 my ($self) = @_;
97 my $json = $JSON->encode($self->to_event->to_hash);
98 my $b64 = encode_base64($json, '');
99 $b64 =~ tr{+/}{-_};
100 $b64 =~ s/=+\z//;
101 return "Nostr $b64";
102 }
103  
104 sub _valid_server_domain {
105 my ($server) = @_;
106 return length($server) <= 253
107 && $server =~ /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*\z/;
108 }
109  
110 1;
111  
112 =pod
113  
114 =head1 NAME
115  
116 Net::Blossom::AuthToken - BUD-11 Blossom authorization token builder
117  
118 =head1 SYNOPSIS
119  
120 use Net::Blossom::AuthToken;
121  
122 my $token = Net::Blossom::AuthToken->new(
123 key => $key,
124 action => 'upload',
125 content => 'Upload Blob',
126 expiration => time + 300,
127 hashes => [$sha256],
128 );
129  
130 my $header = $token->authorization_header;
131  
132 =head1 DESCRIPTION
133  
134 C<Net::Blossom::AuthToken> builds BUD-11 Nostr authorization events and encodes
135 them as Blossom C<Authorization> header values.
136  
137 The C<key> argument must be an object that provides C<pubkey_hex> and
138 C<sign_event>. C<pubkey_hex> must return the Nostr public key as lowercase
139 64-character hex. C<sign_event> receives the C<Net::Nostr::Event> object,
140 signs it, and must leave the event with a valid signature.
141  
142 =head1 CONSTRUCTOR
143  
144 =head2 new
145  
146 my $token = Net::Blossom::AuthToken->new(%args);
147  
148 Required arguments:
149  
150 =over 4
151  
152 =item * C<key>
153  
154 A signing object that provides C<pubkey_hex> and C<sign_event>.
155  
156 =item * C<action>
157  
158 One of C<get>, C<upload>, C<list>, C<delete>, or C<media>.
159  
160 =item * C<content>
161  
162 The event content string.
163  
164 =item * C<expiration>
165  
166 Unix timestamp. It must be a non-negative integer and must be in the future.
167  
168 =back
169  
170 Optional arguments:
171  
172 =over 4
173  
174 =item * C<server>
175  
176 A lowercase DNS-style domain name for one server scope. This is a domain only,
177 not a URL. Empty labels and leading or trailing label hyphens are rejected.
178  
179 =item * C<servers>
180  
181 Array reference of lowercase DNS-style domain names for server scope.
182  
183 =item * C<hashes>
184  
185 Array reference of lowercase 64-character SHA-256 hashes. C<upload>,
186 C<delete>, and C<media> authorizations require at least one hash.
187  
188 =item * C<created_at>
189  
190 Unix timestamp for the Nostr event. Defaults to the previous Unix second.
191  
192 =back
193  
194 Unknown arguments or invalid values croak.
195  
196 =head1 ACCESSORS
197  
198 =head2 key
199  
200 Returns the signing object passed to C<new>.
201  
202 =head2 action
203  
204 Returns the BUD-11 action.
205  
206 =head2 content
207  
208 Returns the event content.
209  
210 =head2 expiration
211  
212 Returns the expiration timestamp.
213  
214 =head2 server
215  
216 Returns the original C<server> argument, when one was passed.
217  
218 =head2 servers
219  
220 Returns the normalized array reference of server domain names.
221  
222 =head2 hashes
223  
224 Returns the array reference of hash scopes.
225  
226 =head2 created_at
227  
228 Returns the event creation timestamp.
229  
230 =head1 METHODS
231  
232 =head2 to_event
233  
234 my $event = $token->to_event;
235  
236 Builds, signs, and returns a C<Net::Nostr::Event> for kind C<24242>.
237  
238 =head2 authorization_header
239  
240 my $header = $token->authorization_header;
241  
242 Returns the C<Nostr ...> C<Authorization> header value. The payload is canonical
243 JSON encoded as unpadded base64url.
244  
245 =head1 SEE ALSO
246  
247 L<Net::Blossom::Client>, L<Net::Nostr::Event>
248  
249 =head1 INTERNAL METHODS
250  
251 =head2 BUILDARGS
252  
253 Normalizes constructor arguments for Class::Tiny.
254  
255 =head2 BUILD
256  
257 Validates the constructed object for Class::Tiny.
258  
259 =cut
« Blossom/PaymentRequired.pm ↑ Summary Blossom.pm »