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

Documentation page describing how Haketilo selects policy to apply to a page.

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 %} Policy selection {% endblock %}

{% block main %}
  {{ big_heading('Page policy selection') }}

  {% call section() %}
    {% call paragraph() %}
      When a web page is opened, Haketilo is capable of either
      {% call unordered_list() %}
        {% call list_entry() %}
          blocking page's own scripts and
          {{ doc_page_link('injecting payload', 'packages') }}
          configured by the user,
        {% endcall %}
        {% call list_entry() %}
          blocking page's own scripts and injecting an automatically-chosen
          payload that is usable with the page,
        {% endcall %}
        {% call list_entry() %}
          presenting a dialog asking whether to enable an automatically-chosen
          payload that is usable with the page,
        {% endcall %}
        {% call list_entry() %}
          {{ doc_page_link('blocking', 'script_blocking') }} page's own scripts
          or
        {% endcall %}
        {% call list_entry() %}
          allowing page's own scripts to execute normally (i.e. not modifying
          the page in any meaningful way).
        {% endcall %}
      {% endcall %}
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Policy precedence') }}

    {% call paragraph() %}
      User configures Haketilo's behavior by defining script-blocking and
      -allowing rules and by adding and enabling packages. Each rule and each
      package payload has a {{ doc_page_link('URL pattern', 'url_patterns') }}.
      This pattern determines which pages the policy is compatible with.
      Patterns also have well-defined specificity. When multiple rules and
      packages are combatible with given page's URL, the one with the most
      specific pattern "wins". In case of a tie, payload injection is assumed to
      take precedence over rule application.
    {% endcall %}

    {% call paragraph() %}
      In the absence of suitable rules and enabled packages, Haketilo may
      consider non-enabled packages that are suitable for use on the
      currently-visited site. It will either inject package payload
      automatically, ask the user whether to enable the package or ignore it
      completely. The user can switch between these 3 behaviors on the Haketilo
      {{ hkt_link('settings page', 'home.home') }}. Packages that were
      explicitly marked as disabled will always be ignored. Pattern specificity
      is also taken into account in case of multiple packages.
    {% endcall %}

    {% call paragraph() %}
      When absolutely no explicit policy appears suitable for given page,
      Haketilo will apply its default script handling behavrior. Whether
      JavaScript is blocked or allowed by default is also determined by user's
      choice on the {{ hkt_link('settings page', 'home.home') }}.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Special cases') }}

    {% call paragraph() %}
      The sites served by Haketilo itself are exempt from all policies. These
      are <code>http://hkt.mitm.it</code>, <code>https://hkt.mitm.it</code>
      and <code>http://mitm.it</code>. Additionally, if Haketilo experiences an
      internal error (e.g. because it could not parse current URL as sent in by
      the browser), it will try to block page's JavaScript as a security
      measure.
    {% endcall %}

    {% call paragraph() %}
      Internally, Haketilo also has a special high-priority policy for serving
      files used by payloads and for making its APIs accessible to payload
      scripts. This is, however, an implementation detail and casual users need
      not care about it nor understand these nuances.
    {% endcall %}
  {% endcall %}
{% endblock main %}