[proxy] document policy selection

7 files changed, 234 insertions, 16 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"
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
index 0785039..ccdc7c8 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
@@ -20,6 +20,11 @@ code in a proprietary work, I am not going to enforce this in court.
 #}
 {% extends "base.html.jinja" %}
 
+{% macro hkt_doc_link(page_name) %}
+  {% set doc_url = 'https://hkt.mitm.it/doc/' ~ page_name %}
+  {{ doc_link(doc_url) }}
+{% endmacro %}
+
 {% block style %}
   {{ super() }}
 
@@ -47,7 +52,9 @@ code in a proprietary work, I am not going to enforce this in court.
 
   <div class="horizontal-separator"></div>
 
-  {{ label(_('info.base.page_policy_label')) }}
+  {% call label(_('info.base.page_policy_label')) %}
+    {{ hkt_doc_link('policy_selection') }}
+  {% endcall %}
 
   <p class="has-colored-links">
     {% block site_policy required %}{% endblock %}
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja
index b808827..1c0c662 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja
@@ -29,7 +29,9 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block main_rest %}
   <div class="horizontal-separator"></div>
 
-  {{ label(_('info.rule.matched_pattern_label')) }}
+  {% call label(_('info.rule.matched_pattern_label')) %}
+    {{ hkt_doc_link('url_patterns') }}
+  {% endcall %}
 
   <p>
     {{ pattern }}
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja
index a71ca25..e66e685 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja
@@ -40,7 +40,9 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block main_rest %}
   <div class="horizontal-separator"></div>
 
-  {{ label(_('info.payload.matched_pattern_label')) }}
+  {% call label(_('info.payload.matched_pattern_label')) %}
+    {{ hkt_doc_link('url_patterns') }}
+  {% endcall %}
 
   <p>
     {{ payload_data.pattern }}
diff --git a/src/hydrilla/proxy/self_doc.py b/src/hydrilla/proxy/self_doc.py
index a1a2485..ccf0e12 100644
--- a/src/hydrilla/proxy/self_doc.py
+++ b/src/hydrilla/proxy/self_doc.py
@@ -8,4 +8,4 @@ import jinja2
 
 loader = jinja2.PackageLoader(__package__, package_path='self_doc')
 
-page_names = {'url_patterns'}
+page_names = {'url_patterns', 'policy_selection'}
diff --git a/src/hydrilla/proxy/self_doc/doc_base.html.jinja b/src/hydrilla/proxy/self_doc/doc_base.html.jinja
index 7982142..71842f2 100644
--- a/src/hydrilla/proxy/self_doc/doc_base.html.jinja
+++ b/src/hydrilla/proxy/self_doc/doc_base.html.jinja
@@ -36,8 +36,20 @@ code in a proprietary work, I am not going to enforce this in court.
   {{ caller()|safe }}
 {% endmacro %}
 
-{% macro link(where, text) -%}
-  <a href="{{ where }}">{{ text }}</a>
+{% macro doc_page_link(text, page_name) -%}
+  {% if doc_output == 'html_hkt_mitm_it' -%}
+    <a href="{{ url_for('.home_doc', page=page_name) }}">{{ text }}</a>
+  {%- else -%}
+    <a href="{{ page_name ~ '.html' }}">{{ text }}</a>
+  {%- endif %}
+{%- endmacro %}
+
+{% macro hkt_link(text, endpoint_name) -%}
+  {% if doc_output == 'html_hkt_mitm_it' -%}
+    <a href="{{ url_for(endpoint_name, **kwargs) }}">{{ text }}</a>
+  {%- else -%}
+    {{ text }}
+  {%- endif %}
 {%- endmacro %}
 
 {% macro paragraph() %}
diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
new file mode 100644
index 0000000..6519e42
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
@@ -0,0 +1,87 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing how Haketilo selects policy to apply to a page.
+
+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.policy_selection.title') }}{% endblock %}
+
+{% block main %}
+  {{ big_heading(_('doc.policy_selection.h_big')) }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      {{ _('doc.policy_selection.intro') }}
+      {% call unordered_list() %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.enabled_payload_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.auto_payload_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.ask_payload_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.block_js_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.allow_js_case') }}
+        {% endcall %}
+      {% endcall %}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.policy_selection.h_medium.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 }}
+    {% 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 }}
+    {% 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 }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.policy_selection.special_cases.h_medium')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.policy_selection.special_cases.html.exepmt_and_error')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.policy_selection.special_cases.internal_policies') }}
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}