diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/hydrilla/locales/en_US/LC_MESSAGES/messages.po | 704 | ||||
| -rw-r--r-- | src/hydrilla/proxy/self_doc/packages.html.jinja | 41 | ||||
| -rw-r--r-- | src/hydrilla/proxy/self_doc/policy_selection.html.jinja | 73 | ||||
| -rw-r--r-- | src/hydrilla/proxy/self_doc/popup.html.jinja | 101 | ||||
| -rw-r--r-- | src/hydrilla/proxy/self_doc/script_blocking.html.jinja | 92 | ||||
| -rw-r--r-- | src/hydrilla/proxy/self_doc/url_patterns.html.jinja | 181 | ||||
| -rw-r--r-- | src/hydrilla/proxy/web_ui/root.py | 13 |
7 files changed, 362 insertions, 843 deletions
diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po index 7f6760e..7f22ea3 100644 --- a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po +++ b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po @@ -1,20 +1,13 @@ -# SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 +# SPDX-License-Identifier: CC0-1.0 # English translations for Hydrilla&Haketilo. # -# This file is part of Hydrilla&Haketilo. # Copyright (C) 2021-2022 Wojtek Kosior <koszko@koszko.org> -# 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. +# Available under the terms of Creative Commons Zero v1.0 Universal. msgid "" msgstr "" "Project-Id-Version: hydrilla 2.0\n" "Report-Msgid-Bugs-To: koszko@koszko.org\n" -"POT-Creation-Date: 2022-10-27 19:46+0200\n" +"POT-Creation-Date: 2022-10-28 11:58+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,697 +312,6 @@ 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:23 -msgid "doc.policy_selection.title" -msgstr "Policy selection" - -#: 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: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: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: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: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.html.block_js_case.blocking_link_text" -msgstr "blocking" - -#: 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:55 -msgid "doc.policy_selection.h_medium.precedence" -msgstr "Policy precedence" - -#: 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 " -"-allowing rules and by adding and enabling packages. Each rule and each " -"package payload has a {patterns_link}. This pattern determined which " -"pages the policy is compatible with. Patterns also have well-defined " -"specificity. When multiple rules and packages are combatible with given " -"page's URL, the one with the most specific pattern \"wins\". In case of a" -" tie, payload injection is assumed to take precedence over rule " -"application." - -#: 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:65 -msgid "doc.policy_selection.html.precedence_nonenabled_{settings_link}" -msgstr "" -"In the absence of suitable rules and enabled packages, Haketilo may " -"consider non-enabled packages that are suitable for use on the currently-" -"visited site. It will either inject package payload automatically, ask " -"the user whether to enable the package or ignore it completely. The user " -"can switch between these 3 behaviors on the Haketilo {settings_link}. " -"Packages that were explicitly marked as disabled will always be ignored. " -"Pattern specificity is also taken into account in case of multiple " -"packages." - -#: 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:72 -msgid "doc.policy_selection.html.precedence_fallback_{settings_link}" -msgstr "" -"When absolutely no explicit policy appears suitable for given page, " -"Haketilo will apply its default script handling behavrior. Whether " -"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:73 -msgid "doc.policy_selection.precedence_fallback.settings_link_text" -msgstr "settings page" - -#: 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:83 -msgid "doc.policy_selection.special_cases.html.exepmt_and_error" -msgstr "" -"The sites served by Haketilo itself are exempt from all policies. These " -"are <code>http://hkt.mitm.it</code>, <code>https://hkt.mitm.it</code> and" -" <code>http://mitm.it</code>. Additionally, if Haketilo experiences an " -"internal error (e.g. because it could not parse current URL as sent in by" -" the browser), it will try to block page's JavaScript as a security " -"measure." - -#: 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 " -"files used by payloads and for making its APIs accessible to payload " -"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" - -#: 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" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:26 -msgid "doc.url_patterns.h_big" -msgstr "URL patterns" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:30 -msgid "doc.url_patterns.html.intro" -msgstr "" -"We want to be able to apply different rules and custom scripts for " -"different websites. However, merely specifying \"do this for all " -"documents under <code>https://example.com</code>\" is not enough. Single " -"site's pages might differ strongly and require different custom scripts " -"to be loaded. Always matching against a full URL like " -"<code>https://example.com/something/somethingelse</code> is also not a " -"good option. It doesn't allow us to properly handle a site that serves " -"similar pages for multiple values substituted for " -"<code>somethingelse</code>." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:35 -msgid "doc.url_patterns.h_medium.employed_solution" -msgstr "Employed solution" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:38 -msgid "doc.url_patterns.html.wildcards_intro" -msgstr "" -"Wildcards are being used to address the problem. Each payload and rule in" -" Haketilo has a URL pattern that specifies to which internet pages it " -"applies. A URL pattern can be as as simple as literal URL in which case " -"it only matches itself. It can also contain wildcards in the form of one " -"or more asterisks (<code>*</code>) that correspond to multiple possible " -"strings occurring in that place." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:42 -msgid "doc.url_patterns.html.wildcards_types_introduced" -msgstr "" -"Wildcards can appear in URL's domain and path that follows it. These 2 " -"types of wildcards are handled separately." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:47 -msgid "doc.url_patterns.h_small.domain_wildcards" -msgstr "Domain wildcards" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:50 -msgid "doc.url_patterns.html.domain_wildcards_intro" -msgstr "" -"A domain wildcard takes the form of one, two or three asterisks occurring" -" in place of a single domain name segment at the beginning (left). " -"Depending on the number of asterisks, the meaning is as follows" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:55 -msgid "doc.url_patterns.html.domain_no_asterisks_example" -msgstr "" -"no asterisks (e.g. <code>example.com</code>) - match domain name exactly " -"(e.g. <code>example.com</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:58 -msgid "doc.url_patterns.html.domain_one_asterisk_example" -msgstr "" -"one asterisk (e.g. <code>*.example.com</code>) - match all domains " -"resulting from substituting <code>*</code> with a <span " -"class=\"bold\">single</span> segment (e.g. " -"<code>banana.example.com</code> or <code>pineapple.example.com</code> but" -" <span class=\"bold\">not</span> <code>pineapple.pen.example.com</code> " -"nor <code>example.com</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:61 -msgid "doc.url_patterns.html.domain_two_asterisks_example" -msgstr "" -"two asterisks (e.g. <code>**.example.com</code>) - match all domains " -"resulting from substituting <code>**</code> with <span class=\"bold\">two" -" or more</span> segments (e.g. <code>monad.breakfast.example.com</code> " -"or <code>pure.monad.breakfast.example.com</code> but <span " -"class=\"bold\">not</span> <code>cabalhell.example.com</code> nor " -"<code>example.com</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:64 -msgid "doc.url_patterns.html.domain_three_asterisks_example" -msgstr "" -"three asterisks (e.g. <code>***.example.com</code>) - match all domains " -"resulting from substituting <code>***</code> with <span " -"class=\"bold\">zero or more</span> segments (e.g. " -"<code>hello.parkmeter.example.com</code> or " -"<code>iliketrains.example.com</code> or <code>example.com</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:70 -msgid "doc.url_patterns.h_small.path_wildcards" -msgstr "Path wildcards" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:73 -msgid "doc.url_patterns.html.path_wildcards_intro" -msgstr "" -"A path wildcard takes the form of one, two or three asterisks occurring " -"in place of a single path segment at the end of path (right). Depending " -"on the number of asterisks, the meaning is as follows" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:78 -msgid "doc.url_patterns.html.path_no_asterisks_example" -msgstr "" -"no asterisks (e.g. <code>/joke/clowns</code>) - match path exactly (e.g. " -"<code>/joke/clowns</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:81 -msgid "doc.url_patterns.html.path_one_asterisk_example" -msgstr "" -"one asterisk (e.g. <code>/itscalled/*</code>) - match all paths resulting" -" from substituting <code>*</code> with a <span " -"class=\"bold\">single</span> segment (e.g. " -"<code>/itscalled/gnulinux</code> or <code>/itscalled/glamp</code> but " -"<span class=\"bold\">not</span> <code>/itscalled/</code> nor " -"<code>/itscalled/gnu/linux</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:84 -msgid "doc.url_patterns.html.path_two_asterisks_example" -msgstr "" -"two asterisks (e.g. <code>/another/**</code>) - match all paths resulting" -" from substituting <code>**</code> with <span class=\"bold\">two or " -"more</span> segments (e.g. <code>/another/nsa/backdoor</code> or " -"<code>/another/best/programming/language</code> but <span " -"class=\"bold\">not</span> <code>/another/apibreak</code> nor " -"<code>/another</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:87 -msgid "doc.url_patterns.html.path_three_asterisks_example" -msgstr "" -"three asterisks (e.g. <code>/mail/dmarc/***</code>) - match all paths " -"resulting from substituting <code>***</code> with <span " -"class=\"bold\">zero or more</span> segments (e.g. " -"<code>/mail/dmarc/spf</code>, <code>/mail/dmarc</code> or " -"<code>/mail/dmarc/dkim/failure</code> but <span class=\"bold\">not</span>" -" <code>/mail/</code>)" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:92 -msgid "doc.url_patterns.html.path_trailing_slash" -msgstr "" -"If pattern ends <span class=\"bold\">without</span> a trailing slash, it " -"mathes paths with any number of trailing slashes, including zero. If " -"pattern ends <span class=\"bold\">with</span> a trailing slash, it only " -"mathes paths with one or more trailing slashes. For example, " -"<code>/itscalled/*</code> matches <code>/itscalled/gnulinux</code>, " -"<code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code> " -"while <code>/itscalled/*/</code> only matches " -"<code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code> " -"out of those three." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:96 -msgid "doc.url_patterns.html.path_trailing_slash_priority" -msgstr "" -"If two patterns only differ by the presence of a trailing slash, pattern " -"<span class=\"bold\">with</span> a trailing slash is considered <span " -"class=\"bold\">more specific</span>." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:100 -msgid "doc.url_patterns.html.path_literal_trailing_asterisks" -msgstr "" -"Additionally, any path with literal trailing asterisks is matched by " -"itself, even if such pattern would otherwise be treated as wildcard (e.g." -" <code>/gobacktoxul/**</code> matches <code>/gobacktoxul/**</code>). This" -" is likely to change in the future and would best not be relied upon. " -"Appending three additional asterisks to path pattern to represent literal" -" asterisks is being considered." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:105 -msgid "doc.url_patterns.h_small.protocol_wildcards" -msgstr "URL scheme wildcard" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:108 -msgid "doc.url_patterns.html.protocol_wildcards" -msgstr "" -"<code>http://</code> and <code>https://</code> shemes in the URL are " -"matched exactly. However, starting with Haketilo 3.0, it is also possible" -" for scheme pseudo-wildcard of <code>http*://</code> to be used. Use of " -"URL pattern with this scheme is equivalent to the use of 2 separate " -"patterns starting with <code>http://</code> and <code>https://</code>, " -"respectively. For example, pattern <code>http*://example.com</code> shall" -" match both <code>https://example.com</code> and " -"<code>http://example.com</code>." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:112 -msgid "doc.url_patterns.html.protocol_wildcards_are_aliases" -msgstr "" -"<code>http*://</code> may be considered not to be a true wildcard but " -"rather an alias for either of the other 2 values. As of Haketilo 3.0, the" -" speicificity of a URL pattern starting with <code>http*://</code> is " -"considered to be the same as that of the corresponding URL pattern " -"starting with <code>http://</code> or <code>https://</code>. In case of a" -" conflict, the order of precedence of such patterns is unspecified. This " -"behavior is likely to change in the future versions of Haketilo." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:117 -msgid "doc.url_patterns.h_small.wildcard_priorities" -msgstr "Wildcard pattern priorities and querying" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:120 -msgid "doc.url_patterns.priorities_intro" -msgstr "" -"In case multiple patterns match some URL, the more specific one is " -"preferred. Specificity is considered as follows" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:125 -msgid "doc.url_patterns.priorities_rule_path_ending" -msgstr "" -"If patterns only differ in the final path segment, the one with least " -"wildcard asterisks in that segment if preferred." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:128 -msgid "doc.url_patterns.priorities_rule_path_length" -msgstr "" -"If patterns, besides the above, only differ in path length, one with " -"longer path is preferred. Neither final wildcard segment nor trailing " -"dashes account for path length." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:131 -msgid "doc.url_patterns.priorities_rule_domain_beginning" -msgstr "" -"If patterns, besides the above, only differ in the initial domain " -"segment, one with least wildcard asterisks in that segment is preferred." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:134 -#, fuzzy -msgid "doc.url_patterns.priorities_rule_domain_length" -msgstr "" -"If patterns differ in domain length, one with longer domain is preferred." -" Initial wildcard segment does not account for domain length." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:139 -msgid "doc.url_patterns.html.priorities_example1_intro" -msgstr "" -"As an example, consider the URL " -"<code>http://settings.query.example.com/google/tries/destroy/adblockers//</code>." -" Patterns matching it are, in the following order" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:266 -msgid "doc.url_patterns.html.priorities_example1_note" -msgstr "" -"Variants of those patterns starting with <code>http*://</code> would of " -"course match as well. They have been omitted for simplicity." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:270 -msgid "doc.url_patterns.html.priorities_example2_intro" -msgstr "" -"For a simpler URL like <code>https://example.com</code> the patterns " -"would be" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:281 -msgid "doc.url_patterns.html.priorities_example2_note" -msgstr "" -"Variants of those patterns with a trailing dash added would <span " -"class=\"bold\">not</span> match the URL. Also, the pattern variants " -"starting with <code>http*://</code> have been once again omitted." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:286 -msgid "doc.url_patterns.h_small.limits" -msgstr "Limits" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:289 -msgid "doc.url_patterns.limits" -msgstr "" -"In order to prevent some easy-to-conduct DoS attacks, older versions of " -"Haketilo and Hydrilla limited the lengths of domain and path parts of " -"processed URLs. This is no longer the case." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:294 -msgid "doc.url_patterns.h_medium.alt_solution" -msgstr "Alternative solution idea: mimicking web server mechanics" - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:297 -msgid "doc.url_patterns.url_pattern_drawbacks" -msgstr "" -"While wildcard patterns as presented give a lot of flexibility, they are " -"not the only viable approach to specifying what URLs to apply " -"rules/payloads to. In fact, wildcards are different from how the server " -"side of a typical website decides what to return for a given URL request." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:301 -msgid "doc.url_patterns.server_behavior_mimicking_idea" -msgstr "" -"In a typical scenario, an HTTP server like Apache reads configuration " -"files provided by its administrator and uses various (virtual host, " -"redirect, request rewrite, CGI, etc.) instructions to decide how to " -"handle given URL. Perhps using a scheme that mimics the configuration " -"options typically used with web servers would give more efficiency in " -"specifying what page settings to apply when." - -#: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:305 -msgid "doc.url_patterns.approach_may_be_considered" -msgstr "This approach may be considered in the future." - #: src/hydrilla/proxy/state_impl/concrete_state.py:111 msgid "err.proxy.unknown_db_schema" msgstr "" diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja new file mode 100644 index 0000000..a9bedc5 --- /dev/null +++ b/src/hydrilla/proxy/self_doc/packages.html.jinja @@ -0,0 +1,41 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Documentation page describing the concept of packages in Haketilo. + +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 %} Packages {% endblock %} + +{% block main %} + {{ big_heading('Packages in Haketilo') }} + + {% call section() %} + {% call paragraph() %} + blah blah + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading('blah blah') }} + + {% call paragraph() %} + more blah blah... + {% endcall %} + {% endcall %} +{% endblock main %} diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja index 4d9b251..687d2bd 100644 --- a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja +++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja @@ -20,71 +20,90 @@ code in a proprietary work, I am not going to enforce this in court. #} {% extends "doc_base.html.jinja" %} -{% block title %}{{ _('doc.policy_selection.title') }}{% endblock %} +{% block title %} Policy selection {% endblock %} {% block main %} - {{ big_heading(_('doc.policy_selection.h_big')) }} + {{ big_heading('Page policy selection') }} {% call section() %} {% call paragraph() %} - {{ _('doc.policy_selection.intro') }} + When a web page is opened, Haketilo is capable of either {% call unordered_list() %} {% call list_entry() %} - {{ _('doc.policy_selection.enabled_payload_case') }} + blocking page's own scripts and + {{ doc_page_link('injecting payload', 'packages') }} + configured by the user, {% endcall %} {% call list_entry() %} - {{ _('doc.policy_selection.auto_payload_case') }} + blocking page's own scripts and injecting an automatically-chosen + payload that is usable with the page, {% endcall %} {% call list_entry() %} - {{ _('doc.policy_selection.ask_payload_case') }} + presenting a dialog asking whether to enable an automatically-chosen + payload that is usable with the page, {% endcall %} {% call list_entry() %} - {% 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 }} + {{ doc_page_link('blocking', 'script_blocking') }} page's own scripts + or {% endcall %} {% call list_entry() %} - {{ _('doc.policy_selection.allow_js_case') }} + allowing page's own scripts to execute normally (i.e. not modifying + the page in any meaningful way). {% endcall %} {% endcall %} {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.policy_selection.h_medium.precedence')) }} + {{ medium_heading('Policy precedence') }} {% call paragraph() %} - {% set fmt = _('doc.policy_selection.html.precedence_general_{patterns_link}') %} - {% set link_text = _('doc.policy_selection.precedence_general.patterns_link_text') %} - {% set link = doc_page_link(link_text|e, 'url_patterns') %} - {{ fmt.format(patterns_link=link)|safe }} + User configures Haketilo's behavior by defining script-blocking and + -allowing rules and by adding and enabling packages. Each rule and each + package payload has a {{ doc_page_link('URL pattern', 'url_patterns') }}. + This pattern determines which pages the policy is compatible with. + Patterns also have well-defined specificity. When multiple rules and + packages are combatible with given page's URL, the one with the most + specific pattern "wins". In case of a tie, payload injection is assumed to + take precedence over rule application. {% endcall %} {% call paragraph() %} - {% set fmt = _('doc.policy_selection.html.precedence_nonenabled_{settings_link}') %} - {% set link_text = _('doc.policy_selection.precedence_nonenabled.settings_link_text') %} - {% set link = hkt_link(link_text|e, 'home.home') %} - {{ fmt.format(settings_link=link)|safe }} + In the absence of suitable rules and enabled packages, Haketilo may + consider non-enabled packages that are suitable for use on the + currently-visited site. It will either inject package payload + automatically, ask the user whether to enable the package or ignore it + completely. The user can switch between these 3 behaviors on the Haketilo + {{ hkt_link('settings page', 'home.home') }}. Packages that were + explicitly marked as disabled will always be ignored. Pattern specificity + is also taken into account in case of multiple packages. {% endcall %} {% call paragraph() %} - {% set fmt = _('doc.policy_selection.html.precedence_fallback_{settings_link}') %} - {% set link_text = _('doc.policy_selection.precedence_fallback.settings_link_text') %} - {% set link = hkt_link(link_text|e, 'home.home') %} - {{ fmt.format(settings_link=link)|safe }} + When absolutely no explicit policy appears suitable for given page, + Haketilo will apply its default script handling behavrior. Whether + JavaScript is blocked or allowed by default is also determined by user's + choice on the {{ hkt_link('settings page', 'home.home') }}. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.policy_selection.special_cases.h_medium')) }} + {{ medium_heading('Special cases') }} {% call paragraph() %} - {{ _('doc.policy_selection.special_cases.html.exepmt_and_error')|safe }} + The sites served by Haketilo itself are exempt from all policies. These + are <code>http://hkt.mitm.it</code>, <code>https://hkt.mitm.it</code> + and <code>http://mitm.it</code>. Additionally, if Haketilo experiences an + internal error (e.g. because it could not parse current URL as sent in by + the browser), it will try to block page's JavaScript as a security + measure. {% endcall %} {% call paragraph() %} - {{ _('doc.policy_selection.special_cases.internal_policies') }} + Internally, Haketilo also has a special high-priority policy for serving + files used by payloads and for making its APIs accessible to payload + scripts. This is, however, an implementation detail and casual users need + not care about it nor understand these nuances. {% endcall %} {% endcall %} {% endblock main %} diff --git a/src/hydrilla/proxy/self_doc/popup.html.jinja b/src/hydrilla/proxy/self_doc/popup.html.jinja index f1a31e9..a5ad909 100644 --- a/src/hydrilla/proxy/self_doc/popup.html.jinja +++ b/src/hydrilla/proxy/self_doc/popup.html.jinja @@ -20,111 +20,138 @@ 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 title %} Popup {% endblock %} {% block main %} - {{ big_heading(_('doc.popup.h_big')) }} + {{ big_heading('Haketilo popup') }} {% call section() %} {% call paragraph() %} - {{ _('doc.popup.intro') }} + 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. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.popup.h_medium.operating')) }} + {{ medium_heading('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 - }} + 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 + {{ doc_page_link('rules', 'script_blocking') }} or + {{ doc_page_link('payloads', 'packages') }} 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. {% endcall %} {% call paragraph() %} - {{ _('doc.popup.operating.html.closing')|safe }} + The dialog can be closed by clicking anywhere on the darker area around + it. It can then be reopened by typing "HKT" again. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.popup.h_medium.enabling')) }} + {{ medium_heading('Enabling/disabling') }} {% call paragraph() %} - {{ _('doc.popup.enabling.html.intro')|safe }} + Popup is unavailable by default on Haketilo special sites including + <code>https://hkt.mitm.it</code>. It can also be disabled independently on {% endcall %} {% call unordered_list() %} {% call list_entry() %} - {{ _('doc.popup.enabling.js_allowed_case') }} + pages with JS allowed, {% endcall %} {% call list_entry() %} - {{ _('doc.popup.enabling.js_blocked_case') }} + pages with JS blocked and {% endcall %} {% call list_entry() %} - {{ _('doc.popup.enabling.payload_case') }} + pages with script payload injected. {% 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 }} + This can be configured on the {{ hkt_link('setings page', 'home.home') }} + and might be useful to users who are careful about fingerprinting. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.popup.h_medium.fingerprinting')) }} + {{ medium_heading('Fingerprinting considerations') }} {% call paragraph() %} - {{ _('doc.popup.fingerprinting_intro') }} + 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. {% endcall %} {% call paragraph() %} - {{ _('doc.popup.fingerprinting_more') }} + 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. {% endcall %} {% call paragraph() %} - {{ _('doc.popup.fingerprinting_more_more') }} + 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. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.popup.h_medium.other_caveats')) }} + {{ medium_heading('Other caveats') }} {% call paragraph() %} - {{ _('doc.popup.other_caveats.intro') }} + Some other potential issues related to the popup are described below. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.popup.h_small.site_interference')) }} + {{ small_heading('Interference with the site') }} {% call paragraph() %} - {{ _('doc.popup.site_interference.text') }} + 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. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.popup.h_small.content_blockers_interference')) }} + {{ small_heading('Interference with other script-blocking tools') }} {% call paragraph() %} - {{ _('doc.popup.content_blockers_interference.text') }} + 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. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.popup.h_small.url_mismatch')) }} + {{ small_heading('URL mismatch') }} {% call paragraph() %} - {{ _('doc.popup.url_mismatch.text')|safe }} + 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. {% endcall %} {% endcall %} {% endblock main %} diff --git a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja index 63b647e..c0a5275 100644 --- a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja +++ b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja @@ -20,84 +20,106 @@ 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 title %} Script blocking {% endblock %} {% block main %} - {{ big_heading(_('doc.script_blocking.h_big')) }} + {{ big_heading('Script blocking in Haketilo') }} {% call section() %} {% call paragraph() %} - {{ _('doc.script_blocking.intro') }} + 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. {% 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 }} + Besides the casual script-blocking discussed here, Haketilo also blocks + page's JavaScript when injecting the user-specified + {{ doc_page_link('script payloads', 'packages') }}. That functionality is + described on its own documentation page. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.script_blocking.h_medium.configuring')) }} + {{ medium_heading('Configuring script blocking') }} {% 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') %} + User can {{ - fmt.format( - rules_link = rules_link, - patterns_link = patterns_link, - policy_link = policy_link - )|safe + hkt_link('define script-blocking and -allowing rules', 'rules.rules') }} + using {{ doc_page_link('URL patterns', 'url_patterns') }}. 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 + {{ doc_page_link('policy selection page', 'policy_selection') }}. {% endcall %} {% call paragraph() %} - {{ _('doc.script_blocking.configuring.html.rules_example')|safe }} + 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. {% 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 }} + It is also possible to configure whether scripts should be blocked by + dafault on pages where no explicit rule and no payload is used. The + relevant option can be found on Haketilo + {{ hkt_link('settings page', 'home.home') }}. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.script_blocking.medium_h.with_other_tools')) }} + {{ medium_heading('Use with other script-blocking tools') }} {% call paragraph() %} - {{ _('doc.script_blocking.with_other_tools.haketilo_independently') }} + 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. {% 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 }} + 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 + {{ doc_page_link('popup', 'popup') }}). {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.script_blocking.medium_h.technical')) }} + {{ medium_heading('Technical details') }} {% call paragraph() %} - {{ _('doc.script_blocking.technical.general') }} + 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. {% endcall %} {% call paragraph() %} - {{ _('doc.script_blocking.technical.means_no_reports') }} + 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. {% endcall %} {% call paragraph() %} - {{ _('doc.script_blocking.technical.popup_script') }} + 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. {% endcall %} {% endcall %} {% endblock main %} diff --git a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja index 7d2718f..f3415c5 100644 --- a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja +++ b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja @@ -20,123 +20,210 @@ code in a proprietary work, I am not going to enforce this in court. #} {% extends "doc_base.html.jinja" %} -{% block title %}{{ _('doc.url_patterns.title') }}{% endblock %} +{% block title %} URL patterns {% endblock %} {% block main %} - {{ big_heading(_('doc.url_patterns.h_big')) }} + {{ big_heading('Haketio URL patterns') }} {% call section() %} {% call paragraph() %} - {{ _('doc.url_patterns.html.intro')|safe }} + We want to be able to apply different rules and custom scripts for + different websites. However, merely specifying "do this for all documents + under <code>https://example.com</code>" is not enough. Single site's pages + might differ strongly and require different custom scripts to be + loaded. Always matching against a full URL like + <code>https://example.com/something/somethingelse</code> is also not + a good option. It doesn't allow us to properly handle a site that serves + similar pages for multiple values substituted for + <code>somethingelse</code>. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.url_patterns.h_medium.employed_solution')) }} + {{ medium_heading('Employed solution') }} {% call paragraph() %} - {{ _('doc.url_patterns.html.wildcards_intro')|safe }} + Wildcards are being used to address the problem. Each payload and rule in + Haketilo has a URL pattern that specifies to which internet pages it + applies. A URL pattern can be as as simple as literal URL in which case it + only matches itself. It can also contain wildcards in the form of one or + more asterisks (<code>*</code>) that correspond to multiple possible + strings occurring in that place. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.wildcards_types_introduced')|safe }} + Wildcards can appear in URL's domain and path that follows it. These 2 + types of wildcards are handled separately. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.url_patterns.h_small.domain_wildcards')) }} + {{ small_heading('Domain wildcards') }} {% call paragraph() %} - {{ _('doc.url_patterns.html.domain_wildcards_intro')|safe }} + A domain wildcard takes the form of one, two or three asterisks occurring + in place of a single domain name segment at the beginning + (left). Depending on the number of asterisks, the meaning is as follows {% endcall %} {% call unordered_list() %} {% call list_entry() %} - {{ _('doc.url_patterns.html.domain_no_asterisks_example')|safe }} + no asterisks (e.g. <code>example.com</code>) - match domain name exactly + (e.g. <code>example.com</code>) {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.html.domain_one_asterisk_example')|safe }} + one asterisk (e.g. <code>*.example.com</code>) - match all domains + resulting from substituting <code>*</code> with a + <span class="bold">single</span> segment (e.g. + <code>banana.example.com</code> or <code>pineapple.example.com</code> + but <span class="bold">not</span> <code>pineapple.pen.example.com</code> + nor <code>example.com</code>) {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.html.domain_two_asterisks_example')|safe }} + two asterisks (e.g. <code>**.example.com</code>) - match all domains + resulting from substituting <code>**</code> with + <span class="bold">two or more</span> segments (e.g. + <code>monad.breakfast.example.com</code> or + <code>pure.monad.breakfast.example.com</code> but + <span class="bold">not</span> <code>cabalhell.example.com</code> nor + <code>example.com</code>) {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.html.domain_three_asterisks_example')|safe }} + three asterisks (e.g. <code>***.example.com</code>) - match all domains + resulting from substituting <code>***</code> with + <span class="bold">zero or more</span> segments (e.g. + <code>hello.parkmeter.example.com</code> or + <code>iliketrains.example.com</code> or <code>example.com</code>) {% endcall %} {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.url_patterns.h_small.path_wildcards')) }} + {{ small_heading('Path wildcards') }} {% call paragraph() %} - {{ _('doc.url_patterns.html.path_wildcards_intro')|safe }} + A path wildcard takes the form of one, two or three asterisks occurring in + place of a single path segment at the end of path (right). Depending on + the number of asterisks, the meaning is as follows {% endcall %} {% call unordered_list() %} {% call list_entry() %} - {{ _('doc.url_patterns.html.path_no_asterisks_example')|safe }} + no asterisks (e.g. <code>/joke/clowns</code>) - match path exactly (e.g. + <code>/joke/clowns</code>) {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.html.path_one_asterisk_example')|safe }} + one asterisk (e.g. <code>/itscalled/*</code>) - match all paths + resulting from substituting <code>*</code> with a + <span class="bold">single</span> segment (e.g. + <code>/itscalled/gnulinux</code> or <code>/itscalled/glamp</code> but + <span class="bold">not</span> <code>/itscalled/</code> nor + <code>/itscalled/gnu/linux</code>) {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.html.path_two_asterisks_example')|safe }} + two asterisks (e.g. <code>/another/**</code>) - match all paths + resulting from substituting <code>**</code> with + <span class="bold">two or more</span> segments (e.g. + <code>/another/nsa/backdoor</code> or + <code>/another/best/programming/language</code> but + <span class="bold">not</span> <code>/another/apibreak</code> nor + <code>/another</code>) {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.html.path_three_asterisks_example')|safe }} + three asterisks (e.g. <code>/mail/dmarc/***</code>) - match all paths + resulting from substituting <code>***</code> with + <span class="bold">zero or more</span> segments (e.g. + <code>/mail/dmarc/spf</code>, <code>/mail/dmarc</code> or + <code>/mail/dmarc/dkim/failure</code> but + <span class="bold">not</span> <code>/mail/</code>) {% endcall %} {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.path_trailing_slash')|safe }} + If pattern ends <span class="bold">without</span> a trailing slash, it + mathes paths with any number of trailing slashes, including zero. If + pattern ends <span class="bold">with</span> a trailing slash, it only + mathes paths with one or more trailing slashes. For example, + <code>/itscalled/*</code> matches <code>/itscalled/gnulinux</code>, + <code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code> + while <code>/itscalled/*/</code> only matches + <code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code> + out of those three. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.path_trailing_slash_priority')|safe }} + If two patterns only differ by the presence of a trailing slash, + pattern <span class="bold">with</span> a trailing slash is considered + <span class="bold">more specific</span>. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.path_literal_trailing_asterisks')|safe }} + Additionally, any path with literal trailing asterisks is matched by + itself, even if such pattern would otherwise be treated as wildcard + (e.g. <code>/gobacktoxul/**</code> matches <code>/gobacktoxul/**</code>). + This is likely to change in the future and would best not be relied upon. + Appending three additional asterisks to path pattern to represent literal + asterisks is being considered. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.url_patterns.h_small.protocol_wildcards')) }} + {{ small_heading('URL scheme wildcard') }} {% call paragraph() %} - {{ _('doc.url_patterns.html.protocol_wildcards')|safe }} + <code>http://</code> and <code>https://</code> shemes in the URL are + matched exactly. However, starting with Haketilo 3.0, it is also possible + for scheme pseudo-wildcard of <code>http*://</code> to be used. Use of URL + pattern with this scheme is equivalent to the use of 2 separate patterns + starting with <code>http://</code> and <code>https://</code>, + respectively. For example, pattern <code>http*://example.com</code> shall + match both <code>https://example.com</code> and + <code>http://example.com</code>. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.protocol_wildcards_are_aliases')|safe }} + <code>http*://</code> may be considered not to be a true wildcard but + rather an alias for either of the other 2 values. As of Haketilo 3.0, the + speicificity of a URL pattern starting with <code>http*://</code> is + considered to be the same as that of the corresponding URL pattern + starting with <code>http://</code> or <code>https://</code>. In case of a + conflict, the order of precedence of such patterns is unspecified. This + behavior is likely to change in the future versions of Haketilo. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.url_patterns.h_small.wildcard_priorities')) }} + {{ small_heading('Wildcard pattern priorities and querying') }} {% call paragraph() %} - {{ _('doc.url_patterns.priorities_intro') }} + In case multiple patterns match some URL, the more specific one is + preferred. Specificity is considered as follows {% endcall %} {% call unordered_list() %} {% call list_entry() %} - {{ _('doc.url_patterns.priorities_rule_path_ending')|safe }} + If patterns only differ in the final path segment, the one with least + wildcard asterisks in that segment if preferred. {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.priorities_rule_path_length')|safe }} + If patterns, besides the above, only differ in path length, one with + longer path is preferred. Neither final wildcard segment nor trailing + dashes account for path length. {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.priorities_rule_domain_beginning')|safe }} + If patterns, besides the above, only differ in the initial domain + segment, one with least wildcard asterisks in that segment is preferred. {% endcall %} {% call list_entry() %} - {{ _('doc.url_patterns.priorities_rule_domain_length')|safe }} + If patterns differ in domain length, one with longer domain is + preferred. Initial wildcard segment does not account for domain length. {% endcall %} {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.priorities_example1_intro')|safe }} + As an example, consider the URL + <code>http://settings.query.example.com/google/tries/destroy/adblockers//</code>. + Patterns matching it are, in the following order {% endcall %} {% call verbatim() %} @@ -263,11 +350,13 @@ http://***.example.com/*** {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.priorities_example1_note')|safe }} + Variants of those patterns starting with <code>http*://</code> would of + course match as well. They have been omitted for simplicity. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.priorities_example2_intro')|safe }} + For a simpler URL like <code>https://example.com</code> the patterns would + be {% endcall %} {% call verbatim() %} @@ -278,31 +367,43 @@ https://***.example.com/*** {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.html.priorities_example2_note')|safe }} + Variants of those patterns with a trailing dash added + would <span class="bold">not</span> match the URL. Also, the pattern + variants starting with <code>http*://</code> have been once again omitted. {% endcall %} {% endcall %} {% call section() %} - {{ small_heading(_('doc.url_patterns.h_small.limits')) }} + {{ small_heading('Limits') }} {% call paragraph() %} - {{ _('doc.url_patterns.limits')|safe }} + In order to prevent some easy-to-conduct DoS attacks, older versions of + Haketilo and Hydrilla limited the lengths of domain and path parts of + processed URLs. This is no longer the case. {% endcall %} {% endcall %} {% call section() %} - {{ medium_heading(_('doc.url_patterns.h_medium.alt_solution')) }} + {{ medium_heading('Alternative solution idea: mimicking web server mechanics') }} {% call paragraph() %} - {{ _('doc.url_patterns.url_pattern_drawbacks') }} + While wildcard patterns as presented give a lot of flexibility, they are + not the only viable approach to specifying what URLs to apply + rules/payloads to. In fact, wildcards are different from how the server + side of a typical website decides what to return for a given URL request. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.server_behavior_mimicking_idea') }} + In a typical scenario, an HTTP server like Apache reads configuration + files provided by its administrator and uses various (virtual host, + redirect, request rewrite, CGI, etc.) instructions to decide how to handle + given URL. Perhps using a scheme that mimics the configuration options + typically used with web servers would give more efficiency in specifying + what page settings to apply when. {% endcall %} {% call paragraph() %} - {{ _('doc.url_patterns.approach_may_be_considered') }} + This approach may be considered in the future. {% endcall %} {% endcall %} {% endblock main %} diff --git a/src/hydrilla/proxy/web_ui/root.py b/src/hydrilla/proxy/web_ui/root.py index 917c063..4eea860 100644 --- a/src/hydrilla/proxy/web_ui/root.py +++ b/src/hydrilla/proxy/web_ui/root.py @@ -45,7 +45,7 @@ import jinja2 import flask import werkzeug -from ...translations import translation as make_translation +from ... import translations from ... import versions from ... import item_infos from ... import common_jinja_templates @@ -188,8 +188,14 @@ def home_doc(page: str) -> str: if page not in self_doc.page_names: flask.abort(404) + locale = translations.select_best_locale() + if locale == translations.default_locale: + prefix = '' + else: + prefix = f'{locale}/' + return flask.render_template( - f'{page}.html.jinja', + f'{prefix}{page}.html.jinja', doc_output = 'html_hkt_mitm_it' ) @@ -239,7 +245,8 @@ def process_request( with app._haketilo_app_lock: app._haketilo_state = state - app.jinja_env.install_gettext_translations(make_translation()) + best_translations = translations.translation() + app.jinja_env.install_gettext_translations(best_translations) flask_response = app.test_client().open( path = path, |