[proxy] document policy selection

1 files changed, 118 insertions, 10 deletions

diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
index 2b922ed..c6426fa 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-26 16:03+0200\n"
+"POT-Creation-Date: 2022-10-27 14:02+0200\n"
 "PO-Revision-Date: 2022-02-12 00:00+0000\n"
 "Last-Translator: Wojtek Kosior <koszko@koszko.org>\n"
 "Language: en_US\n"
@@ -220,39 +220,39 @@ msgstr ""
 "\n"
 "{}"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:34
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:39
 msgid "info.base.title"
 msgstr "Page info"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:39
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:44
 msgid "info.base.heading.page_info"
 msgstr "Haketilo page handling details"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:42
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:47
 msgid "info.base.page_url_label"
 msgstr "Page URL"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:50
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:55
 msgid "info.base.page_policy_label"
 msgstr "Active policy"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:62
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:69
 msgid "info.base.more_config_options_label"
 msgstr "Configure"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:77
 msgid "info.base.this_site_script_blocking_button"
 msgstr "JS blocking on this site"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:73
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:80
 msgid "info.base.this_site_payload_button"
 msgstr "Payload for this site"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:76
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:83
 msgid "info.base.this_page_script_blocking_button"
 msgstr "JS blocking on this page"
 
-#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:79
+#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:86
 msgid "info.base.this_page_payload_button"
 msgstr "Payload for this page"
 
@@ -319,6 +319,114 @@ 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
+msgid "doc.policy_selection.title"
+msgstr "Policy selection"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:27
+msgid "doc.policy_selection.h_big"
+msgstr "Page policy selection"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:31
+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
+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
+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
+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:43
+msgid "doc.policy_selection.block_js_case"
+msgstr "blocking page's own scripts or"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:46
+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
+msgid "doc.policy_selection.h_medium.precedence"
+msgstr "Policy precedence"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:56
+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:57
+msgid "doc.policy_selection.precedence_general.patterns_link_text"
+msgstr "URL pattern"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:63
+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:64
+msgid "doc.policy_selection.precedence_nonenabled.settings_link_text"
+msgstr "settings page"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:70
+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:71
+msgid "doc.policy_selection.precedence_fallback.settings_link_text"
+msgstr "settings page"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:78
+msgid "doc.policy_selection.special_cases.h_medium"
+msgstr "Special cases"
+
+#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:81
+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:85
+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/url_patterns.html.jinja:23
 msgid "doc.url_patterns.title"
 msgstr "URL patterns"