From f2af30f506c9f3ff7c560e4e4af956e1209f27b0 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Thu, 27 Oct 2022 17:26:22 +0200 Subject: [proxy] document script blocking --- .../common_jinja_templates/base.html.jinja | 2 +- src/hydrilla/locales/en_US/LC_MESSAGES/messages.po | 174 ++++++++++++++++++--- .../js_fallback_blocked_info.html.jinja | 1 + .../js_rule_blocked_info.html.jinja | 1 + .../proxy/self_doc/policy_selection.html.jinja | 5 +- .../proxy/self_doc/script_blocking.html.jinja | 103 ++++++++++++ .../proxy/web_ui/templates/rules/index.html.jinja | 5 +- 7 files changed, 268 insertions(+), 23 deletions(-) create mode 100644 src/hydrilla/proxy/self_doc/script_blocking.html.jinja 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() %} -
  • +
  • {{ caller() }}
    • {% 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 \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 " +"https://en.wikipedia.org/***. If we then wanted to make an " +"exception just for the \"List of emoticons\" page, we could create an " +"additional allowing rule with " +"https://en.wikipedia.org/wiki/List_of_emoticons 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 {% 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 {% 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 %} -

    {{ _('web_ui.rules.heading') }}

    +

    + {{ _('web_ui.rules.heading') }} + {{ hkt_doc_link('script_blocking') }} +

    -- cgit v1.2.3