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

Documentation page describing Haketilo popup.

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

{% block main %}
  {{ big_heading('Haketilo popup') }}

  {% call section() %}
    {% call paragraph() %}
      Taking inspiration from user interface features of browser extensions,
      Haketilo also offers a popup window for quick interaction with the
      user. For technical reasons, the popup is presented as part of the web
      page and behaves slightly differently from those some users might have
      found in similar tools.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Operating') }}

    {% call paragraph() %}
      The popup dialog can be opened by typing big letters "HKT" anywhere on the
      page. It then presents some basic information about the handling of
      current URL. It also allows the user quickly define new
      {{ doc_page_link('rules', 'script_blocking') }} or
      {{ doc_page_link('payloads', 'packages') }} for it. As of Haketilo 3.0,
      however, the actual configuration is not performed from the popup itself
      but rather a relevant Haketilo rule/payload definition page is opened in a
      new tab.
    {% endcall %}

    {% call paragraph() %}
      The dialog can be closed by clicking anywhere on the darker area around
      it. It can then be reopened by typing "HKT" again.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Enabling/disabling') }}

    {% call paragraph() %}
      Popup is unavailable by default on Haketilo special sites including
      <code>https://hkt.mitm.it</code>. It can also be disabled independently on
    {% endcall %}

    {% call unordered_list() %}
      {% call list_entry() %}
        pages with JS allowed,
      {% endcall %}
      {% call list_entry() %}
        pages with JS blocked and
      {% endcall %}
      {% call list_entry() %}
        pages with script payload injected.
      {% endcall %}
    {% endcall %}

    {% call paragraph() %}
      This can be configured on the {{ hkt_link('setings page', 'home.home') }}
      and might be useful to users who are careful about fingerprinting.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Fingerprinting considerations') }}

    {% call paragraph() %}
      To make the popup available, Haketilo has to inject an additional script
      to all pages. That makes it easy for pages to determine with certainty
      that given user is running Haketilo. This has implications for privacy and
      may also be used by a hostile site to selectively cause annoyance to
      Haketilo users.
    {% endcall %}

    {% call paragraph() %}
      The above problems would be present regardless on pages with
      Haketilo-injected payloads. I.e. in many cases a site could theoretically
      find out the user is not accessing it in a normal way. However, the popup
      also increases fingerprintability when no payload is in use and especially
      on pages with JavaScript allowed. For this reason, the presence of popup
      on pages has been made configurable.
    {% endcall %}

    {% call paragraph() %}
      It is also worth noting that as of version 3.0 Haketilo does not make
      guarantees about the browser fingerprint. Despite best efforts, there are
      still other aspects that might make a Haketilo user distinguishable to a
      website even when popup is disabled.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ medium_heading('Other caveats') }}

    {% call paragraph() %}
      Some other potential issues related to the popup are described below.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ small_heading('Interference with the site') }}

    {% call paragraph() %}
      The popup gets injected by Haketilo into the actual web page. Although
      care was taken to make accidental breakage unlikely, it might still happen
      under some specific conditions.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ small_heading('Interference with other script-blocking tools') }}

    {% call paragraph() %}
      The popup is driven by a piece of JavaScript code injected by Haketilo to
      pages. Haketilo by itself makes sure neither the policies specified by the
      page nor its own script-blocking mechanisms interfere with this particular
      piece. In spite of that, a browser extension or web browser's own settings
      might prevent the popup script from executing, making the dialog
      unavailable.
    {% endcall %}
  {% endcall %}

  {% call section() %}
    {{ small_heading('URL mismatch') }}

    {% call paragraph() %}
      Sometimes a page might change parts of its address visible in browser's
      URL bar. E.g. after opening <code>https://entraide.chatons.org/</code> in
      the browser we might see <code>https://entraide.chatons.org/en/</code> as
      the current address even though no reload happened. In addition, some
      browsers hide URL's traling dash ("/") from the user. Regardless of that,
      Haketilo's popup always presents the original URL under which the current
      page was served. Although this the intended behavior, it might cause
      confusion and therefore has been documented here.
    {% endcall %}
  {% endcall %}
{% endblock main %}