view release on metacpan or  search on metacpan

lib/Developer/Dashboard/Web/App.pm  view on Meta::CPAN

use Developer::Dashboard::JSON qw(json_encode);
use Developer::Dashboard::Platform qw(command_in_path is_windows);
use Developer::Dashboard::TextUtils qw(_trim);
use Developer::Dashboard::HtmlEscape qw(_escape_html _escape_html_attr);
use Developer::Dashboard::PageDocument;
use Developer::Dashboard::PageRuntime;
use Developer::Dashboard::Codec qw(decode_payload);
use Developer::Dashboard::Zipper ();
use Developer::Dashboard::SkillDispatcher ();
use Developer::Dashboard::Auth ();
our $MODULE_SOURCE_PATH = File::Spec->rel2abs(__FILE__);
our $ORIG_CWD = cwd();    # compile-time CWD so rel2abs resolves correctly even after chdir

# new(%args)
# Constructs the browser-facing dashboard web application.
# Input: auth, pages, sessions, config, and optional actions/resolver objects.
# Output: Developer::Dashboard::Web::App object.
sub new {
    my ( $class, %args ) = @_;
    my $auth     = $args{auth}     || die 'Missing auth store';
    my $pages    = $args{pages}    || die 'Missing page store';
    my $sessions = $args{sessions} || die 'Missing session store';
    my $runtime = $args{runtime};
    if ( !$runtime ) {
        $runtime = Developer::Dashboard::PageRuntime->new(
            paths => ref($pages) eq 'Developer::Dashboard::PageStore' ? $pages->{paths} : undef,
        );
    }
    return bless {
        actions  => $args{actions},
        auth     => $auth,
        config   => $args{config},
        pages    => $pages,
        prompt   => $args{prompt},
        runtime  => $runtime,
        resolver => $args{resolver},
        sessions => $sessions,
    }, $class;
}

# HTTP methods that can change server state. The Origin/Referer half of the
# cross-site request forgery defense applies to exactly these, because a
# browser only guarantees an Origin header on a cross-site state-changing
# request. The fetch-metadata half below carries no such limit and covers GET
# too, which is what the code-executing saved-Ajax route needs.
my %STATE_CHANGING_METHODS = map { $_ => 1 } qw(POST PUT DELETE PATCH);

# Fetch-metadata values that mean the request was not issued by this
# dashboard's own pages. The browser sets Sec-Fetch-Site itself and it is a
# forbidden header name, so page script can neither forge nor suppress it.
# `same-origin` is the dashboard's own page and `none` is a user-initiated load
# (typed URL, bookmark, browser start-up), so both stay outside the check.
my %FOREIGN_FETCH_SITES = map { $_ => 1 } qw(cross-site same-site);

# _csrf_rejection_response(%args)
# Cross-site request forgery choke point for every request. Browsers
# unconditionally attach an Origin header to cross-site state-changing
# requests (and legacy flows carry a Referer), so a foreign Origin/Referer
# identifies an attack regardless of trust tier: the loopback-admin shortcut,
# an ambient helper session cookie, and even valid machine credentials must all
# refuse to act on it. Requests carrying neither header are allowed because
# non-browser machine clients (curl, registered x-dd-api-key consumers) send
# neither, while a hostile page cannot suppress the Origin header on a
# cross-site state-changing request. A GET needs the separate fetch-metadata
# check, which runs first and on every method.
# Input: normalized request method and headers (host, origin, referer,
# sec-fetch-site).
# Output: 403 empty-body response array reference when the browser context is
# foreign, otherwise undef and the request proceeds to tier dispatch.
sub _csrf_rejection_response {
    my ( $self, %args ) = @_;

    # Fetch metadata is checked on every method, not just the state-changing
    # ones: a saved-Ajax handler is an operator-written script that the
    # `/ajax/<file>` route runs from a plain GET, so GET is not a safe method
    # here. Origin cannot defend that route — browsers omit Origin on
    # same-origin GETs, and a hostile page can drop its Referer with a referrer
    # policy — but it cannot touch Sec-Fetch-Site.
    return $self->_csrf_forbidden_response if $self->_fetch_site_is_foreign(%args);

    my $method = uc( $args{method} || 'GET' );
    return undef if !$STATE_CHANGING_METHODS{$method};
    my $headers = $args{headers} || {};
    my $source = _browser_source_value($headers);
    return undef if $source eq '';
    return $self->_csrf_forbidden_response
      if !$self->_request_source_is_same_site( source => $source, headers => $headers );
    return undef;
}

# _fetch_site_is_foreign(%args)
# Reports whether the browser itself labelled this request as coming from
# another site. A request carrying no Sec-Fetch-Site is never foreign, which
# keeps non-browser clients (curl, registered x-dd-api-key consumers) and
# browsers too old to send fetch metadata working exactly as before; a hostile
# page cannot reach that shape, because every browser that can be scripted into
# making the request also sends the header. A cross-site or same-site label is
# foreign unless the accompanying Origin/Referer names this dashboard or a
# trusted local alias, which keeps the localhost/127.0.0.1 pair — one host to
# the loopback trust model, two sites to the browser — serving normally.
# Input: normalized request headers (sec-fetch-site, origin, referer, host).
# Output: boolean true when the request comes from a foreign browser context.
sub _fetch_site_is_foreign {
    my ( $self, %args ) = @_;
    my $headers = $args{headers} || {};
    my $site =
      defined $headers->{'sec-fetch-site'} && !ref( $headers->{'sec-fetch-site'} )
      ? lc $headers->{'sec-fetch-site'}
      : '';
    $site =~ s/^\s+//;
    $site =~ s/\s+$//;
    return 0 if !$FOREIGN_FETCH_SITES{$site};
    my $source = _browser_source_value($headers);
    return 1 if $source eq '';
    return $self->_request_source_is_same_site( source => $source, headers => $headers ) ? 0 : 1;
}

