aboutsummaryrefslogtreecommitdiff
path: root/src/hydrilla
diff options
context:
space:
mode:
authorWojtek Kosior <koszko@koszko.org>2022-10-27 17:26:22 +0200
committerWojtek Kosior <koszko@koszko.org>2022-10-27 17:26:22 +0200
commitf2af30f506c9f3ff7c560e4e4af956e1209f27b0 (patch)
tree25fd1e30a9727bbd93d6c3e260364a4d043b91e7 /src/hydrilla
parent728fcad5e498ac26b108383d7117ad59ad029fd3 (diff)
downloadhaketilo-hydrilla-f2af30f506c9f3ff7c560e4e4af956e1209f27b0.tar.gz
haketilo-hydrilla-f2af30f506c9f3ff7c560e4e4af956e1209f27b0.zip
[proxy] document script blocking
Diffstat (limited to 'src/hydrilla')
-rw-r--r--src/hydrilla/common_jinja_templates/base.html.jinja2
-rw-r--r--src/hydrilla/locales/en_US/LC_MESSAGES/messages.po174
-rw-r--r--src/hydrilla/proxy/policies/info_pages_templates/js_fallback_blocked_info.html.jinja1
-rw-r--r--src/hydrilla/proxy/policies/info_pages_templates/js_rule_blocked_info.html.jinja1
-rw-r--r--src/hydrilla/proxy/self_doc/policy_selection.html.jinja5
-rw-r--r--src/hydrilla/proxy/self_doc/script_blocking.html.jinja103
-rw-r--r--src/hydrilla/proxy/web_ui/templates/rules/index.html.jinja5
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">