NAME

Web::VWF::Blacklist - Country-based access control for VWF pages

VERSION

Version 0.003.0

SYNOPSIS

use Web::VWF::Blacklist;

my $bl = Web::VWF::Blacklist->new(countries => $config->{blacklist_countries});
if($bl->is_blocked($lingua->country())) { ... }

METHODS

new

Purpose: build a blacklist.

Args: countries (optional) - an arrayref of two-letter country codes, or a comma/space separated string, as an XML configuration file gives. Defaults to the built-in list.

Returns: a Web::VWF::Blacklist.

Side Effects: none. Each object has its own list, so two objects never affect one another.

Usage:

my $bl = Web::VWF::Blacklist->new(countries => [qw(CN RU)]);

EXAMPLE

my $bl = Web::VWF::Blacklist->new();			# built-in list
my $strict = Web::VWF::Blacklist->new(countries => 'CN, RU');

API SPECIFICATION

INPUT

{
	countries => { type => [ 'arrayref', 'string' ], optional => 1 },
}

OUTPUT

{ type => 'object', isa => 'Web::VWF::Blacklist' }

MESSAGES

+--------------------------------+------------------------------+-----------------------+
| Message                        | Meaning                      | Resolution            |
+--------------------------------+------------------------------+-----------------------+
| Invalid country code 'X' in    | An entry is not two letters  | Fix the configuration |
|   the blacklist                |                              |                       |
+--------------------------------+------------------------------+-----------------------+

FORMAL SPECIFICATION

CC == { c : seq LETTER | #c = 2 }
Blacklist ≙ [ blocked : ℙ CC | ∀ c : blocked • c = upper(c) ]

New
  Blacklist'
  countries? : seq CC
  ─────────
  blocked' = { c : ran countries? • upper(c) }

is_blocked

Purpose: is this country blacklisted?

Args: a two-letter country code, any case. undef or an empty string (GeoIP could not place the client) is never blocked, so a lookup failure does not lock everyone out.

Returns: 1 or 0.

Side Effects: none.

Usage:

print "Go away\n" if $bl->is_blocked('cn');

EXAMPLE

my $bl = Web::VWF::Blacklist->new(countries => ['CN']);
$bl->is_blocked('cn');	# 1
$bl->is_blocked('GB');	# 0
$bl->is_blocked(undef);	# 0

API SPECIFICATION

INPUT

{ country => { type => 'string', optional => 1, position => 0 } }

OUTPUT

{ type => 'boolean' }

MESSAGES

None.

FORMAL SPECIFICATION

IsBlocked
  ΞBlacklist
  c? : CC ∪ {⊥} ; r! : 𝔹
  ─────────
  r! ⇔ (c? ≠ ⊥ ∧ upper(c?) ∈ blocked)

countries

Purpose: the blocked countries, for CGI::ACL's deny_country.

Args: none.

Returns: an arrayref of upper-case codes, sorted.

Side Effects: none.

Usage:

$acl->deny_country(country => $bl->countries());

EXAMPLE

Web::VWF::Blacklist->new(countries => 'ru cn')->countries();	# ['CN', 'RU']

API SPECIFICATION

INPUT

{}

OUTPUT

{ type => 'arrayref', element_type => 'string' }

MESSAGES

None.

FORMAL SPECIFICATION

Countries
  ΞBlacklist
  r! : seq CC
  ─────────
  ran r! = blocked ∧ r! is sorted

LIMITATIONS

Country is only as good as the GeoIP database: VPNs, proxies and stale databases all defeat it. It is a noise filter, not a security boundary.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2010-2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.