[proxy] document script blocking

7 files changed, 268 insertions, 23 deletions

diff --git a/src/hydrilla/common_jinja_templates/base.html.jinja b/src/hydrilla/common_jinja_templates/base.html.jinja
index cdaffe3..c4d288b 100644
--- a/src/hydrilla/common_jinja_templates/base.html.jinja
+++ b/src/hydrilla/common_jinja_templates/base.html.jinja
@@ -114,7 +114,7 @@ code in a proprietary work, I am not going to enforce this in court.
 {% endmacro %}
 
 {% macro list_entry() %}
-  <li>
+  <li class="has-colored-links">
     {{ caller() }}
   </li>
 {% endmacro %}
diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
index c6426fa..983a5e8 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 14:02+0200\n"
+"POT-Creation-Date: 2022-10-27 17:22+0200\n"
 "PO-Revision-Date: 2022-02-12 00:00+0000\n"
 "Last-Translator: Wojtek Kosior <koszko@koszko.org>\n"
 "Language: en_US\n"
@@ -319,49 +319,53 @@ msgstr "Requested file could not be found."
 msgid "api.resource_not_enabled_for_access"
 msgstr "Requested resource is not enabled for access."
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:24
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:23
 msgid "doc.policy_selection.title"
 msgstr "Policy selection"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:27
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:26
 msgid "doc.policy_selection.h_big"
 msgstr "Page policy selection"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:31
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:30
 msgid "doc.policy_selection.intro"
 msgstr "When a web page is opened, Haketilo is capable of either"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:34
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:33
 msgid "doc.policy_selection.enabled_payload_case"
 msgstr "blocking page's own scripts and injecting payload configured by the user,"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:37
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:36
 msgid "doc.policy_selection.auto_payload_case"
 msgstr ""
 "blocking page's own scripts and injecting an automatically-chosen payload"
 " that is usable with the page,"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:40
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:39
 msgid "doc.policy_selection.ask_payload_case"
 msgstr ""
 "presenting a dialog asking whether to enable an automatically-chosen "
 "payload that is usable with the page,"
 
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:42
+msgid "doc.policy_selection.block_js_case_{blocking_link}"
+msgstr "{blocking_link} page's own scripts or"
+
 #: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:43
-msgid "doc.policy_selection.block_js_case"
-msgstr "blocking page's own scripts or"
+msgid "doc.policy_selection.html.block_js_case.blocking_link_text"
+msgstr "blocking"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:46
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:48
 msgid "doc.policy_selection.allow_js_case"
 msgstr ""
 "allowing page's own scripts to execute normally (i.e. not modifying the "
 "page in any meaningful way)."
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:53
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:55
 msgid "doc.policy_selection.h_medium.precedence"
 msgstr "Policy precedence"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:56
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:58
 msgid "doc.policy_selection.html.precedence_general_{patterns_link}"
 msgstr ""
 "User configures Haketilo's behavior by defining script-blocking and "
@@ -373,11 +377,11 @@ msgstr ""
 " tie, payload injection is assumed to take precedence over rule "
 "application."
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:57
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:59
 msgid "doc.policy_selection.precedence_general.patterns_link_text"
 msgstr "URL pattern"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:63
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:65
 msgid "doc.policy_selection.html.precedence_nonenabled_{settings_link}"
 msgstr ""
 "In the absence of suitable rules and enabled packages, Haketilo may "
@@ -389,11 +393,11 @@ msgstr ""
 "Pattern specificity is also taken into account in case of multiple "
 "packages."
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:64
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:66
 msgid "doc.policy_selection.precedence_nonenabled.settings_link_text"
 msgstr "settings page"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:70
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:72
 msgid "doc.policy_selection.html.precedence_fallback_{settings_link}"
 msgstr ""
 "When absolutely no explicit policy appears suitable for given page, "
