| 1 | package Web::VWF::Display; | ||
| 2 | |||
| 3 | # Display a page. Certain variables are available to all templates, such as | ||
| 4 | # the stuff in the configuration file | ||
| 5 | |||
| 6 | =encoding utf8 | ||
| 7 | |||
| 8 | =head1 NAME | ||
| 9 | |||
| 10 | Web::VWF::Display - The base class of the pages | ||
| 11 | |||
| 12 | =head1 VERSION | ||
| 13 | |||
| 14 | Version 0.003.0 | ||
| 15 | |||
| 16 | =head1 DESCRIPTION | ||
| 17 | |||
| 18 | Every page, such as C<Web::VWF::Display::index>, inherits from this. Its | ||
| 19 | constructor checks the request, as C<Referer>, L<CGI::IDS>, the throttle and the | ||
| 20 | country blacklist, and returns undef to refuse or croaks on an attack; | ||
| 21 | C<as_string> gives the headers and then the page, which a subclass makes by | ||
| 22 | calling C<html>. The template is chosen from the class name, the kind of client | ||
| 23 | and the language: see L<Web::VWF/DESCRIPTION>. The settings are in | ||
| 24 | L<Web::VWF/CONFIGURATION>. | ||
| 25 | |||
| 26 | =cut | ||
| 27 | |||
| 28 | # ----------------------------------------------------------------------- | ||
| 29 | |||
| 30 | =head1 CONFIGURATION | ||
| 31 | |||
| 32 | =head2 CSRF Protection | ||
| 33 | |||
| 34 | VWF automatically issues a CSRF token as a cookie on every page with a form so | ||
| 35 | that forms can protect against cross-site request forgery. The token is | ||
| 36 | signed with an HMAC secret. B<You must supply that secret in your site's | ||
| 37 | XML configuration file.> | ||
| 38 | |||
| 39 | =head3 Recommended setup - configure a persistent secret | ||
| 40 | |||
| 41 | Add the following block to your domain's XML config (e.g. | ||
| 42 | C<conf/example.com/config.xml>): | ||
| 43 | |||
| 44 | <security> | ||
| 45 | <csrf> | ||
| 46 | <secret>your-long-random-string-here</secret> | ||
| 47 | </csrf> | ||
| 48 | </security> | ||
| 49 | |||
| 50 | The secret can be any string, but should be long and unpredictable. | ||
| 51 | Generate a good one with: | ||
| 52 | |||
| 53 | perl -MCrypt::URandom=urandom -e 'print unpack("H*", urandom(32)), "\n"' | ||
| 54 | |||
| 55 | or | ||
| 56 | |||
| 57 | openssl rand -hex 32 | ||
| 58 | |||
| 59 | Tokens signed with this secret survive across FastCGI process restarts, | ||
| 60 | so users will not lose form state when the server is reloaded. | ||
| 61 | |||
| 62 | =head3 What happens if you do not configure a secret | ||
| 63 | |||
| 64 | If C<security.csrf.secret> is absent, VWF B<does not refuse to start>. | ||
| 65 | Instead it: | ||
| 66 | |||
| 67 | =over 4 | ||
| 68 | |||
| 69 | =item 1. | ||
| 70 | |||
| 71 | Generates a cryptographically random 256-bit secret the first time a | ||
| 72 | CSRF token is needed in the current process. | ||
| 73 | |||
| 74 | =item 2. | ||
| 75 | |||
| 76 | Emits a one-time warning to the error log: | ||
| 77 | |||
| 78 | VWF: security.csrf.secret is not configured; using a per-process | ||
| 79 | random secret. CSRF tokens will not survive process restarts. | ||
| 80 | Set security.csrf.secret in your site config to suppress this warning. | ||
| 81 | |||
| 82 | =item 3. | ||
| 83 | |||
| 84 | Uses that random secret for every token issued in this process lifetime. | ||
| 85 | |||
| 86 | =back | ||
| 87 | |||
| 88 | This means CSRF protection is still B<cryptographically strong> - there is | ||
| 89 | no hardcoded or guessable key - but if the FastCGI process restarts (e.g. | ||
| 90 | on deploy or crash) any tokens issued before the restart become invalid. | ||
| 91 | Users who had a form open will see a CSRF validation failure on submit and | ||
| 92 | will need to reload the page. | ||
| 93 | |||
| 94 | To silence the warning and avoid that edge case, set the secret in config | ||
| 95 | as shown above. | ||
| 96 | |||
| 97 | =head3 Disabling CSRF entirely | ||
| 98 | |||
| 99 | Set C<security.csrf.enable> to C<0> in your config if you do not use | ||
| 100 | server-side form handling and do not need CSRF tokens at all: | ||
| 101 | |||
| 102 | <security> | ||
| 103 | <csrf> | ||
| 104 | <enable>0</enable> | ||
| 105 | </csrf> | ||
| 106 | </security> | ||
| 107 | |||
| 108 | =cut | ||
| 109 | |||
| 110 | # ----------------------------------------------------------------------- | ||
| 111 | |||
| 112 | use version; our $VERSION = version->declare('0.003.0'); | ||
| 113 | |||
| 114 | use v5.20; | ||
| 115 | use strict; | ||
| 116 | use warnings; | ||
| 117 | use feature qw(signatures); | ||
| 118 | no warnings qw(experimental::signatures); | ||
| 119 | |||
| 120 | use Config::Abstraction; | ||
| 121 | use CGI::Info 1.14; # For is_ai() | ||
| 122 | use Data::Dumper; | ||
| 123 | use Digest::MD5 qw(md5_hex); | ||
| 124 | use Crypt::URandom qw(urandom); # CSPRNG for CSRF tokens; rand() is not safe | ||
| 125 | use Carp qw(croak carp); # croak for fatal errors, carp for warnings | ||
| 126 | |||
| 127 | # Per-process fallback CSRF secret, generated once if no secret is configured. | ||
| 128 | # Tokens are valid within a process lifetime but not across restarts. | ||
| 129 | my $_csrf_fallback_secret; | ||
| 130 | use Digest::SHA qw(sha256_hex); | ||
| 131 | use File::Spec; | ||
| 132 | use Object::Configure; | ||
| 133 | use Params::Get; | ||
| 134 | use Template::Filters; | ||
| 135 | use Template::Plugin::EnvHash; | ||
| 136 | use Template::Plugin::Math; | ||
| 137 | use Template::Plugin::JSON; | ||
| 138 | use HTML::SocialMedia; | ||
| 139 | use Web::VWF::Blacklist; | ||
| 140 | use Web::VWF::Utils qw(create_memory_cache); | ||
| 141 | use Error; | ||
| 142 | use File::pfopen; | ||
| 143 | use Params::Get; | ||
| 144 | use Scalar::Util; | ||
| 145 | |||
| 146 | our $sm; | ||
| 147 | |||
| 148 | # Main display handler for generating web pages using Template Toolkit | ||
| 149 | # Handles security, throttling, localization, and template selection | ||
| 150 | # Constructor. Accepts either a flat list of key => value pairs or a hashref. | ||
| 151 | # Returns a blessed display object, or undef if the request should be blocked | ||
| 152 | # (e.g. invalid Referer header). | ||
| 153 | sub new | ||
| 154 | { | ||
| 155 | my $class = shift; | ||
| 156 | |||
| 157 | # Normalise both calling styles (hash list and hashref) into a single hashref. | ||
| 158 | my $params = Params::Get::get_params(undef, @_); | ||
| 159 | |||
| 160 | if(!defined($class)) { | ||
| 161 | # Called as VWF::Display::new() rather than VWF::Display->new(). | ||
| 162 | # FIXME: this only works when no arguments are given | ||
| 163 | $class = __PACKAGE__; | ||
| 164 | } elsif(Scalar::Util::blessed($class)) { | ||
| 165 | # $class is already an object - return a shallow clone with the new | ||
| 166 | # params merged in (used to re-bless into a subclass). | ||
| 167 | return bless { %{$class}, %{$params} }, ref($class); | ||
| 168 | } | ||
| 169 | |||
| 170 | # SECURITY - Shellshock / invalid-referer defence: | ||
| 171 | # The HTTP_REFERER header is attacker-controlled. Validate it as a URI | ||
| 172 | # before letting it propagate further into the request; returning undef | ||
| 173 | # causes the caller to treat this as a blocked request. | ||
| 174 | if(defined($ENV{'HTTP_REFERER'})) { | ||
| 175 | unless(Data::Validate::URI->can('new')) { | ||
| 176 | require Data::Validate::URI; | ||
| 177 | Data::Validate::URI->import(); | ||
| 178 | } | ||
| 179 | |||
| 180 | unless(Data::Validate::URI->new()->is_uri($ENV{'HTTP_REFERER'})) { | ||
| 181 | return; # reject requests with a syntactically invalid Referer | ||
| 182 | } | ||
| 183 | } | ||
| 184 | |||
| 185 | # Allow subclasses declared via Object::Configure to inject extra params. | ||
| 186 | $params = Object::Configure::configure($class, $params); | ||
| 187 | |||
| 188 | my $info = $params->{info} || CGI::Info->new(); | ||
| 189 | |||
| 190 | # Resolve the configuration directory hierarchy for this domain. | ||
| 191 | my $config_dir = _find_config_dir($params, $info); | ||
| 192 | if($params->{'logger'}) { | ||
| 193 | $params->{'logger'}->debug(__PACKAGE__, ' (', __LINE__, "): path = $config_dir"); | ||
| 194 | } | ||
| 195 | |||
| 196 | # Load 'default' first so that domain-specific values override the defaults. | ||
| 197 | my $config; | ||
| 198 | eval { | ||
| 199 | if($config = Config::Abstraction->new(config_dirs => [$config_dir], config_files => ['default', $info->domain_name()], logger => $params->{'logger'})) { | ||
| 200 | $config = $config->all(); | ||
| 201 | } | ||
| 202 | }; | ||
| 203 | if($@ || !defined($config)) { | ||
| 204 | croak("Configuration error: $@: $config_dir/", $info->domain_name()); | ||
| 205 | } | ||
| 206 | |||
| 207 | # Merge caller-supplied config on top of the file-based defaults so that | ||
| 208 | # page-specific overrides take precedence. | ||
| 209 | if(defined($params->{'config'})) { | ||
| 210 | $config = { %{$config}, %{$params->{'config'}} }; | ||
| 211 | } | ||
| 212 | |||
| 213 | unless($info->is_search_engine() || !defined($ENV{'REMOTE_ADDR'})) { | ||
| 214 | if(my $params = $info->params()) { | ||
| 215 | # Intrusion Detection System integration | ||
| 216 | require CGI::IDS; | ||
| 217 | CGI::IDS->import(); | ||
| 218 | |||
| 219 | my $ids = CGI::IDS->new(); | ||
| 220 | $ids->set_scan_keys(scan_keys => 1); | ||
| 221 | |||
| 222 | my $impact = $ids->detect_attacks(request => $params); | ||
| 223 | my $threshold = $config->{security}->{ids_threshold} // 50; | ||
| 224 | if($impact > $threshold) { | ||
| 225 | croak($ENV{'REMOTE_ADDR'}, ": IDS impact is $impact"); # Block detected attacks | ||
| 226 | } | ||
| 227 | } | ||
| 228 | |||
| 229 | if($ENV{'REMOTE_ADDR'}) { | ||
| 230 | # Connection throttling system | ||
| 231 | require Data::Throttler; | ||
| 232 | |||
| 233 | my $db_file = $config->{'throttle'}->{'file'} // File::Spec->catdir($info->tmpdir(), 'throttle'); | ||
| 234 | |||
| 235 | # The eval only finds out whether the client is over the limit, | ||
| 236 | # so that it catches errors from a broken YAML file and nothing | ||
| 237 | # else. A "return" in here would leave only the eval, not new(). | ||
| 238 | my $throttled = eval { | ||
| 239 | my %options = ( | ||
| 240 | max_items => $config->{'throttle'}->{'max_items'} // 30, # Allow 30 requests | ||
| 241 | interval => $config->{'throttle'}->{'interval'} // 90, # Per 90 second window | ||
| 242 | backend => 'YAML', | ||
| 243 | backend_options => { | ||
| 244 | db_file => $db_file | ||
| 245 | } | ||
| 246 | ); | ||
| 247 | |||
| 248 | my $throttler = Data::Throttler->new(%options); | ||
| 249 | $throttler && !$throttler->try_push(key => $ENV{'REMOTE_ADDR'}); | ||
| 250 | }; | ||
| 251 | if($@) { | ||
| 252 | if($params->{'logger'}) { | ||
| 253 | $params->{'logger'}->notice("Removing unparsable YAML file $db_file: $@"); | ||
| 254 | } | ||
| 255 | unlink($db_file); | ||
| 256 | } elsif($throttled) { | ||
| 257 | $info->status(429); # Too many requests | ||
| 258 | sleep(1); # Slow down attackers | ||
| 259 | if($params->{'logger'}) { | ||
| 260 | $params->{'logger'}->info("$ENV{REMOTE_ADDR} connexion throttled"); | ||
| 261 | } | ||
| 262 | return; | ||
| 263 | } | ||
| 264 | |||
| 265 | # Country based blocking | ||
| 266 | if(my $lingua = $params->{lingua}) { | ||
| 267 | my $country = $lingua->country(); | ||
| 268 | if(Web::VWF::Blacklist->new(countries => $config->{'blacklist_countries'})->is_blocked($country)) { | ||
| 269 | if($params->{'logger'}) { | ||
| 270 | $params->{'logger'}->warn("$ENV{REMOTE_ADDR} is from a blacklisted country $country"); | ||
| 271 | } | ||
| 272 | croak("$ENV{REMOTE_ADDR} is from a blacklisted country $country"); | ||
| 273 | } | ||
| 274 | } | ||
| 275 | } | ||
| 276 | } | ||
| 277 | |||
| 278 | # Initialise the template system | ||
| 279 | Template::Filters->use_html_entities(); | ||
| 280 | |||
| 281 | # _ names included for legacy reasons, they will go away | ||
| 282 | my $self = { | ||
| 283 | _cachedir => $params->{cachedir}, | ||
| 284 | info => $info, | ||
| 285 | _info => $info, | ||
| 286 | _logger => $params->{logger}, | ||
| 287 | config_dir => $config_dir, | ||
| 288 | %{$params}, | ||
| 289 | config => $config, | ||
| 290 | _config => $config, | ||
| 291 | }; | ||
| 292 | |||
| 293 | if(my $lingua = $params->{'lingua'}) { | ||
| 294 | $self->{'lingua'} = $lingua; | ||
| 295 | $self->{'_lingua'} = $lingua; | ||
| 296 | } | ||
| 297 | if(my $key = $info->param('key')) { | ||
| 298 | $self->{'key'} = $key; | ||
| 299 | $self->{'_key'} = $key; | ||
| 300 | } | ||
| 301 | if(my $page = $info->param('page')) { | ||
| 302 | $self->{'page'} = $page; | ||
| 303 | $self->{'_page'} = $page; | ||
| 304 | } | ||
| 305 | |||
| 306 | # Social media integration | ||
| 307 | if(my $twitter = $config->{'twitter'}) { | ||
| 308 | my $smcache = create_memory_cache(config => $config, logger => $params->{'logger'}, namespace => 'HTML::SocialMedia'); | ||
| 309 | $sm ||= HTML::SocialMedia->new({ twitter => $twitter, cache => $smcache, lingua => $params->{lingua}, logger => $params->{logger} }); | ||
| 310 | $self->{'_social_media'}->{'twitter_tweet_button'} = $sm->as_string(twitter_tweet_button => 1); | ||
| 311 | } elsif(!defined($sm)) { | ||
| 312 | my $smcache = create_memory_cache(config => $config, logger => $params->{'logger'}, namespace => 'HTML::SocialMedia'); | ||
| 313 | $sm = HTML::SocialMedia->new({ cache => $smcache, lingua => $params->{lingua}, logger => $params->{logger} }); | ||
| 314 | } | ||
| 315 | $self->{'_social_media'}->{'facebook_share_button'} = $sm->as_string(facebook_share_button => 1); | ||
| 316 | # $self->{'_social_media'}->{'google_plusone'} = $sm->as_string(google_plusone => 1); | ||
| 317 | |||
| 318 | # Return the blessed object | ||
| 319 | return bless $self, $class; | ||
| 320 | } | ||
| 321 | |||
| 322 | # Internal method to determine the configuration directory | ||
| 323 | sub _find_config_dir | ||
| 324 | { | ||
| 325 | my($args, $info) = @_; | ||
| 326 | |||
| 327 | if($ENV{'CONFIG_DIR'}) { | ||
| 328 | return $ENV{'CONFIG_DIR'}; | ||
| 329 | } | ||
| 330 | |||
| 331 | # Look first in $root_dir/conf | ||
| 332 | |||
| 333 | my $config_dir = $ENV{'root_dir'}; | ||
| 334 | if(defined($config_dir) && (-d $config_dir)) { | ||
| 335 | $config_dir = File::Spec->catdir($config_dir, 'conf'); | ||
| 336 | |||
| 337 | if(-d $config_dir) { | ||
| 338 | return $config_dir; | ||
| 339 | } | ||
| 340 | } | ||
| 341 | |||
| 342 | $config_dir = File::Spec->catdir( | ||
| 343 | $info->script_dir(), | ||
| 344 | File::Spec->updir(), | ||
| 345 | File::Spec->updir(), | ||
| 346 | 'conf' | ||
| 347 | ); | ||
| 348 | |||
| 349 | if(!-d $config_dir) { | ||
| 350 | $config_dir = File::Spec->catdir( | ||
| 351 | $info->script_dir(), | ||
| 352 | File::Spec->updir(), | ||
| 353 | 'conf' | ||
| 354 | ); | ||
| 355 | } | ||
| 356 | |||
| 357 | if(!-d $config_dir) { | ||
| 358 | if($ENV{'DOCUMENT_ROOT'}) { | ||
| 359 | $config_dir = File::Spec->catdir( | ||
| 360 | # $ENV{'DOCUMENT_ROOT'}, | ||
| 361 | $info->rootdir(), | ||
| 362 | File::Spec->updir(), | ||
| 363 | 'lib', | ||
| 364 | 'conf' | ||
| 365 | ); | ||
| 366 | } else { | ||
| 367 | $config_dir = File::Spec->catdir( | ||
| 368 | $ENV{'HOME'}, | ||
| 369 | 'lib', | ||
| 370 | 'conf' | ||
| 371 | ); | ||
| 372 | } | ||
| 373 | } | ||
| 374 | |||
| 375 | if(!-d $config_dir) { | ||
| 376 | if($args->{config_directory}) { | ||
| 377 | return $args->{config_directory}; | ||
| 378 | } | ||
| 379 | if($args->{logger}) { | ||
| 380 | while(my ($k, $v) = each %ENV) { | ||
| 381 | $args->{logger}->debug("$k=$v"); | ||
| 382 | } | ||
| 383 | } | ||
| 384 | } | ||
| 385 | |||
| 386 | return $config_dir; | ||
| 387 | } | ||
| 388 | |||
| 389 | # Call this to display the page | ||
| 390 | # It calls http() to create the HTTP headers, then html() to create the body | ||
| 391 | sub as_string { | ||
| 392 | my ($self, $args) = @_; | ||
| 393 | |||
| 394 | # TODO: Get all cookies and send them to the template. | ||
| 395 | # 'cart' is an example | ||
| 396 | unless($args && $args->{cart}) { | ||
| 397 | if(my $purchases = $self->{_info}->get_cookie(cookie_name => 'cart')) { | ||
| 398 | # SECURITY - malformed cookie defence: | ||
| 399 | # The cart cookie is colon-delimited key:qty pairs (e.g. "sku1:2:sku2:1"). | ||
| 400 | # An attacker-controlled cookie with an odd number of colons would cause | ||
| 401 | # "Odd number of elements in hash assignment" and corrupt the cart hash. | ||
| 402 | # Only convert the list to a hash when the element count is even. | ||
| 403 | my @parts = split(/:/, $purchases); | ||
| 404 | if(@parts % 2 == 0) { | ||
| 405 | my %cart = @parts; | ||
| 406 | # Strip any key or value containing non-alphanumeric characters to | ||
| 407 | # prevent template injection through attacker-controlled cookie data. | ||
| 408 | $args->{cart} = { | ||
| 409 | map { | ||
| 410 | (/\A[A-Za-z0-9_]+\z/ && defined($cart{$_}) && ($cart{$_} =~ /\A[A-Za-z0-9_]+\z/)) | ||
| 411 | ? ($_ => $cart{$_}) : () | ||
| 412 | } keys %cart | ||
| 413 | }; | ||
| 414 | } | ||
| 415 | } | ||
| 416 | } | ||
| 417 | |||
| 418 | # Calculate items in cart if not already present in $args | ||
| 419 | unless($args && $args->{itemsincart}) { | ||
| 420 | if($args->{cart}) { | ||
| 421 | my $itemsincart; | ||
| 422 | foreach my $key(keys %{$args->{cart}}) { | ||
| 423 | if(defined($args->{cart}{$key}) && ($args->{cart}{$key} ne '')) { | ||
| 424 | $itemsincart += $args->{cart}{$key}; | ||
| 425 | } else { | ||
| 426 | delete $args->{cart}{$key}; | ||
| 427 | } | ||
| 428 | } | ||
| 429 | $args->{itemsincart} = $itemsincart; | ||
| 430 | } | ||
| 431 | } | ||
| 432 | |||
| 433 | my($cache, $key); | ||
| 434 | |||
| 435 | if(!$args->{itemsincart}) { | ||
| 436 | $cache = create_memory_cache(config => $self->{config}, logger => $self->{'logger'}, namespace => ref($self)); | ||
| 437 | $key = cache_key_from_hashref($args); | ||
| 438 | if(my $rc = $cache->get($key)) { | ||
| 439 | $self->_send_csrf_token($rc); | ||
| 440 | return $rc; | ||
| 441 | } | ||
| 442 | } | ||
| 443 | |||
| 444 | # my $html = $self->html($args); | ||
| 445 | # unless($html) { | ||
| 446 | # return; | ||
| 447 | # } | ||
| 448 | # return $self->http() . $html; | ||
| 449 | |||
| 450 | # Build the HTTP response | ||
| 451 | my $rc = $self->http($args); | ||
| 452 | if($rc =~ /^Location:\s/ms) { | ||
| 453 | return $rc; | ||
| 454 | } | ||
| 455 | $rc .= $self->html($args); | ||
| 456 | $self->_send_csrf_token($rc); | ||
| 457 | if($cache) { | ||
| 458 | $self->{cache_duration} ||= '5 minutes'; | ||
| 459 | $cache->set($key, $rc, $self->{cache_duration}); | ||
| 460 | } | ||
| 461 | return $rc; | ||
| 462 | } | ||
| 463 | |||
| 464 | # Determine the path to the correct template file based on various criteria such as language settings, browser type, and module path | ||
| 465 | sub get_template_path | ||
| 466 | { | ||
| 467 | my $self = shift; | ||
| 468 | my %args = (ref($_[0]) eq 'HASH') ? %{$_[0]} : @_; | ||
| 469 | |||
| 470 | if($self->{_logger}) { | ||
| 471 | $self->{_logger}->trace('Entering get_template_path'); | ||
| 472 | } | ||
| 473 | |||
| 474 | if($self->{_filename}) { | ||
| 475 | if($self->{_logger}) { | ||
| 476 | $self->{_logger}->trace({ message => 'returning ' . $self->{_filename} }); | ||
| 477 | } | ||
| 478 | return $self->{_filename}; | ||
| 479 | } | ||
| 480 | |||
| 481 | # FIXME: reread the config file since something is cloberring it | ||
| 482 | if(my $config = Config::Abstraction->new(config_dirs => [$self->{config_dir}], config_files => ['default', $self->{info}->domain_name()], logger => $self->{logger})) { | ||
| 483 | $config = $config->all(); | ||
| 484 | $self->{config} = $self->{_config} = $config; | ||
| 485 | } | ||
| 486 | my $dir = $ENV{'root_dir'} || $self->{_config}->{root_dir} || $self->{_info}->root_dir(); | ||
| 487 | if($self->{_logger}) { | ||
| 488 | $self->{_logger}->debug(__PACKAGE__, ': ', __LINE__, ": root_dir $dir"); | ||
| 489 | $self->{_logger}->debug(Data::Dumper->new([Web::VWF::Utils::redact_config($self->{_config})])->Dump()); | ||
| 490 | } | ||
| 491 | $dir .= '/templates'; | ||
| 492 | |||
| 493 | my $prefix; | ||
| 494 | |||
| 495 | # Look in .../robot or .../mobile first, if appropriate | ||
| 496 | # Look in .../en/gb/web, then .../en/web then /web | ||
| 497 | foreach my $browser_type($self->_types()) { | ||
| 498 | if(my $lingua = $self->{_lingua}) { | ||
| 499 | $self->_debug({ message => 'Requested language: ' . $lingua->requested_language() }); | ||
| 500 | # FIXME: look for lower priority languages if the highest isn't found | ||
| 501 | if(my $language = $lingua->language_code_alpha2()) { | ||
| 502 | if(my $dialect = $lingua->sublanguage_code_alpha2()) { | ||
| 503 | $prefix .= "$dir/$browser_type/$language/$dialect:"; | ||
| 504 | $prefix .= "$dir/$browser_type/$language/default:"; | ||
| 505 | } | ||
| 506 | $prefix .= "$dir/$language/$browser_type:" if(-d "$dir/$language/$browser_type"); | ||
| 507 | $prefix .= "$dir/$browser_type/$language:" if(-d "$dir/$browser_type/$language"); | ||
| 508 | } | ||
| 509 | } | ||
| 510 | $prefix .= "$dir/$browser_type/default:" if(-d "$dir/$browser_type/default"); | ||
| 511 | $prefix .= "$dir/default/$browser_type/:" if(-d "$dir/default/$browser_type"); | ||
| 512 | $prefix .= "$dir/$browser_type:" if(-d "$dir/$browser_type"); | ||
| 513 | } | ||
| 514 | |||
| 515 | # Fall back to .../web, or if that fails, assume no web, robot or | ||
| 516 | # mobile variant | ||
| 517 | $prefix .= "$dir/web:$dir/default/web:$dir/default:$dir"; | ||
| 518 | |||
| 519 | $self->_debug({ message => "prefix: $prefix" }); | ||
| 520 | |||
| 521 | my $modulepath = $args{'modulepath'} || ref($self); | ||
| 522 | $modulepath =~ s/::/\//g; | ||
| 523 | |||
| 524 | if($prefix =~ /\.\.\//) { | ||
| 525 | throw Error::Simple("Prefix must not contain ../ ($prefix)"); | ||
| 526 | } | ||
| 527 | |||
| 528 | # Untaint the prefix value which may have been read in from a configuration file | ||
| 529 | ($prefix) = ($prefix =~ m/^([A-Z0-9_\.\-\/:]+)$/ig); | ||
| 530 | |||
| 531 | my ($fh, $filename) = File::pfopen::pfopen($prefix, $modulepath, 'tmpl:tt:html:htm:txt'); | ||
| 532 | if((!defined($filename)) || (!defined($fh))) { | ||
| 533 | throw Error::Simple("Can't find suitable $modulepath html or tmpl/tt file in $prefix in $dir or a subdir (check " . join(':', @{$self->{'config'}->{'config_path'} // []}) . ')'); | ||
| 534 | } | ||
| 535 | close($fh); | ||
| 536 | $self->_debug({ message => "Using $filename" }); | ||
| 537 | $self->{_filename} = $filename; | ||
| 538 | |||
| 539 | # Remember the template filename | ||
| 540 | if($self->{'log'}) { | ||
| 541 | $self->{'log'}->template($filename); | ||
| 542 | } | ||
| 543 | |||
| 544 | return $filename; | ||
| 545 | } | ||
| 546 | |||
| 547 | =head2 set_cookie | ||
| 548 | |||
| 549 | Safely set cookie values with validation. | ||
| 550 | |||
| 551 | Takes either a hash reference or a list of key-value pairs as input. | ||
| 552 | Iterates over the parameters and stores them in the object's _cookies hash. | ||
| 553 | Returns the object itself, allowing for method chaining. | ||
| 554 | |||
| 555 | =cut | ||
| 556 | |||
| 557 | sub set_cookie | ||
| 558 | { | ||
| 559 | my $self = shift; | ||
| 560 | my %params = (ref($_[0]) eq 'HASH') ? %{$_[0]} : @_; | ||
| 561 | |||
| 562 | # Validate cookie parameters | ||
| 563 | for my $key (keys %params) { | ||
| 564 | # Sanitize cookie names and values | ||
| 565 | next unless $key =~ /^[a-zA-Z0-9_-]+$/; | ||
| 566 | |||
| 567 | my $value = $params{$key}; | ||
| 568 | next unless defined $value; | ||
| 569 | |||
| 570 | # Basic value sanitization | ||
| 571 | $value =~ s/[;\r\n]//g; | ||
| 572 | $self->{_cookies}->{$key} = $value; | ||
| 573 | } | ||
| 574 | |||
| 575 | return $self; | ||
| 576 | } | ||
| 577 | |||
| 578 | =head2 add_preload | ||
| 579 | |||
| 580 | $self->add_preload($href, $as, %opts); | ||
| 581 | |||
| 582 | Queue a resource to be advertised to the browser (and to the HTTP/2 server) | ||
| 583 | as a preload hint, emitted as a C<Link: rel=preload> HTTP header. | ||
| 584 | |||
| 585 | In HTTP/2, the web server can read these headers and I<push> the named assets | ||
| 586 | to the client before the browser has finished parsing the HTML and discovered | ||
| 587 | them itself. This eliminates a full round-trip for render-critical resources | ||
| 588 | such as stylesheets and fonts, measurably reducing time-to-first-paint. | ||
| 589 | |||
| 590 | In HTTP/1.1 the header still provides a useful hint: browsers begin fetching | ||
| 591 | the asset as soon as they see the response headers, in parallel with HTML | ||
| 592 | parsing, which is faster than waiting for the parser to encounter the | ||
| 593 | C<< <link> >> or C<< <script> >> tag. | ||
| 594 | |||
| 595 | =head3 Parameters | ||
| 596 | |||
| 597 | =over 4 | ||
| 598 | |||
| 599 | =item $href (required) | ||
| 600 | |||
| 601 | Root-relative path to the resource, e.g. C</css/main.css>. Must start with | ||
| 602 | a C</>. Absolute URLs and relative paths are rejected to prevent header | ||
| 603 | injection. | ||
| 604 | |||
| 605 | =item $as (required) | ||
| 606 | |||
| 607 | The W3C resource type. Must be one of: | ||
| 608 | |||
| 609 | audio document embed fetch font image object | ||
| 610 | script style track video worker | ||
| 611 | |||
| 612 | Choosing the correct type matters: it determines the request's priority, | ||
| 613 | the C<Accept> header the browser sends, and whether the resource is subject | ||
| 614 | to Content Security Policy checks. An incorrect type causes the browser to | ||
| 615 | ignore the hint silently. | ||
| 616 | |||
| 617 | =item crossorigin => 1 (optional) | ||
| 618 | |||
| 619 | Include the C<crossorigin> attribute on the Link header. This is required | ||
| 620 | for any resource that will be fetched in CORS anonymous mode - most notably | ||
| 621 | web fonts, even when they are served from the same origin. Without it the | ||
| 622 | browser issues a second, uncached fetch when it encounters the C<< <link> >> | ||
| 623 | tag in the HTML. | ||
| 624 | |||
| 625 | Defaults to C<1> automatically when C<$as> is C<font>; for all other types | ||
| 626 | defaults to C<0>. | ||
| 627 | |||
| 628 | =back | ||
| 629 | |||
| 630 | Returns C<$self> so calls may be chained. | ||
| 631 | |||
| 632 | =head3 When to call it | ||
| 633 | |||
| 634 | Call C<add_preload> from a page subclass constructor, I<after> | ||
| 635 | C<< $class->SUPER::new(@args) >> returns and I<before> C<as_string> is | ||
| 636 | called. C<http()> reads the preload queue when it runs, so any call made | ||
| 637 | before that point will be included in the response. | ||
| 638 | |||
| 639 | Do B<not> call it from C<html()>: by the time C<html()> executes, C<http()> | ||
| 640 | has already emitted the headers and the Link headers will be lost. | ||
| 641 | |||
| 642 | =head3 What to preload | ||
| 643 | |||
| 644 | Preload only resources that are I<render-critical> for the current page - | ||
| 645 | assets the browser will definitely need within the first few seconds of | ||
| 646 | rendering. Good candidates: | ||
| 647 | |||
| 648 | =over 4 | ||
| 649 | |||
| 650 | =item * The primary stylesheet (C<as=style>) | ||
| 651 | |||
| 652 | =item * Web fonts referenced by that stylesheet (C<as=font>) | ||
| 653 | |||
| 654 | =item * A critical above-the-fold script (C<as=script>) | ||
| 655 | |||
| 656 | =back | ||
| 657 | |||
| 658 | Avoid preloading everything: unused preloads waste bandwidth and compete with | ||
| 659 | resources the browser has already prioritised. Per-page subclasses are the | ||
| 660 | right place because each page knows exactly which assets its template needs. | ||
| 661 | |||
| 662 | =head3 Examples | ||
| 663 | |||
| 664 | Typical use inside a page subclass: | ||
| 665 | |||
| 666 | package VWF::Display::index; | ||
| 667 | use parent 'VWF::Display'; | ||
| 668 | |||
| 669 | sub new { | ||
| 670 | my ($class, @args) = @_; | ||
| 671 | my $self = $class->SUPER::new(@args); | ||
| 672 | return unless defined $self; # blocked by Display (e.g. bad Referer) | ||
| 673 | |||
| 674 | # Register render-critical assets for this page. | ||
| 675 | # add_preload() returns $self so calls chain naturally. | ||
| 676 | $self->add_preload('/css/main.css', 'style') | ||
| 677 | ->add_preload('/fonts/body.woff2', 'font') # crossorigin added automatically | ||
| 678 | ->add_preload('/fonts/heading.woff2', 'font') | ||
| 679 | ->add_preload('/js/index.js', 'script'); | ||
| 680 | |||
| 681 | return $self; | ||
| 682 | } | ||
| 683 | |||
| 684 | These produce the following headers in the HTTP response: | ||
| 685 | |||
| 686 | Link: </css/main.css>; rel=preload; as=style | ||
| 687 | Link: </fonts/body.woff2>; rel=preload; as=font; crossorigin | ||
| 688 | Link: </fonts/heading.woff2>; rel=preload; as=font; crossorigin | ||
| 689 | Link: </js/index.js>; rel=preload; as=script | ||
| 690 | |||
| 691 | A resource fetched via C<fetch()> or C<XMLHttpRequest> that requires CORS: | ||
| 692 | |||
| 693 | $self->add_preload('/api/config.json', 'fetch', crossorigin => 1); | ||
| 694 | |||
| 695 | An above-the-fold hero image (no C<crossorigin> needed for images): | ||
| 696 | |||
| 697 | $self->add_preload('/img/hero.webp', 'image'); | ||
| 698 | |||
| 699 | =head3 Why the base class preloads nothing by default | ||
| 700 | |||
| 701 | C<VWF::Display> ships no assets of its own, so there is nothing framework-level | ||
| 702 | to preload. Additionally, C<http()> runs I<before> C<html()>, which means the | ||
| 703 | template has not yet been processed when the headers are emitted - the base | ||
| 704 | class has no way to inspect template contents to discover asset references | ||
| 705 | automatically. Each subclass is therefore responsible for declaring its own | ||
| 706 | dependencies explicitly. | ||
| 707 | |||
| 708 | =cut | ||
| 709 | |||
| 710 | sub add_preload | ||
| 711 | { | ||
| 712 | my ($self, $href, $as, %opts) = @_; | ||
| 713 | |||
| 714 | # Allowlist of valid W3C Resource Hints 'as' types (https://www.w3.org/TR/preload/). | ||
| 715 | # Any other value would produce an invalid Link header that browsers ignore. | ||
| 716 | my %valid_types = map { $_ => 1 } | ||
| 717 | qw(audio document embed fetch font image object script style track video worker); | ||
| 718 | croak "Unknown preload type '$as'; must be one of: " . join(', ', sort keys %valid_types) | ||
| 719 | unless $valid_types{$as}; | ||
| 720 | |||
| 721 | # SECURITY - header injection defence: | ||
| 722 | # $href is interpolated into the Link header value. Reject anything that | ||
| 723 | # is not a root-relative path; in particular, CRLF characters in $href | ||
| 724 | # would let a caller inject arbitrary HTTP headers. | ||
| 725 | croak "Preload href must be a root-relative path starting with '/'" | ||
| 726 | # (?![/\\]): "//host/x" (or "/\host/x") is another site, not a path here; | ||
| 727 | # \z: $ would let a trailing newline through | ||
| 728 | unless defined($href) && $href =~ m{\A/(?![/\\])[^\r\n]*\z}; | ||
| 729 | |||
| 730 | # Fonts loaded cross-origin (which is every font in practice, even same-origin, | ||
| 731 | # due to the CORS anonymous-mode requirement) must carry the crossorigin attribute | ||
| 732 | # or the browser will fetch them twice. Default it on for font type. | ||
| 733 | my $crossorigin = $opts{crossorigin} // ($as eq 'font' ? 1 : 0); | ||
| 734 | |||
| 735 | $self->{_preloads} ||= []; | ||
| 736 | push @{$self->{_preloads}}, { href => $href, as => $as, crossorigin => $crossorigin }; | ||
| 737 | |||
| 738 | return $self; # allow chaining: $self->add_preload(...)->add_preload(...) | ||
| 739 | } | ||
| 740 | |||
| 741 | =head2 http | ||
| 742 | |||
| 743 | Returns the HTTP header section, terminated by an empty line | ||
| 744 | |||
| 745 | =cut | ||
| 746 | |||
| 747 | # Generate and return the HTTP response headers (without the blank-line | ||
| 748 | # terminator - FCGI::Buffer appends that). Also emits Set-Cookie lines | ||
| 749 | # for session cookies, plus Link: rel=preload headers | ||
| 750 | # for any assets registered via add_preload(). | ||
| 751 | sub http | ||
| 752 | { | ||
| 753 | my $self = shift; | ||
| 754 | my $params = Params::Get::get_params(undef, @_); | ||
| 755 | |||
| 756 | # Emit Link: rel=preload headers for all assets queued by add_preload(). | ||
| 757 | # In HTTP/2 these headers instruct the server to push the assets before | ||
| 758 | # the browser has parsed the HTML and discovered them itself, eliminating | ||
| 759 | # a full round-trip for render-critical resources like stylesheets and fonts. | ||
| 760 | if(my $preloads = $self->{_preloads}) { | ||
| 761 | for my $p (@{$preloads}) { | ||
| 762 | my $link = "Link: <$p->{href}>; rel=preload; as=$p->{as}"; | ||
| 763 | # The crossorigin attribute is required for fonts and for any | ||
| 764 | # resource fetched in CORS anonymous mode; without it the browser | ||
| 765 | # will ignore the push and fetch the resource again anyway. | ||
| 766 | $link .= '; crossorigin' if $p->{crossorigin}; | ||
| 767 | print "$link\n"; | ||
| 768 | } | ||
| 769 | } | ||
| 770 | |||
| 771 | # Emit Set-Cookie headers for any cookies queued by set_cookie(). | ||
| 772 | # All cookies carry HttpOnly and SameSite=Strict; the Secure flag is | ||
| 773 | # added automatically when the connection is HTTPS. | ||
| 774 | if(my $cookies = $self->{_cookies}) { | ||
| 775 | foreach my $cookie (keys(%{$cookies})) { | ||
| 776 | my $value = exists $cookies->{$cookie} ? $cookies->{$cookie} : '0:0'; | ||
| 777 | my $secure = ($self->{'info'}->protocol() eq 'https') ? '; Secure' : ''; | ||
| 778 | print "Set-Cookie: $cookie=$value; path=/; HttpOnly; SameSite=Strict$secure\n"; | ||
| 779 | } | ||
| 780 | } | ||
| 781 | |||
| 782 | # Choose Content-Type from the template extension, or use the caller's | ||
| 783 | # override if one was supplied (e.g. for JSON or XML responses). | ||
| 784 | my $rc; | ||
| 785 | if($params->{'Content-Type'}) { | ||
| 786 | $rc = $params->{'Content-Type'} . "\n"; | ||
| 787 | } else { | ||
| 788 | my $filename = $self->get_template_path(); | ||
| 789 | if ($filename =~ /\.txt$/) { | ||
| 790 | $rc = "Content-Type: text/plain\n"; | ||
| 791 | } else { | ||
| 792 | # Switch STDOUT to UTF-8 mode before sending HTML to prevent | ||
| 793 | # the Perl runtime from inserting a spurious BOM. | ||
| 794 | binmode(STDOUT, ':utf8'); | ||
| 795 | $rc = "Content-Type: text/html; charset=UTF-8\n"; | ||
| 796 | } | ||
| 797 | } | ||
| 798 | |||
| 799 | # Seconds only (RFC 9110 section 10.2.3); anything else could inject headers | ||
| 800 | if(defined(my $retry_after = $params->{'Retry-After'})) { | ||
| 801 | croak("Retry-After must be a number of seconds, not '$retry_after'") | ||
| 802 | unless($retry_after =~ /\A\d+\z/); | ||
| 803 | $rc .= "Retry-After: $retry_after\n"; | ||
| 804 | } | ||
| 805 | |||
| 806 | # -- Defensive security headers ----------------------------------------- | ||
| 807 | # X-Frame-Options: prevents clickjacking by disallowing iframe embedding | ||
| 808 | # from cross-origin pages. (OWASP Clickjacking Defence Cheat Sheet) | ||
| 809 | # X-Content-Type-Options: stops browsers from MIME-sniffing the response | ||
| 810 | # away from the declared Content-Type, closing a class of XSS vectors. | ||
| 811 | # X-XSS-Protection: enables the legacy XSS auditor in older browsers. | ||
| 812 | # Referrer-Policy: sends the full URL only to same-origin requests, so | ||
| 813 | # sensitive URL parameters are not leaked to third-party analytics. | ||
| 814 | # Content-Security-Policy: whitelists script and style origins. | ||
| 815 | # 'unsafe-inline' is present for legacy templates; tighten this once | ||
| 816 | # all inline scripts have been migrated to external files. | ||
| 817 | # Maps made by HTML::OSM load Leaflet from unpkg.com and tiles from | ||
| 818 | # openstreetmap.org. Only the version of Leaflet that HTML::OSM uses is | ||
| 819 | # allowed, since unpkg.com serves every package on npm. | ||
| 820 | # Strict-Transport-Security: instructs the browser to use HTTPS for the | ||
| 821 | # next year; includeSubDomains covers all sub-sites. | ||
| 822 | return $rc . | ||
| 823 | "X-Frame-Options: SAMEORIGIN\n" . | ||
| 824 | "X-Content-Type-Options: nosniff\n" . | ||
| 825 | "X-XSS-Protection: 1; mode=block\n" . | ||
| 826 | "Referrer-Policy: strict-origin-when-cross-origin\n" . | ||
| 827 | "Content-Security-Policy: default-src 'self'; " . | ||
| 828 | "script-src 'self' 'unsafe-inline' https://unpkg.com/leaflet\@1.9.4/; " . | ||
| 829 | "style-src 'self' 'unsafe-inline' https://unpkg.com/leaflet\@1.9.4/; " . | ||
| 830 | "img-src 'self' data: https://unpkg.com/leaflet\@1.9.4/ https://*.tile.openstreetmap.org\n" . | ||
| 831 | "Strict-Transport-Security: max-age=31536000; includeSubDomains\n\n"; | ||
| 832 | } | ||
| 833 | |||
| 834 | # Run the given data through the template to create HTML | ||
| 835 | |||
| 836 | # Override this routine in a subclass if you wish to create special arguments to | ||
| 837 | # send to the template | ||
| 838 | sub html { | ||
| 839 | my $self = shift; | ||
| 840 | my %params = (ref($_[0]) eq 'HASH') ? %{$_[0]} : @_; | ||
| 841 | |||
| 842 | my $filename = $self->get_template_path(); | ||
| 843 | my $rc; | ||
| 844 | |||
| 845 | # Handle template files (.tmpl or .tt) | ||
| 846 | if($filename =~ /.+\.t(mpl|t)$/) { | ||
| 847 | require Template; | ||
| 848 | Template->import(); | ||
| 849 | |||
| 850 | my $info = $self->{_info}; | ||
| 851 | |||
| 852 | # The values in config are defaults which can be overridden by | ||
| 853 | # the values in info, then the values in params | ||
| 854 | # Always build a fresh hash: the template variables added below must | ||
| 855 | # not leak into the object's configuration or into the CGI parameters | ||
| 856 | my $vals = { | ||
| 857 | %{$self->{_config} // {}}, | ||
| 858 | %{$info->params() // {}}, | ||
| 859 | %params, | ||
| 860 | }; | ||
| 861 | $vals->{script_name} = $info->script_name(); | ||
| 862 | |||
| 863 | $vals->{cart} = $info->get_cookie(cookie_name => 'cart'); | ||
| 864 | $vals->{lingua} = $self->{_lingua}; | ||
| 865 | $vals->{social_media} = $self->{_social_media}; | ||
| 866 | $vals->{info} = $info; | ||
| 867 | $vals->{as_string} = $info->as_string(); | ||
| 868 | |||
| 869 | my $template = Template->new({ | ||
| 870 | INTERPOLATE => 1, | ||
| 871 | POST_CHOMP => 1, | ||
| 872 | ABSOLUTE => 1, | ||
| 873 | PLUGINS => { JSON => 'Template::Plugin::JSON' }, | ||
| 874 | }); | ||
| 875 | |||
| 876 | $self->_debug({ message => __PACKAGE__ . ': ' . __LINE__ . ': Passing these to the template: ' . join(', ', keys %{$vals}) }); | ||
| 877 | |||
| 878 | # Process the template | ||
| 879 | if(!$template->process($filename, $vals, \$rc)) { | ||
| 880 | if(my $err = $template->error()) { | ||
| 881 | throw Error::Simple($err); | ||
| 882 | } | ||
| 883 | throw Error::Simple("Unknown error in template: $filename"); | ||
| 884 | } | ||
| 885 | } elsif($filename =~ /\.(html?|txt)$/) { | ||
| 886 | # Handle static HTML or text files | ||
| 887 | open(my $fin, '<', $filename) || throw Error::Simple("$filename: $!"); | ||
| 888 | |||
| 889 | my @lines = <$fin>; | ||
| 890 | |||
| 891 | close $fin; | ||
| 892 | |||
| 893 | $rc = join('', @lines); | ||
| 894 | } else { | ||
| 895 | throw Error::Simple("Unhandled file type $filename"); | ||
| 896 | } | ||
| 897 | |||
| 898 | # Check for mailto links and log a warning | ||
| 899 | if(($filename !~ /.txt$/) && ($rc =~ /\smailto:(.+?)>/) && ($1 !~ /^&/) && $self->{_logger}) { | ||
| 900 | $self->{_logger}->warn({ message => "Found mailto link $1, you should remove it or use " . obfuscate($1) . ' instead' }); | ||
| 901 | } | ||
| 902 | |||
| 903 | return $rc; | ||
| 904 | } | ||
| 905 | |||
| 906 | sub _debug | ||
| 907 | { | ||
| 908 | my $self = shift; | ||
| 909 | |||
| 910 | if(my $logger = $self->{_logger}) { | ||
| 911 | my %params = (ref($_[0]) eq 'HASH') ? %{$_[0]} : @_; | ||
| 912 | if(defined($ENV{'REMOTE_ADDR'})) { | ||
| 913 | $logger->debug("$ENV{'REMOTE_ADDR'}: $params{'message'}"); | ||
| 914 | } else { | ||
| 915 | $logger->debug($params{'message'}); | ||
| 916 | } | ||
| 917 | } | ||
| 918 | return $self; | ||
| 919 | } | ||
| 920 | |||
| 921 | # Encode a string as HTML numeric entities, e.g. 'a@b' => 'a@b'. | ||
| 922 | # Always returns one string: it is used inside a concatenation, where a list | ||
| 923 | # would be counted rather than joined. | ||
| 924 | sub obfuscate { | ||
| 925 | return join('', map { '&#' . ord($_) . ';' } split(//, shift)); | ||
| 926 | } | ||
| 927 | |||
| 928 | sub _types | ||
| 929 | { | ||
| 930 | my $self = shift; | ||
| 931 | my $info = $self->{_info}; | ||
| 932 | my @rc; | ||
| 933 | |||
| 934 | if($info->is_search_engine()) { | ||
| 935 | push @rc, 'search', 'robot'; | ||
| 936 | } elsif($info->is_mobile()) { | ||
| 937 | push @rc, 'mobile'; | ||
| 938 | } elsif($info->is_ai()) { | ||
| 939 | # AI crawlers are robots, so fall back to the robot templates | ||
| 940 | push @rc, 'ai', 'robot', 'search'; | ||
| 941 | } elsif($info->is_robot()) { | ||
| 942 | push @rc, 'robot', 'search'; | ||
| 943 | } | ||
| 944 | push @rc, 'web'; | ||
| 945 | |||
| 946 | if(my $logger = $self->{'_logger'}) { | ||
| 947 | $logger->trace('< ', __PACKAGE__, '::_types returning ', join(':', @rc)); | ||
| 948 | } | ||
| 949 | |||
| 950 | return @rc; | ||
| 951 | } | ||
| 952 | |||
| 953 | # Issue a fresh CSRF token to a page that has a form, so that the form can embed it. | ||
| 954 | # The token is validated server-side when the form is submitted. | ||
| 955 | # CSRF protection is enabled by default and can be turned off in config. | ||
| 956 | # Other pages aren't sent one: FCGI::Buffer won't cache or save a page that has a | ||
| 957 | # Set-Cookie header, since it would give that cookie to everyone. | ||
| 958 | sub _send_csrf_token($self, $page) { | ||
| 959 | return unless($page =~ /<form\b/i); | ||
| 960 | return unless($self->{config}->{security}->{csrf}->{enable} // 1); | ||
| 961 | |||
| 962 | my $csrf_token = $self->_generate_csrf_token(); | ||
| 963 | print "Set-Cookie: csrf_token=$csrf_token; path=/; HttpOnly; SameSite=Strict\n"; | ||
| 964 | } | ||
| 965 | |||
| 966 | sub _generate_csrf_token($self) { | ||
| 967 | # Prefer an explicitly configured HMAC secret from security.csrf.secret. | ||
| 968 | # If absent, fall back to a per-process random secret generated at first use | ||
| 969 | # and warn once so the operator knows to configure a persistent one. | ||
| 970 | # A per-process secret is still cryptographically strong (no hardcoded value), | ||
| 971 | # but tokens will be invalidated whenever the FastCGI process restarts. | ||
| 972 | my $secret = $self->{config}->{security}->{csrf}->{secret}; | ||
| 973 | unless(defined $secret) { | ||
| 974 | unless(defined $_csrf_fallback_secret) { | ||
| 975 | $_csrf_fallback_secret = unpack('H*', urandom(32)); | ||
| 976 | my $config_path = $self->{config}->{config_path} | ||
| 977 | ? join(', ', @{$self->{config}->{config_path}}) | ||
| 978 | : 'conf/' . ($self->{info} ? ($self->{info}->domain_name() // 'unknown') : 'unknown'); | ||
| 979 | carp "VWF: security.csrf.secret is not configured; " | ||
| 980 | . 'using a per-process random secret. ' | ||
| 981 | . 'CSRF tokens will not survive process restarts. ' | ||
| 982 | . "Add <security><csrf><secret>...</secret></csrf></security> " | ||
| 983 | . "to $config_path to suppress this warning."; | ||
| 984 | } | ||
| 985 | $secret = $_csrf_fallback_secret; | ||
| 986 | } | ||
| 987 | |||
| 988 | # SECURITY - use a cryptographically secure RNG, not rand(). | ||
| 989 | # Perl's built-in rand() is a predictable PRNG; if an attacker knows the | ||
| 990 | # approximate server time they can enumerate the 32-bit output space in | ||
| 991 | # seconds. Crypt::URandom reads from /dev/urandom (or the OS equivalent), | ||
| 992 | # giving 256 bits of unpredictable entropy as a 64-character hex string. | ||
| 993 | my $random = unpack('H*', urandom(32)); | ||
| 994 | my $timestamp = time(); | ||
| 995 | my $token_data = "$timestamp:$random"; | ||
| 996 | |||
| 997 | # Build an HMAC-style signature: sha256( token_data || ':' || secret ). | ||
| 998 | # The server must re-derive and compare this signature on form submission. | ||
| 999 | my $signature = sha256_hex("$token_data:$secret"); | ||
| 1000 | |||
| 1001 | return "$token_data:$signature"; | ||
| 1002 | } | ||
| 1003 | |||
| 1004 | sub cache_key_from_hashref { | ||
| 1005 | my $hashref = $_[0]; | ||
| 1006 | |||
| 1007 | # Use Data::Dumper with sorted keys for consistent output | ||
| 1008 | local $Data::Dumper::Sortkeys = 1; | ||
| 1009 | local $Data::Dumper::Terse = 1; | ||
| 1010 | local $Data::Dumper::Indent = 0; | ||
| 1011 | |||
| 1012 | my $dumped = Dumper($hashref); | ||
| 1013 | |||
| 1014 | # Create an MD5 hash for a compact key | ||
| 1015 | return md5_hex($dumped); | ||
| 1016 | } | ||
| 1017 | |||
| 1018 | 1; | ||
| 1019 | |||
| 1020 | =head1 METHODS | ||
| 1021 | |||
| 1022 | =head2 new | ||
| 1023 | |||
| 1024 | Takes a hash or a hash reference of the request's C<info>, C<lingua>, C<config>, | ||
| 1025 | C<logger>, C<cache>, C<config_dir> and so on, which L<Web::VWF> supplies. | ||
| 1026 | Validates the Referer, reads the configuration again for itself, runs | ||
| 1027 | L<CGI::IDS> and the throttle, and blocks a blacklisted country. Returns undef | ||
| 1028 | when the request is to be refused and croaks on an attack. | ||
| 1029 | |||
| 1030 | =head3 API SPECIFICATION | ||
| 1031 | |||
| 1032 | =head4 INPUT | ||
| 1033 | |||
| 1034 | { | ||
| 1035 | info => { type => 'object' }, | ||
| 1036 | lingua => { type => 'object', optional => 1 }, | ||
| 1037 | config => { type => 'object', optional => 1 }, | ||
| 1038 | logger => { type => 'object', optional => 1 }, | ||
| 1039 | cache => { type => 'object', optional => 1 }, | ||
| 1040 | config_dir => { type => 'string', optional => 1 }, | ||
| 1041 | } | ||
| 1042 | |||
| 1043 | =head4 OUTPUT | ||
| 1044 | |||
| 1045 | { type => 'object', isa => 'Web::VWF::Display', optional => 1 } | ||
| 1046 | |||
| 1047 | =head2 as_string | ||
| 1048 | |||
| 1049 | Takes a hash reference of the variables for the template and returns the | ||
| 1050 | headers, from C<http>, and the page, from C<html>. The result is kept in memory | ||
| 1051 | for five minutes unless the client has a cart. A page that returns a string | ||
| 1052 | starting C<Location:> from C<html> is sent as a redirect. | ||
| 1053 | |||
| 1054 | =head2 html | ||
| 1055 | |||
| 1056 | Renders the template found by C<get_template_path>. A subclass overrides it, | ||
| 1057 | validates its input, and calls C<SUPER::html> with the variables for the | ||
| 1058 | template. The template sees the configuration, then the CGI parameters, then | ||
| 1059 | those variables, each overriding the one before. | ||
| 1060 | |||
| 1061 | =head2 get_template_path | ||
| 1062 | |||
| 1063 | The path of the template for the page: under F<$root_dir/templates/>, by the kind | ||
| 1064 | of client, the language and its dialect, and then the class's name, so that | ||
| 1065 | C<Web::VWF::Display::index> is F<web/Web/VWF/Display/index.tmpl>. Dies if there | ||
| 1066 | is none. | ||
| 1067 | |||
| 1068 | =head2 cache_key_from_hashref | ||
| 1069 | |||
| 1070 | A function and not a method: an MD5 sum of a hash reference, the same for | ||
| 1071 | equal contents, to name the cached page. | ||
| 1072 | |||
| 1073 | =head2 obfuscate | ||
| 1074 | |||
| 1075 | A function and not a method: a string written as HTML numeric entities, which | ||
| 1076 | a template uses to make an e-mail address harder for a robot to read. | ||
| 1077 | |||
| 1078 | =head1 AUTHOR | ||
| 1079 | |||
| 1080 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||
| 1081 | |||
| 1082 | =head1 LICENCE AND COPYRIGHT | ||
| 1083 | |||
| 1084 | Copyright 2010-2026 Nigel Horne. | ||
| 1085 | |||
| 1086 | Usage is subject to the GPL2 licence terms. | ||
| 1087 | If you use it, | ||
| 1088 | please let me know. | ||
| 1089 | |||
| 1090 | =cut |