# _browser_source_value($headers)
# Picks the header that names the browser context a request came from. Origin
# wins when present and Referer is the legacy fallback; reference-valued header

lib/Developer/Dashboard/Web/App.pm  view on Meta::CPAN

    elsif ( $filename =~ /\.svg$/i ) {
        return 'image/svg+xml';
    }
    elsif ( $filename =~ /\.png$/i ) {
        return 'image/png';
    }
    elsif ( $filename =~ /\.jpe?g$/i ) {
        return 'image/jpeg';
    }
    elsif ( $filename =~ /\.gif$/i ) {
        return 'image/gif';
    }
    elsif ( $filename =~ /\.webp$/i ) {
        return 'image/webp';
    }
    elsif ( $filename =~ /\.ico$/i ) {
        return 'image/x-icon';
    }
    else {
        return 'application/octet-stream';
    }
}

1;

__END__

=encoding UTF-8

=head1 NAME

Developer::Dashboard::Web::App - local web application for Developer Dashboard

=head1 SYNOPSIS

  my $app = Developer::Dashboard::Web::App->new(
      auth     => $auth,
      pages    => $pages,
      sessions => $sessions,
  );

=head1 DESCRIPTION

This module handles the browser-facing dashboard routes, helper login flow,
page rendering modes, and page/action execution endpoints. It also provides
static file serving for JavaScript, CSS, and other assets from the public
directory structure (~/.developer-dashboard/dashboard/public/{js,css,others}).
The browser tab icon at C</favicon.ico> is served from the same layered
C<others> roots with a bundled fallback, and resolves before the authorization
gate because browsers request it implicitly on every page load.

Cross-site request forgery defense: every state-changing request (POST, PUT,
DELETE, PATCH) passes one origin check before any trust-tier dispatch. When
the request carries an C<Origin> header (or, absent that, a C<Referer>), its
authority must equal the request's own C<Host> header or name a trusted local
alias — a numeric loopback literal, the localhost hostname family, or a
configured C<web.ssl_subject_alt_names> entry, the same alias semantics the
loopback-admin trust check applies. Anything else, including the opaque
C<Origin: null>, is refused with an empty 403 on every tier: the
loopback-admin shortcut, helper sessions, and the machine API tier alike,
because browsers attach ambient credentials and loopback reachability to
cross-site requests automatically. Requests with neither header keep working,
since non-browser machine clients send neither while browsers always attach
C<Origin> to cross-site state-changing requests. The check also holds behind
the SSL front-proxy, which forwards TLS bytes unmodified, so the backend
compares against the browser's own C<Host> header.

That origin check cannot defend a C<GET>, because browsers omit C<Origin> on
same-origin GETs and a hostile page can drop its C<Referer> with a referrer
policy — yet C</ajax/E<lt>fileE<gt>> runs an operator-written saved handler as
a child process from a plain GET, on a tier that needs no cookie. So the same
choke point additionally refuses, on B<every> method, any request the browser
labelled C<Sec-Fetch-Site: cross-site> or C<same-site>, unless the
accompanying C<Origin>/C<Referer> names this dashboard or a trusted local
alias (the C<localhost>/C<127.0.0.1> pair is one host to the trust model and
two sites to the browser). C<Sec-Fetch-Site> is set by the browser itself and
is a forbidden header name, so page script can neither forge nor suppress it.
Requests carrying no fetch metadata are unaffected, which keeps machine
clients and browsers too old to send it working unchanged.

=head1 METHODS

=head2 new, handle

Construct and dispatch the local web application.

=head2 _serve_static_file($type, $filename)

Serves static files from the public directory.

Input: $type (js, css, or others subdirectory), $filename (requested filename).
Output: array reference of [status_code, content_type, body].

Security: Prevents directory traversal attacks and verifies files are within
the public directory before serving.

=head2 _static_path_contained($file_path, $allowed_roots)

Package function asserting that one resolved static asset path still lives
beneath an allowed public root after symlinks and parent-directory components
are resolved with C<Cwd::abs_path>, denying by default when no allowed roots
are supplied. Every static-serving entry point passes its lookup roots through
this check before opening a resolved path, including skill-namespaced assets,
whose allowed roots come from the skill dispatcher's layered
C<dashboards/public> trees.

Input: resolved candidate file path string and array reference of allowed root
directory path strings.
Output: boolean true when the resolved path is inside one existing allowed
root, otherwise false.

=head2 _get_content_type($type, $filename)

Determines the MIME type for a file based on its type and extension.

Input: $type (js, css, or others), $filename (requested filename).
Output: MIME type string suitable for Content-Type header.

Supports: JS, CSS, JSON, XML, HTML, SVG, PNG, JPEG, GIF, WebP, ICO, and others.

=for comment FULL-POD-DOC START