[proxy] document popup

4 files changed, 317 insertions, 25 deletions

diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
index 983a5e8..7f6760e 100644
--- a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
+++ b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
@@ -14,7 +14,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: hydrilla 2.0\n"
 "Report-Msgid-Bugs-To: koszko@koszko.org\n"
-"POT-Creation-Date: 2022-10-27 17:22+0200\n"
+"POT-Creation-Date: 2022-10-27 19:46+0200\n"
 "PO-Revision-Date: 2022-02-12 00:00+0000\n"
 "Last-Translator: Wojtek Kosior <koszko@koszko.org>\n"
 "Language: en_US\n"
@@ -228,31 +228,31 @@ msgstr "Page info"
 msgid "info.base.heading.page_info"
 msgstr "Haketilo page handling details"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:47
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:48
 msgid "info.base.page_url_label"
 msgstr "Page URL"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:55
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:56
 msgid "info.base.page_policy_label"
 msgstr "Active policy"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:69
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70
 msgid "info.base.more_config_options_label"
 msgstr "Configure"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:77
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:78
 msgid "info.base.this_site_script_blocking_button"
 msgstr "JS blocking on this site"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:80
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:81
 msgid "info.base.this_site_payload_button"
 msgstr "Payload for this site"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:83
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:84
 msgid "info.base.this_page_script_blocking_button"
 msgstr "JS blocking on this page"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:86
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:87
 msgid "info.base.this_page_payload_button"
 msgstr "Payload for this page"
 
@@ -431,6 +431,165 @@ msgstr ""
 "scripts. This is, however, an implementation detail and casual users need"
 " not care about it nor understand these nuances."
 
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:23
+msgid "doc.popup.title"
+msgstr "Popup"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:26
+msgid "doc.popup.h_big"
+msgstr "Haketilo popup"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:30
+msgid "doc.popup.intro"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:35
+msgid "doc.popup.h_medium.operating"
+msgstr "Operating"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:38
+msgid "doc.popup.operating.html.opening_{blocking_link}_{packages_link}"
+msgstr ""
+"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 {blocking_link} "
+"or {packages_link} 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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:39
+msgid "doc.popup.operating.opening.blocking_link_text"
+msgstr "rules"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:41
+msgid "doc.popup.operating.opening.packages_link_text"
+msgstr "payloads"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:52
+msgid "doc.popup.operating.html.closing"
+msgstr ""
+"The dialog can be closed by clicking anywhere on the darker area around "
+"it. It can then be reopened by typing \"HKT\" again."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:57
+msgid "doc.popup.h_medium.enabling"
+msgstr "Enabling/disabling"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:60
+msgid "doc.popup.enabling.html.intro"
+msgstr ""
+"Popup is unavailable by default on Haketilo special sites including "
+"<code>https://hkt.mitm.it</code>. It can also be disabled independently "
+"on"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:65
+msgid "doc.popup.enabling.js_allowed_case"
+msgstr "pages with JS allowed,"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:68
+msgid "doc.popup.enabling.js_blocked_case"
+msgstr "pages with JS blocked and"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:71
+msgid "doc.popup.enabling.payload_case"
+msgstr "pages with script payload injected."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:76
+msgid "doc.popup.enabling.html.rest_{settings_link}"
+msgstr ""
+"This can be configured on the {settings_link} and might be useful to "
+"users who are careful about fingerprinting."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:77
+msgid "doc.popup.enabling.html.rest.settings_link_text"
+msgstr "settings page"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:84
+msgid "doc.popup.h_medium.fingerprinting"
+msgstr "Fingerprinting considerations"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:87
+msgid "doc.popup.fingerprinting_intro"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:91
+msgid "doc.popup.fingerprinting_more"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:95
+msgid "doc.popup.fingerprinting_more_more"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:100
+msgid "doc.popup.h_medium.other_caveats"
+msgstr "Other caveats"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:103
+msgid "doc.popup.other_caveats.intro"
+msgstr "Some other potential issues related to the popup are described below."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:108
+msgid "doc.popup.h_small.site_interference"
+msgstr "Interference with the site"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:111
+msgid "doc.popup.site_interference.text"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:116
+msgid "doc.popup.h_small.content_blockers_interference"
+msgstr "Interference with other script-blocking tools"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:119
+msgid "doc.popup.content_blockers_interference.text"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:124
+msgid "doc.popup.h_small.url_mismatch"
+msgstr "URL mismatch"
+
+#: src/hydrilla/proxy/self_doc/popup.html.jinja:127
+#, fuzzy
+msgid "doc.popup.url_mismatch.text"
+msgstr ""
+"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."
+
 #: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:23
 msgid "doc.script_blocking.title"
 msgstr "Script blocking"
