| 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 |