blib/lib/Web/VWF/Blacklist.pm untested

filter: Statementstmt 0.0% 0 / 45 Branchbran 0.0% 0 / 6 Conditioncond 0.0% 0 / 7 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 0.0% 0 / 10 Podpod 0.0% 0 / 3 totaltotal 0.0% 0 / 75 CC 4 SCAR 15.9
CC
4
Cov
0%
new
12.0
is_blocked
6.0
countries
2.0
CRAP 4.9
1 package Web::VWF::Blacklist;
2  
3 # Which countries may not use the site.
4 #
5 # This list used to be written out three times, in page.fcgi for CGI::ACL, in
6 # Web::VWF::Allow and in VWF::Display, and the copies had drifted apart (Display
7 # was missing BY, UA and XH). All three now ask this module. Sites can set
8 # their own list with blacklist_countries in the configuration file.
9  
10 use strict;
11 use warnings;
12  
13 use Carp qw(croak);
14 use Params::Get;
15 use Params::Validate::Strict;
16 use Readonly;
17  
18 use version; our $VERSION = version->declare('0.003.0');
19  
20 # Used when the configuration file has no blacklist_countries entry
21 Readonly my @DEFAULT_COUNTRIES => qw(
22 BY MD RU CN BR UY TR MA VE SA CY CO MX IN RS PK UA XH
23 );
24  
25 # ISO 3166-1 alpha-2 (plus the user-assigned XA-XZ range), any case
26 Readonly my $COUNTRY_CODE => qr/\A[A-Za-z]{2}\z/;
27  
28 =encoding utf8
29  
30 =head1 NAME
31  
32 Web::VWF::Blacklist - Country-based access control for VWF pages
33  
34 =head1 VERSION
35  
36 Version 0.003.0
37  
38 =head1 SYNOPSIS
39  
40 use Web::VWF::Blacklist;
41  
42 my $bl = Web::VWF::Blacklist->new(countries => $config->{blacklist_countries});
43 if($bl->is_blocked($lingua->country())) { ... }
44  
45 =head1 METHODS
46  
47 =head2 new
48  
49 Purpose: build a blacklist.
50  
51 Args: C<countries> (optional) - an arrayref of two-letter country codes, or a
52 comma/space separated string, as an XML configuration file gives. Defaults to the
53 built-in list.
54  
55 Returns: a C<Web::VWF::Blacklist>.
56  
57 Side Effects: none. Each object has its own list, so two objects never
58 affect one another.
59  
60 Usage:
61  
62 my $bl = Web::VWF::Blacklist->new(countries => [qw(CN RU)]);
63  
64 =head3 EXAMPLE
65  
66 my $bl = Web::VWF::Blacklist->new(); # built-in list
67 my $strict = Web::VWF::Blacklist->new(countries => 'CN, RU');
68  
69 =head3 API SPECIFICATION
70  
71 =head4 INPUT
72  
73 {
74 countries => { type => [ 'arrayref', 'string' ], optional => 1 },
75 }
76  
77 =head4 OUTPUT
78  
79 { type => 'object', isa => 'Web::VWF::Blacklist' }
80  
81 =head3 MESSAGES
82  
83 +--------------------------------+------------------------------+-----------------------+
84 | Message | Meaning | Resolution |
85 +--------------------------------+------------------------------+-----------------------+
86 | Invalid country code 'X' in | An entry is not two letters | Fix the configuration |
87 | the blacklist | | |
88 +--------------------------------+------------------------------+-----------------------+
89  
90 =head3 FORMAL SPECIFICATION
91  
92 CC == { c : seq LETTER | #c = 2 }
93 Blacklist ≙ [ blocked : ℙ CC | ∀ c : blocked • c = upper(c) ]
94  
95 New
96 Blacklist'
97 countries? : seq CC
98 ─────────
99 blocked' = { c : ran countries? • upper(c) }
100  
101 =cut
102  
103 sub new
104 {
105 my $class = shift;
106  
107 my $args = Params::Validate::Strict::validate_strict({
108 schema => { countries => { type => ['arrayref', 'string'], optional => 1 } },
109 input => Params::Get::get_params(undef, \@_) || {},
110 });
111  
112 # Depending on the file format, the configuration file gives either a
113 # list or a string such as "CN, RU", so accept both
114 my $countries = $args->{countries} // [@DEFAULT_COUNTRIES];
115 $countries = [split /[\s,]+/, $countries] unless(ref($countries));
116  
117 my %blocked;
118 foreach my $code(grep { length } @{$countries}) {
119 croak("Invalid country code '$code' in the blacklist") if($code !~ $COUNTRY_CODE);
120 $blocked{uc $code} = 1;
121 }
122  
123 return bless { blocked => \%blocked }, $class;
124 }
125  
126 =head2 is_blocked
127  
128 Purpose: is this country blacklisted?
129  
130 Args: a two-letter country code, any case. C<undef> or an empty string
131 (GeoIP could not place the client) is never blocked, so a lookup failure
132 does not lock everyone out.
133  
134 Returns: 1 or 0.
135  
136 Side Effects: none.
137  
138 Usage:
139  
140 print "Go away\n" if $bl->is_blocked('cn');
141  
142 =head3 EXAMPLE
143  
144 my $bl = Web::VWF::Blacklist->new(countries => ['CN']);
145 $bl->is_blocked('cn'); # 1
146 $bl->is_blocked('GB'); # 0
147 $bl->is_blocked(undef); # 0
148  
149 =head3 API SPECIFICATION
150  
151 =head4 INPUT
152  
153 { country => { type => 'string', optional => 1, position => 0 } }
154  
155 =head4 OUTPUT
156  
157 { type => 'boolean' }
158  
159 =head3 MESSAGES
160  
161 None.
162  
163 =head3 FORMAL SPECIFICATION
164  
165 IsBlocked
166 ΞBlacklist
167 c? : CC ∪ {⊥} ; r! : 𝔹
168 ─────────
169 r! ⇔ (c? ≠ ⊥ ∧ upper(c?) ∈ blocked)
170  
171 =cut
172  
173 sub is_blocked
174 {
175 my ($self, $country) = @_;
176  
177 return (defined($country) && $self->{blocked}{uc $country}) ? 1 : 0;
178 }
179  
180 =head2 countries
181  
182 Purpose: the blocked countries, for CGI::ACL's C<deny_country>.
183  
184 Args: none.
185  
186 Returns: an arrayref of upper-case codes, sorted.
187  
188 Side Effects: none.
189  
190 Usage:
191  
192 $acl->deny_country(country => $bl->countries());
193  
194 =head3 EXAMPLE
195  
196 Web::VWF::Blacklist->new(countries => 'ru cn')->countries(); # ['CN', 'RU']
197  
198 =head3 API SPECIFICATION
199  
200 =head4 INPUT
201  
202 {}
203  
204 =head4 OUTPUT
205  
206 { type => 'arrayref', element_type => 'string' }
207  
208 =head3 MESSAGES
209  
210 None.
211  
212 =head3 FORMAL SPECIFICATION
213  
214 Countries
215 ΞBlacklist
216 r! : seq CC
217 ─────────
218 ran r! = blocked ∧ r! is sorted
219  
220 =cut
221  
222 sub countries
223 {
224 my $self = shift;
225  
226 return [sort keys %{$self->{blocked}}];
227 }
228  
229 =head1 LIMITATIONS
230  
231 Country is only as good as the GeoIP database: VPNs, proxies and stale
232 databases all defeat it. It is a noise filter, not a security boundary.
233  
234 =cut
235  
236 1;
237  
238 =head1 AUTHOR
239  
240 Nigel Horne, C<< <njh at nigelhorne.com> >>
241  
242 =head1 LICENCE AND COPYRIGHT
243  
244 Copyright 2010-2026 Nigel Horne.
245  
246 Usage is subject to the GPL2 licence terms.
247 If you use it,
248 please let me know.
249  
250 =cut