@@ -1122,69 +1281,69 @@ msgstr "Prune orphans"
 msgid "web_ui.home.popup_settings_label"
 msgstr "Popup settings"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:210
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:212
 msgid "web_ui.home.configure_popup_settings_on_pages_with"
 msgstr "Configure popup settings on pages with"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:216
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:218
 msgid "web_ui.home.popup_settings_jsallowed_button"
 msgstr "JS allowed"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:217
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:219
 msgid "web_ui.home.popup_settings_jsblocked_button"
 msgstr "JS blocked"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:218
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:220
 msgid "web_ui.home.popup_settings_payloadon_button"
 msgstr "Payload used"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:268
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:270
 msgid "web_ui.home.popup_no_button"
 msgstr "Disable popup"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:271
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:273
 msgid "web_ui.home.popup_yes_button"
 msgstr "Enable popup"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:281
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:283
 msgid "web_ui.home.jsallowed_popup_yes"
 msgstr ""
 "Haketilo currently makes it possible to open its popup window on pages "
 "where native JS has been allowed to execute. This is a convenience that "
 "comes at a price of greater risk of user fingerprinting."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:283
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:285
 msgid "web_ui.home.jsallowed_popup_no"
 msgstr ""
 "Haketilo currently does not make it possible to open its popup window on "
 "pages with their native JS allowed. This setting is less convenient but "
 "decreases the risk of user fingerprinting."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:289
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:291
 msgid "web_ui.home.jsblocked_popup_yes"
 msgstr ""
 "Haketilo currently makes it possible to open its popup window on pages "
 "where native JS has been blocked from executing."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:291
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:293
 msgid "web_ui.home.jsblocked_popup_no"
 msgstr ""
 "Haketilo currently does not make it possible to open its popup window on "
 "pages where native JS has been blocked from executing."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:297
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:299
 msgid "web_ui.home.payloadon_popup_yes"
 msgstr ""
 "Haketilo currently makes it possible to open its popup window on pages "
 "where payload is used."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:299
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:301
 msgid "web_ui.home.payloadon_popup_no"
 msgstr ""
 "Haketilo currently does not make it possible to open its popup window on "
 "pages where payload is used."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:304
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:306
 msgid "web_ui.home.popup_can_be_opened_by"
 msgstr ""
 "When enabled on given page, popup dialog can be opened by typing big "
@@ -1831,15 +1990,15 @@ msgstr "Add rule"
 msgid "web_ui.rules.title"
 msgstr "Script blocking"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja:32
+#: src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja:33
 msgid "web_ui.rules.heading"
 msgstr "Manage script blocking"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja:36
+#: src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja:39
 msgid "web_ui.rules.add_rule_button"
 msgstr "Define new rule"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja:41
+#: src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja:44
 msgid "web_ui.rules.rule_list_heading"
 msgstr "Defined rules"
 
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
index ccdc7c8..9268c92 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
@@ -42,6 +42,7 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block main %}
   <h3>
     {{ _('info.base.heading.page_info') }}
+    {{ hkt_doc_link('popup') }}
   </h3>
 
   {{ label(_('info.base.page_url_label')) }}
diff --git a/src/hydrilla/proxy/self_doc/popup.html.jinja b/src/hydrilla/proxy/self_doc/popup.html.jinja
new file mode 100644
index 0000000..f1a31e9
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/popup.html.jinja
@@ -0,0 +1,130 @@
+{#
+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 %}{{ _('doc.popup.title') }}{% endblock %}
+
+{% block main %}
+  {{ big_heading(_('doc.popup.h_big')) }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      {{ _('doc.popup.intro') }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.popup.h_medium.operating')) }}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.popup.operating.html.opening_{blocking_link}_{packages_link}') %}
+      {% set blocking_link_text = _('doc.popup.operating.opening.blocking_link_text') %}
+      {% set blocking_link = doc_page_link(blocking_link_text|e, 'script_blocking') %}
+      {% set packages_link_text = _('doc.popup.operating.opening.packages_link_text') %}
+      {% set packages_link = doc_page_link(packages_link_text|e, 'packages') %}
+      {{
+        fmt.format(
+            blocking_link = blocking_link,
+            packages_link = packages_link
+        )|safe
+      }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.operating.html.closing')|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.popup.h_medium.enabling')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.enabling.html.intro')|safe }}
+    {% endcall %}
+
+    {% call unordered_list() %}
+      {% call list_entry() %}
+        {{ _('doc.popup.enabling.js_allowed_case') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.popup.enabling.js_blocked_case') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ _('doc.popup.enabling.payload_case') }}
+      {% endcall %}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.popup.enabling.html.rest_{settings_link}') %}
+      {% set link_text = _('doc.popup.enabling.html.rest.settings_link_text') %}
+      {% set link = hkt_link(link_text|e, 'home.home') %}
+      {{ fmt.format(settings_link=link)|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.popup.h_medium.fingerprinting')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.fingerprinting_intro') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.fingerprinting_more') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.fingerprinting_more_more') }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.popup.h_medium.other_caveats')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.other_caveats.intro') }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.popup.h_small.site_interference')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.site_interference.text') }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.popup.h_small.content_blockers_interference')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.content_blockers_interference.text') }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ small_heading(_('doc.popup.h_small.url_mismatch')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.popup.url_mismatch.text')|safe }}
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}
diff --git a/src/hydrilla/proxy/web_ui/templates/index.html.jinja b/src/hydrilla/proxy/web_ui/templates/index.html.jinja
index ff74369..36d9941 100644
--- a/src/hydrilla/proxy/web_ui/templates/index.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/index.html.jinja
@@ -193,7 +193,9 @@ code in a proprietary work, I am not going to enforce this in court.
 
   <div class="horizontal-separator"></div>
 
-  {{ label(_('web_ui.home.popup_settings_label')) }}
+  {% call label(_('web_ui.home.popup_settings_label')) %}
+    {{ hkt_doc_link('popup') }}
+  {% endcall %}
 
   {%
     macro render_popup_settings(