Identifier.pm

filter: Statementstmt 96.9% 128 / 132 Branchbran 96.8% 62 / 64 Conditioncond 90.9% 20 / 22 MC/DCmcdc 83.3% 10 / 12 Subroutinesub 100% 20 / 20 Podpod 100% 8 / 8 totaltotal 96.1% 248 / 258 CC 43 SCAR 16.2
CC
43
Cov
96%
parse
8.0
__ANON__
7.4
verify
7.0
CRAP 5.1
« Bech32.pm ↑ Summary _ConstructorArgs.pm »
1 package Net::Nostr::Identifier;
2  
3 2 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 2 ▶use Net::Nostr::_ConstructorArgs ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use Net::Nostr::_URI qw(build_nip05_url validate_http_base_url);
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 2 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 2 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 2 ▶use Class::Tiny qw(
Subroutine BEGIN: called CC=1 SCAR=0.0
12 base_url
13 2 );
14  
15 39 ▶sub new {
Subroutine new: called CC=3 SCAR=11.0
Pod documented
16 39 my $class = shift;
17 39 my $self = bless { Net::Nostr::_ConstructorArgs::normalize(@_) }, $class;
18 39 my %known; @known{Class::Tiny->get_all_attributes_for($class)} = ();
19 39 my @unknown = grep { !exists $known{$_} } keys %$self;
20 39 ▶ croak "unknown argument(s): " . join(', ', sort @unknown) if @unknown;
Branch: 1 branch
BranchTrueFalseTotal
if @unknown 1 38 39
21 $self->{base_url} = validate_http_base_url($self->{base_url}, label => 'base_url')
22 38 ▶ if defined $self->{base_url};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"base_url"} 23 15 38
23 29 return $self;
24 }
25  
26 71 ▶sub parse {
Subroutine parse: called CC=8 SCAR=20.8
Pod documented
27 71 my ($class, $identifier) = @_;
28 71 ▶ croak "invalid NIP-05 identifier: missing \@"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $identifier and $identifier =~ /@/ 7 64 71
Condition100%3/3
defined $identifier and $identifier =~ /@/
!ll&&!rl&&r
1664
MC/DC100%2/2
defined $identifier and $identifier =~ /@/
defined $identifier $identifier =~ /@/
Truth table100%3/3
A and B
A= defined $identifierB= $identifier =~ /@/
ABresult
0X0
100
111
29 unless defined $identifier && $identifier =~ /@/;
30 64 my @parts = split /@/, $identifier, -1;
31 64 ▶ croak "invalid NIP-05 identifier: multiple \@" if @parts > 2;
Branch: 1 branch
BranchTrueFalseTotal
if @parts > 2 2 62 64
32 62 my ($local, $domain) = @parts;
33 62 ▶ croak "invalid NIP-05 identifier: empty local-part"
Branch: 1 branch
BranchTrueFalseTotal
unless length $local 2 60 62
34 unless length $local;
35 60 ▶ croak "invalid NIP-05 identifier: empty domain"
Branch: 1 branch
BranchTrueFalseTotal
unless length $domain 2 58 60
36 unless length $domain;
37 58 ▶ croak "invalid NIP-05 identifier: local-part contains invalid characters (must be a-z0-9-_.)"
Branch: 1 branch
BranchTrueFalseTotal
unless $local =~ /\A[a-z0-9\-_.]+\z/ 7 51 58
38 unless $local =~ /\A[a-z0-9\-_.]+\z/;
39 51 ▶ croak "invalid NIP-05 identifier: domain contains invalid characters"
Branch: 1 branch
BranchTrueFalseTotal
if $domain =~ m([\s/:?\#\[\]\x00-\x1f\x7f]) 15 36 51
40 if $domain =~ m{[\s/:?\#\[\]\x00-\x1f\x7f]};
41 36 return ($local, $domain);
42 }
43  
44 5 ▶sub url {
Subroutine url: called CC=1 SCAR=0.0
Pod documented
45 5 my ($class, $identifier) = @_;
46 5 my ($local, $domain) = $class->parse($identifier);
47 4 return build_nip05_url("https://$domain", $local);
48 }
49  
50 5 ▶sub display_name {
Subroutine display_name: called CC=2 SCAR=6.9
Pod documented
51 5 my ($class, $identifier) = @_;
52 5 my ($local, $domain) = $class->parse($identifier);
53 4 ▶ return $domain if $local eq '_';
Branch: 1 branch
BranchTrueFalseTotal
if $local eq "_" 2 2 4
54 2 return $identifier;
55 }
56  
57 30 ▶sub verify_response {
Subroutine verify_response: called CC=6 SCAR=17.9
Pod documented
58 30 my ($class, $response, $local_part, $pubkey) = @_;
59 30 ▶ return 0 unless ref $response eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $response eq "HASH" 6 24 30
60 24 ▶ return 0 unless ref($response->{names}) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $response->{"names"} eq "HASH" 5 19 24
61 19 my $found = $response->{names}{$local_part};
62 19 ▶ return 0 unless defined $found;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $found 2 17 19
63 # Keys must be 64-char lowercase hex (32-byte pubkey)
64 17 ▶ return 0 unless $found =~ /\A[a-f0-9]{64}\z/;
Branch: 1 branch
BranchTrueFalseTotal
unless $found =~ /\A[a-f0-9]{64}\z/ 6 11 17
65 11 ▶ return $found eq $pubkey ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$found eq $pubkey ? : 7 4 11
66 }
67  
68 15 ▶sub extract_relays {
Subroutine extract_relays: called CC=4 SCAR=13.9
Pod documented
69 15 my ($class, $response, $pubkey) = @_;
70 15 ▶ return [] unless ref $response eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $response eq "HASH" 2 13 15
71 13 ▶ return [] unless ref($response->{relays}) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $response->{"relays"} eq "HASH" 4 9 13
72 9 my $list = $response->{relays}{$pubkey};
73 9 ▶ return [] unless ref $list eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $list eq "ARRAY" 3 6 9
74 6 return $list;
75 }
76  
77 13 ▶sub _require_http {
Subroutine _require_http: called CC=3 SCAR=11.0
78 13 my ($method) = @_;
79 13 ▶ return if eval { require AnyEvent::HTTP; 1 };
Branch: 1 branch
BranchTrueFalseTotal
if eval { do { require AnyEvent::HTTP; 1 } } 11 2 13
80 2 ▶ my $error = $@ || 'unknown error';
Condition50%1/2
$@ || 'unknown error'
l!l
20
MC/DC0%0/1
$@ || 'unknown error'
$@
Truth table50%1/2
A
A= $@
Aresult
11
00
81 2 chomp $error;
82 2 croak "AnyEvent::HTTP is an optional dependency required by Net::Nostr::Identifier::$method; install AnyEvent::HTTP or install the Net::Nostr shim distribution ($error)";
83 }
84  
85 11 ▶sub _fetch {
Subroutine _fetch: called CC=1 SCAR=0.0
86 11 my ($self, $url, $cb) = @_;
87 AnyEvent::HTTP::http_request(
88 GET => $url,
89 recurse => 0, # MUST ignore redirects
90 11 ▶ sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
91 11 my ($body, $headers) = @_;
92 11 $cb->($body, $headers);
93 },
94 11 );
95 }
96  
97 16 ▶sub _build_fetch_url {
Subroutine _build_fetch_url: called CC=2 SCAR=6.9
98 16 my ($self, $identifier) = @_;
99 16 my ($local, $domain) = Net::Nostr::Identifier->parse($identifier);
100 14 ▶ if (defined $self->base_url) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->base_url) 12 2 14
101 12 return (build_nip05_url($self->base_url, $local), $local);
102 }
103 2 return (build_nip05_url("https://$domain", $local), $local);
104 }
105  
106 15 ▶sub verify {
Subroutine verify: called CC=7 SCAR=19.5
Pod documented
107 15 my $self = shift;
108 15 my %args = Net::Nostr::_ConstructorArgs::normalize(@_);
109 15 ▶ my $identifier = $args{identifier} // croak "identifier required";
Condition100%2/2
$args{"identifier"} // croak("identifier required")
l!l
141
MC/DC100%1/1
$args{"identifier"} // croak("identifier required")
$args{"identifier"}
Truth table100%2/2
A
A= $args{"identifier"}
Aresult
11
00
110 14 ▶ my $pubkey = $args{pubkey} // croak "pubkey required";
Condition100%2/2
$args{"pubkey"} // croak("pubkey required")
l!l
131
MC/DC100%1/1
$args{"pubkey"} // croak("pubkey required")
$args{"pubkey"}
Truth table100%2/2
A
A= $args{"pubkey"}
Aresult
11
00
111 13 ▶ my $on_success = $args{on_success} // croak "on_success callback required";
Condition100%2/2
$args{"on_success"} // croak("on_success callback required")
l!l
121
MC/DC100%1/1
$args{"on_success"} // croak("on_success callback required")
$args{"on_success"}
Truth table100%2/2
A
A= $args{"on_success"}
Aresult
11
00
112 12 ▶ croak "on_success must be a CODE ref" unless ref($on_success) eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $on_success eq "CODE" 2 10 12
113 10 ▶ my $on_failure = $args{on_failure} // croak "on_failure callback required";
Condition100%2/2
$args{"on_failure"} // croak("on_failure callback required")
l!l
91
MC/DC100%1/1
$args{"on_failure"} // croak("on_failure callback required")
$args{"on_failure"}
Truth table100%2/2
A
A= $args{"on_failure"}
Aresult
11
00
114 9 ▶ croak "on_failure must be a CODE ref" unless ref($on_failure) eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $on_failure eq "CODE" 1 8 9
115  
116 8 my ($url, $local) = $self->_build_fetch_url($identifier);
117  
118 7 _require_http('verify');
119  
120 6 ▶ $self->_fetch($url, sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
121 6 my ($body, $headers) = @_;
122  
123 # Check for redirect (status 3xx)
124 6 ▶ if ($headers->{Status} =~ /^3/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($headers->{"Status"} =~ /^3/) 1 5 6
125 1 $on_failure->("redirect: server returned HTTP $headers->{Status}");
126 1 return;
127 }
128  
129 5 ▶ unless ($headers->{Status} =~ /^2/) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($headers->{"Status"} =~ /^2/) 1 4 5
130 1 $on_failure->("HTTP error: $headers->{Status} $headers->{Reason}");
131 1 return;
132 }
133  
134 4 my $response = eval { JSON::decode_json($body) };
135 4 ▶ unless ($response) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($response) 1 3 4
136 1 $on_failure->("invalid JSON response");
137 1 return;
138 }
139  
140 3 ▶ if (Net::Nostr::Identifier->verify_response($response, $local, $pubkey)) {
Branch: 1 branch
BranchTrueFalseTotal
if ('Net::Nostr::Identifier'->verify_response($response, $local, $pubkey)) { } 2 1 3
141 2 my $relays = Net::Nostr::Identifier->extract_relays($response, $pubkey);
142 2 $on_success->($relays);
143 } else {
144 1 $on_failure->("pubkey mismatch for $local");
145 }
146 6 });
147 }
148  
149 12 ▶sub lookup {
Subroutine lookup: called CC=6 SCAR=18.0
Pod documented
150 12 my $self = shift;
151 12 my %args = Net::Nostr::_ConstructorArgs::normalize(@_);
152 12 ▶ my $identifier = $args{identifier} // croak "identifier required";
Condition100%2/2
$args{"identifier"} // croak("identifier required")
l!l
111
MC/DC100%1/1
$args{"identifier"} // croak("identifier required")
$args{"identifier"}
Truth table100%2/2
A
A= $args{"identifier"}
Aresult
11
00
153 11 ▶ my $on_success = $args{on_success} // croak "on_success callback required";
Condition100%2/2
$args{"on_success"} // croak("on_success callback required")
l!l
101
MC/DC100%1/1
$args{"on_success"} // croak("on_success callback required")
$args{"on_success"}
Truth table100%2/2
A
A= $args{"on_success"}
Aresult
11
00
154 10 ▶ croak "on_success must be a CODE ref" unless ref($on_success) eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $on_success eq "CODE" 1 9 10
155 9 ▶ my $on_failure = $args{on_failure} // croak "on_failure callback required";
Condition100%2/2
$args{"on_failure"} // croak("on_failure callback required")
l!l
81
MC/DC100%1/1
$args{"on_failure"} // croak("on_failure callback required")
$args{"on_failure"}
Truth table100%2/2
A
A= $args{"on_failure"}
Aresult
11
00
156 8 ▶ croak "on_failure must be a CODE ref" unless ref($on_failure) eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $on_failure eq "CODE" 1 7 8
157  
158 7 my ($url, $local) = $self->_build_fetch_url($identifier);
159  
160 6 _require_http('lookup');
161  
162 5 ▶ $self->_fetch($url, sub {
Subroutine __ANON__: called CC=7 SCAR=20.1
163 5 my ($body, $headers) = @_;
164  
165 5 ▶ if ($headers->{Status} =~ /^3/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($headers->{"Status"} =~ /^3/) 1 4 5
166 1 $on_failure->("redirect: server returned HTTP $headers->{Status}");
167 1 return;
168 }
169  
170 4 ▶ unless ($headers->{Status} =~ /^2/) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($headers->{"Status"} =~ /^2/) 0 4 4
171 0 $on_failure->("HTTP error: $headers->{Status} $headers->{Reason}");
172 0 return;
173 }
174  
175 4 my $response = eval { JSON::decode_json($body) };
176 4 ▶ unless ($response) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($response) 0 4 4
177 0 $on_failure->("invalid JSON response");
178 0 return;
179 }
180  
181 4 ▶ unless (ref($response->{names}) eq 'HASH' && defined $response->{names}{$local}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $response->{"names"} eq "HASH" and defined $response->{"names"}{$local}) 1 3 4
Condition66%2/3
ref $response->{"names"} eq "HASH" and defined $response->{"names"}{$local}
!ll&&!rl&&r
013
MC/DC50%1/2
ref $response->{"names"} eq "HASH" and defined $response->{"names"}{$local}
ref $response->{"names"} eq "HASH" defined $response->{"names"}{$local}
Truth table66%2/3
A and B
A= ref $response->{"names"} eq "HASH"B= defined $response->{"names"}{$local}
ABresult
0X0
100
111
182 1 $on_failure->("name '$local' not found");
183 1 return;
184 }
185  
186 3 my $pubkey = $response->{names}{$local};
187 3 ▶ unless ($pubkey =~ /\A[a-f0-9]{64}\z/) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($pubkey =~ /\A[a-f0-9]{64}\z/) 2 1 3
188 2 $on_failure->("invalid pubkey format");
189 2 return;
190 }
191  
192 1 my $relays = Net::Nostr::Identifier->extract_relays($response, $pubkey);
193 1 $on_success->($pubkey, $relays);
194 5 });
195 }
196  
197 2 1;
198  
199 =head1 NAME
200  
201 Net::Nostr::Identifier - Mapping Nostr keys to DNS-based internet identifiers
202  
203 =head1 SYNOPSIS
204  
205 use AnyEvent;
206 use Net::Nostr::Identifier;
207  
208 my $pubkey = 'b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9';
209  
210 # Parse and validate an identifier
211 my ($local, $domain) = Net::Nostr::Identifier->parse('bob@example.com');
212  
213 # Build the well-known URL
214 my $url = Net::Nostr::Identifier->url('bob@example.com');
215 # https://example.com/.well-known/nostr.json?name=bob
216  
217 # Display name (root identifier _@domain shows as domain)
218 Net::Nostr::Identifier->display_name('bob@example.com'); # "bob@example.com"
219 Net::Nostr::Identifier->display_name('_@bob.com'); # "bob.com"
220  
221 # Verify a nostr.json response
222 my $response = { names => { bob => $pubkey } };
223 if (Net::Nostr::Identifier->verify_response($response, 'bob', $pubkey)) {
224 print "Verified!\n";
225 }
226  
227 # Async verification via HTTP (requires AnyEvent and AnyEvent::HTTP)
228 my $cv = AnyEvent->condvar;
229 my $ident = Net::Nostr::Identifier->new;
230 $ident->verify(
231 identifier => 'bob@example.com',
232 pubkey => $pubkey,
233 on_success => sub { my ($relays) = @_; print "Verified!\n"; $cv->send },
234 on_failure => sub { my ($reason) = @_; warn "Failed: $reason"; $cv->send },
235 );
236 $cv->recv;
237  
238 # Async lookup (find pubkey from identifier)
239 $cv = AnyEvent->condvar;
240 $ident->lookup(
241 identifier => 'bob@example.com',
242 on_success => sub { my ($pubkey, $relays) = @_; $cv->send },
243 on_failure => sub { my ($reason) = @_; $cv->send },
244 );
245 $cv->recv;
246  
247 =head1 DESCRIPTION
248  
249 Implements NIP-05 for mapping Nostr public keys to DNS-based internet
250 identifiers. An identifier has the form C<local-part@domain> where the
251 local-part uses only characters C<a-z0-9-_.>.
252  
253 Clients verify an identifier by fetching
254 C<https://E<lt>domainE<gt>/.well-known/nostr.json?name=E<lt>local-partE<gt>>
255 and checking that the returned C<"names"> mapping contains the expected
256 public key.
257  
258 The special identifier C<_@domain> is treated as a root identifier and
259 may be displayed as just the domain.
260  
261 =head1 OPTIONAL HTTP DEPENDENCY
262  
263 Pure helpers such as C<parse>, C<url>, C<display_name>, C<verify_response>, and
264 C<extract_relays> do not load an HTTP client.
265  
266 The network methods C<lookup> and C<verify> lazy-load L<AnyEvent::HTTP>. The
267 L<Net::Nostr::Core> distribution recommends C<AnyEvent::HTTP> but does not
268 require it. Installing the L<Net::Nostr> shim distribution pulls it in as a hard
269 dependency for the full-stack install.
270  
271 =head1 CLASS METHODS
272  
273 =head2 parse
274  
275 my ($local_part, $domain) = Net::Nostr::Identifier->parse('bob@example.com');
276  
277 Splits an identifier into its local-part and domain. Strictly validates
278 both parts. Croaks if the identifier is invalid:
279  
280 =over 4
281  
282 =item * missing or multiple C<@>
283  
284 =item * empty local-part or domain
285  
286 =item * local-part contains characters outside C<a-z0-9-_.>
287  
288 =item * domain contains whitespace, C</>, C<:>, C<?>, C<#>, C<[>, C<]>, or control characters
289  
290 =back
291  
292 Bracketed IPv6 addresses (e.g. C<[::1]>) are rejected because NIP-05 is
293 DNS-based. Ports are rejected because the spec constructs HTTPS URLs from
294 the domain directly.
295  
296 =head2 url
297  
298 my $url = Net::Nostr::Identifier->url('bob@example.com');
299  
300 Returns the well-known URL for verifying the identifier.
301  
302 =head2 display_name
303  
304 my $name = Net::Nostr::Identifier->display_name('bob@example.com'); # "bob@example.com"
305 my $root = Net::Nostr::Identifier->display_name('_@bob.com'); # "bob.com"
306  
307 Returns the display form of the identifier. Root identifiers (C<_@domain>)
308 are displayed as just the domain. All other identifiers are returned as-is.
309  
310 =head2 verify_response
311  
312 my $ok = Net::Nostr::Identifier->verify_response($hashref, $local_part, $pubkey);
313  
314 Returns true if the response hashref maps the given local-part to the given
315 pubkey. Keys must be 64-character lowercase hex (32-byte public keys).
316  
317 =head2 extract_relays
318  
319 my $relays = Net::Nostr::Identifier->extract_relays($hashref, $pubkey);
320  
321 Returns an arrayref of relay URLs for the given pubkey, or an empty arrayref
322 if none are found.
323  
324 =head1 CONSTRUCTOR
325  
326 =head2 new
327  
328 Accepts named arguments as either a flat list or a single hash reference.
329  
330 my $ident = Net::Nostr::Identifier->new(%args);
331  
332 Croaks on unknown arguments.
333  
334 =over 4
335  
336 =item base_url
337  
338 Optional base URL override for testing. When set, HTTP requests go to
339 this URL instead of C<https://E<lt>domainE<gt>>. The value is strictly
340 validated as an HTTP or HTTPS base URL and is composed with
341 C</.well-known/nostr.json> using L<URI>. Existing base paths are preserved.
342 Queries, fragments, userinfo, control characters, spaces, missing hosts, and
343 ports outside C<1..65535> are rejected.
344  
345 =back
346  
347 =head1 INSTANCE METHODS
348  
349 =head2 verify
350  
351 $ident->verify(
352 identifier => 'bob@example.com',
353 pubkey => $hex_pubkey,
354 on_success => sub { my ($relays) = @_ },
355 on_failure => sub { my ($reason) = @_ },
356 );
357  
358 Asynchronously fetches the well-known URL and verifies that the identifier
359 maps to the given pubkey. HTTP redirects are ignored per the spec. Requires
360 L<AnyEvent> and L<AnyEvent::HTTP>. Croaks if any required argument is missing,
361 if C<on_success>/C<on_failure> are not CODE refs, or if C<AnyEvent::HTTP> is
362 not installed.
363  
364 The C<on_success> callback receives an arrayref of relay URLs (may be empty).
365 The C<on_failure> callback receives an error reason string.
366  
367 =head2 lookup
368  
369 $ident->lookup(
370 identifier => 'bob@example.com',
371 on_success => sub { my ($pubkey, $relays) = @_ },
372 on_failure => sub { my ($reason) = @_ },
373 );
374  
375 Asynchronously fetches the well-known URL and returns the pubkey associated
376 with the identifier. HTTP redirects are ignored per the spec. Requires
377 L<AnyEvent> and L<AnyEvent::HTTP>. Croaks if any required argument is missing,
378 if C<on_success>/C<on_failure> are not CODE refs, or if C<AnyEvent::HTTP> is
379 not installed.
380  
381 The C<on_success> callback receives the hex pubkey and an arrayref of relay
382 URLs. The C<on_failure> callback receives an error reason string.
383  
384 =head1 SECURITY
385  
386 The C</.well-known/nostr.json> endpoint B<MUST NOT> return any HTTP redirects.
387 This module ignores all HTTP redirects, treating them as verification failures.
388  
389 =head1 SEE ALSO
390  
391 L<NIP-05|https://github.com/nostr-protocol/nips/blob/master/05.md>
392  
393 =cut
« Bech32.pm ↑ Summary _ConstructorArgs.pm »