{#
SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0

Documentation page describing how Haketilo blocks scripts.

This file is part of Hydrilla&Haketilo.

Copyright (C) 2022 Wojtek Kosior

Dual licensed under
* GNU General Public License v3.0 or later and
* Creative Commons Attribution Share Alike 4.0 International.

You can choose to use either of these licenses or both.


I, Wojtek Kosior, thereby promise not to sue for violation of this
file's licenses. Although I request that you do not make use of this
code in a proprietary work, I am not going to enforce this in court.
#}
{% extends "doc_base.html.jinja" %}

{% block title %} Script blocking {% endblock %}

{% block main %}
  {{ big_heading('Script blocking in Haketilo') }}

  {% call section() %}
    {% call paragraph() %}
      Modern web browsers allow sites to execute software on users'
      devices. This software is usually written in a language called JavaScript
      and abbreviated as JS. It can serve various purposes - from small
      enhancements to deployment of heavy applications inside the
      browser. Because Haketilo aims to give users control over their web
      browsing, one of its supported features is blocking of JavaScript
      execution on per-page and per-site basis.
    {% endcall %}

    {% call paragraph() %}
      Besides the casual script-blocking discussed here, Haketilo also blocks
      page's JavaScript when injecting the user-specified
      {{ doc_page_link('script payloads', 'packages') }}. That functionality is
      described on its own documentation page.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Configuring script blocking') }}

    {% call paragraph() %}
      User can
      {{
        hkt_link('define script-blocking and -allowing rules', 'rules.rules')
      }}
      using {{ doc_page_link('URL patterns', 'url_patterns') }}. Each such rule
      tells Haketilo to either block or allow scripts on pages matched by its
      pattern. Rules with more specific patterns can override those with less
      specific ones as described on the
      {{ doc_page_link('policy selection page', 'policy_selection') }}.
    {% endcall %}

    {% call paragraph() %}
      As an example, if we want all scripts on english Wikipedia pages to be
      blocked, we can add a blocking rule with
      pattern <code>https://en.wikipedia.org/***</code>. If we then wanted to
      make an exception just for the "List of emoticons" page, we could create
      an additional allowing rule with
      <code>https://en.wikipedia.org/wiki/List_of_emoticons</code> as its
      pattern. It would take effect on that page while all the other english
      Wikipedia pages would still have their scripts blocked.
    {% endcall %}

    {% call paragraph() %}
      It is also possible to configure whether scripts should be blocked by
      dafault on pages where no explicit rule and no payload is used. The
      relevant option can be found on Haketilo
      {{ hkt_link('settings page', 'home.home') }}.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Use with other script-blocking tools') }}

    {% call paragraph() %}
      Various browsers and browser extension can also be configured to block
      JavaScript. Haketilo works independently of those tools. If the user
      desires to have scripts on certain page to execute normally, both Haketilo
      and other tools must be configured to allow that.
    {% endcall %}

    {% call paragraph() %}
      Unlike most similar tools, Haketilo operates outside the web browser. As a
      result, it is relatively unlikely for Haketilo to cause these to
      malfunction. At the same time, it is relatively easy to have another
      script blocker break some Haketilo functionality (e.g. its
      {{ doc_page_link('popup', 'popup') }}).
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Technical details') }}

    {% call paragraph() %}
      From technical point of view, Haketilo, as of version 3.0, blocks
      JavaScript by altering the Content-Security-Policy (abbreviated CSP)
      headers in HTTP responses. The original CSP directives sent by site are
      retained, with exception of those which would result in CSP violation
      reports being sent. Haketilo's own script-blocking directives are then
      added to produce the final CSP which user's web browser eventually sees.
    {% endcall %}

    {% call paragraph() %}
      The above means that neither the scripts that would be blocked by page's
      own rules nor those that are blocked by Haketilo are going to cause CSP
      reports to be sent.
    {% endcall %}

    {% call paragraph() %}
      In addition, even when a page has JavaScript nominally blocked, Haketilo
      3.0 may nevertheless inject into it its own script responsible for making
      the popup available. The CSP is then modified appropriately to allow only
      that script to run.
    {% endcall %}
  {% endcall %}
{% endblock main %}