dd39: expand on proposed solution

1 files changed, 61 insertions, 31 deletions

diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst
index 2ca24de4..029ca6d4 100644
--- a/design-documents/039-taler-browser-integration.rst
+++ b/design-documents/039-taler-browser-integration.rst
@@ -89,38 +89,68 @@ Proposed Solution
    As of 2023-01-23, we've decided to go ahead with the approach
    described in this section.
 
-Now
-^^^
-
-* Handling ``taler://`` URIs by overriding the onclick handler of ``a`` HTML elements.
-  This requires excessive permissions but would be a viable work-around,
-  at least on pages that opt in with a special ``<meta name="taler-support" content="uri">`` tag.
-  It does not work in all use-cases, for example when a navigation
-  to a ``taler://`` URI is initiated programmatically or by pasting
-  the URI in the browser's address bar.
-
-* Handling a ``taler://`` URI by putting it directly in a meta tag that causes the
-  wallet to get triggered *on page load*.
-
-
-Future (post-1.0)
-^^^^^^^^^^^^^^^^^
-
-* JavaScript API: The WebExtension can inject a JavaScript API into Websites
-  that allow interacting with the Taler wallet.  This is the approach taken by
-  the MetaMask crypto wallet.  It requires excessive permissions, may break
-  some Websites (https://github.com/brave/browser-laptop/issues/13711) and
-  requires merchants to include extra JavaScript.
-
-  * This type of interaction is useful for Single Page Apps and
-    might be provided by the GNU Taler wallet reference implementation,
-    at least when the user grants additional permissions.
-  * Unfortunately, browsers currently do not provide a safe way
-    for the communication between a WebExtension and the page
-    without excessive permissions.  This especially applies
-    if the Website does not know the extension's ID. Hard-coding
-    the extension IDs would violate the "no vendor lock-in requirement".
+Overview
+^^^^^^^^
 
+The following integration approaches between Websites and the Taler Wallet webextension
+are provided:
+
+1. Directly triggering a ``taler://...`` URI on page load (via a meta tag).
+2. Overriding ``<a href="taler://..." onclick=...>`` tags to trigger the wallet.
+   The onclick handler (which must call preventDefault) can implement behavior
+   that happens only when the webextension is not available.
+3. Future (possibly post-1.0): A ``window.taler`` JavaScript API that is injected
+   into every page that requests it via a meta tag.  This is useful for SPAs that
+   want to programmatically trigger the Taler wallet.
+
+
+Usage
+^^^^^
+
+To directly trigger the handling of a ``taler://`` URI on page load, the following meta tag can be used:
+
+.. code::
+
+   <meta name="taler-uri" content="taler://...">
+
+
+To enable additional communication features between a website and the GNU Taler Wallet webextension, the page must
+include the following meta tag:
+
+.. code::
+  
+  <meta name="taler-support" content="$features">
+
+where ``$features`` is a comma-separated list of features.
+
+The following features are supported:
+
+* ``uri`` will hijack anchor elements (``<a href="taler://..." onclick=...>``) and replace their onclick handler
+  with a different handler that lets the webexension wallet handle the ``taler://`` URI.
+* (future): ``api`` will inject the ``window.taler`` API into the page
+
+
+Caveats and Comments
+^^^^^^^^^^^^^^^^^^^^
+
+* Anchor tag hijacking does not work in all use-cases, for example when a navigation
+to a ``taler://`` URI is initiated programmatically or by pasting
+the URI in the browser's address bar.
+
+* The ``window.taler`` API injection may break some websites
+  (https://github.com/brave/browser-laptop/issues/13711).
+
+* All these approaches require excessive permissions,  as unfortunately,
+  browsers currently do not provide a safe way for the communication between a
+  WebExtension and the page without excessive permissions.  This especially
+  applies if the Website does not know the extension's ID. Hard-coding the
+  extension IDs would violate the "no vendor lock-in requirement".
+
+* A neat feature of the anchor hijacking is that the ``taler://`` URI can be always be copied
+  in the browser (via "copy link address").  Clicking the link always results in either:
+  * The native URI handler, if no Taler Wallet webextension is installed and no onclick handler is defined
+  * The execution of the websites onclick handler if no Taler Wallet webextension is installed
+  * Triggering the webextension wallet to handle the ``taler://`` URI.