@@ -401,15 +405,15 @@ msgstr ""
 "JavaScript is blocked or allowed by default is also determined by user's "
 "choice on the {settings_link}."
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:71
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:73
 msgid "doc.policy_selection.precedence_fallback.settings_link_text"
 msgstr "settings page"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:78
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:80
 msgid "doc.policy_selection.special_cases.h_medium"
 msgstr "Special cases"
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:81
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:83
 msgid "doc.policy_selection.special_cases.html.exepmt_and_error"
 msgstr ""
 "The sites served by Haketilo itself are exempt from all policies. These "
@@ -419,7 +423,7 @@ msgstr ""
 " the browser), it will try to block page's JavaScript as a security "
 "measure."
 
-#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:85
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:87
 msgid "doc.policy_selection.special_cases.internal_policies"
 msgstr ""
 "Internally, Haketilo also has a special high-priority policy for serving "
@@ -427,6 +431,136 @@ 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/script_blocking.html.jinja:23
+msgid "doc.script_blocking.title"
+msgstr "Script blocking"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:26
+msgid "doc.script_blocking.h_big"
+msgstr "Script blocking in Haketilo"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:30
+msgid "doc.script_blocking.intro"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:34
+msgid "doc.script_blocking.html.see_here_for_{packages_link}"
+msgstr ""
+"Besides the casual script-blocking discussed here, Haketilo also blocks "
+"page's JavaScript when injecting the user-specified {packages_link}. That"
+" functionality is described on its own documentation page."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:35
+msgid "doc.script_blocking.see_here_for.packages_link_text"
+msgstr "script payloads"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:42
+msgid "doc.script_blocking.h_medium.configuring"
+msgstr "Configuring script blocking"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:45
+msgid "doc.script_blocking.configuring.html.rules_{rules_link}_{patterns_link}_{policy_link}"
+msgstr ""
+"User can {rules_link} using {patterns_link}. 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 {policy_link}."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:46
+msgid "doc.script_blocking.configuring.rules.rules_link_text"
+msgstr "define script-blocking and -allowing rules"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:48
+msgid "doc.script_blocking.configuring.rules.patterns_link_text"
+msgstr "URL patterns"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:50
+msgid "doc.script_blocking.configuring.rules.policy_link_text"
+msgstr "policy selection page"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:62
+msgid "doc.script_blocking.configuring.html.rules_example"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:66
+msgid "doc.script_blocking.configuring.html.fallback_{settings_link}"
+msgstr ""
+"It is also possible to configure whether scripts should be blocked by "
+"dafault on pages when no explicit rule and no payload is used. The "
+"relevant option is found on Haketilo {settings_link}"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:67
+msgid "doc.script_blocking.configuring.html.fallback.settings_link_text"
+msgstr "settings page"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:74
+msgid "doc.script_blocking.medium_h.with_other_tools"
+msgstr "Use with other script-blocking tools"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:77
+msgid "doc.script_blocking.with_other_tools.haketilo_independently"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:81
+msgid "doc.script_blocking.with_other_tools.html.breakages_{popup_link}"
+msgstr ""
+"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 {popup_link})."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:82
+msgid "doc.script_blocking.with_other_tools.breakages.popup_link_text"
+msgstr "popup"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:89
+msgid "doc.script_blocking.medium_h.technical"
+msgstr "Technical means"
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:92
+msgid "doc.script_blocking.technical.general"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:96
+msgid "doc.script_blocking.technical.means_no_reports"
+msgstr ""
+"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."
+
+#: src/hydrilla/proxy/self_doc/script_blocking.html.jinja:100
+msgid "doc.script_blocking.technical.popup_script"
+msgstr ""
+"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."
+
 #: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:23
 msgid "doc.url_patterns.title"
 msgstr "URL patterns"
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_fallback_blocked_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_fallback_blocked_info.html.jinja
index 3e8719a..1b4ad51 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/js_fallback_blocked_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/js_fallback_blocked_info.html.jinja
@@ -11,4 +11,5 @@ Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
 
 {% block site_policy %}
   {{ _('info.js_fallback_blocked') }}
