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

filter: Statementstmt 0.0% 0 / 439 Branchbran 0.0% 0 / 194 Conditioncond 0.0% 0 / 86 MC/DCmcdc 0.0% 0 / 49 Subroutinesub 0.0% 0 / 45 Podpod 0.0% 0 / 14 totaltotal 0.0% 0 / 827 CC 98 SCAR 53.4
CC
98
Cov
0%
new
702.0
get_template_path
342.0
as_string
156.0
CRAP 208.6
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' => '&#97;&#64;&#98;'.
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