[proxy] document script blocking

1 files changed, 154 insertions, 20 deletions

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"