+  {{ hkt_doc_link('script_blocking') }}
 {% endblock %}
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_blocked_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_blocked_info.html.jinja
index e84d371..3f396a8 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_blocked_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_blocked_info.html.jinja
@@ -11,4 +11,5 @@ Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
 
 {% block site_policy %}
   {{ format_html_with_rule_url(_('info.js_blocked.html.rule{url}_is_used')) }}
+  {{ hkt_doc_link('script_blocking') }}
 {% endblock %}
diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
index 6519e42..4d9b251 100644
--- a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
+++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
@@ -39,7 +39,10 @@ code in a proprietary work, I am not going to enforce this in court.
           {{ _('doc.policy_selection.ask_payload_case') }}
         {% endcall %}
         {% call list_entry() %}
-          {{ _('doc.policy_selection.block_js_case') }}
+          {% set fmt = _('doc.policy_selection.block_js_case_{blocking_link}') %}
+          {% set link_text = _('doc.policy_selection.html.block_js_case.blocking_link_text') %}
+          {% set link = doc_page_link(link_text|e, 'script_blocking') %}
+          {{ fmt.format(blocking_link=link)|safe }}
         {% endcall %}
         {% call list_entry() %}
           {{ _('doc.policy_selection.allow_js_case') }}
diff --git a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
new file mode 100644
index 0000000..63b647e
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
@@ -0,0 +1,103 @@
+{#
+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 %}{{ _('doc.script_blocking.title') }}{% endblock %}
+
+{% block main %}
+  {{ big_heading(_('doc.script_blocking.h_big')) }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      {{ _('doc.script_blocking.intro') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.script_blocking.html.see_here_for_{packages_link}') %}
+      {% set link_text = _('doc.script_blocking.see_here_for.packages_link_text') %}
+      {% set link = doc_page_link(link_text|e, 'packages') %}
+      {{ fmt.format(packages_link=link)|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.script_blocking.h_medium.configuring')) }}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.script_blocking.configuring.html.rules_{rules_link}_{patterns_link}_{policy_link}') %}
+      {% set rules_link_text = _('doc.script_blocking.configuring.rules.rules_link_text') %}
+      {% set rules_link = hkt_link(rules_link_text|e, 'rules.rules') %}
+      {% set patterns_link_text = _('doc.script_blocking.configuring.rules.patterns_link_text') %}
+      {% set patterns_link = doc_page_link(patterns_link_text|e, 'url_patterns') %}
+      {% set policy_link_text = _('doc.script_blocking.configuring.rules.policy_link_text') %}
+      {% set policy_link = doc_page_link(policy_link_text|e, 'policy_selection') %}
+      {{
+        fmt.format(
+            rules_link    = rules_link,
+            patterns_link = patterns_link,
+            policy_link   = policy_link
+        )|safe
+      }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.script_blocking.configuring.html.rules_example')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.script_blocking.configuring.html.fallback_{settings_link}') %}
+      {% set link_text = _('doc.script_blocking.configuring.html.fallback.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.script_blocking.medium_h.with_other_tools')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.script_blocking.with_other_tools.haketilo_independently') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.script_blocking.with_other_tools.html.breakages_{popup_link}') %}
+      {% set link_text = _('doc.script_blocking.with_other_tools.breakages.popup_link_text') %}
+      {% set link = doc_page_link(link_text|e, 'popup') %}
+      {{ fmt.format(popup_link=link)|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.script_blocking.medium_h.technical')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.script_blocking.technical.general') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.script_blocking.technical.means_no_reports') }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.script_blocking.technical.popup_script') }}
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}
diff --git a/src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja b/src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja
index 57cc8ad..d5d1d07 100644
--- a/src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja
@@ -29,7 +29,10 @@ code in a proprietary work, I am not going to enforce this in court.
 {% endblock %}
 
 {% block main %}
-  <h3>{{ _('web_ui.rules.heading') }}</h3>
+  <h3>
+    {{ _('web_ui.rules.heading') }}
+    {{ hkt_doc_link('script_blocking') }}
+  </h3>
 
   <a href="{{ url_for('.add_rule') }}"
      class="green-button block-with-bottom-margin">