diff options
Diffstat (limited to 'design-documents/039-taler-browser-integration.rst')
| -rw-r--r-- | design-documents/039-taler-browser-integration.rst | 109 |
1 files changed, 81 insertions, 28 deletions
diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst index 71feb1c6..980f3f25 100644 --- a/design-documents/039-taler-browser-integration.rst +++ b/design-documents/039-taler-browser-integration.rst @@ -54,13 +54,7 @@ The problems with individual browsers are: either. Another issue is that Websites can't easily find out whether a browser -extension handling the ``taler://`` protocol is installed. To avoid using this -information for fingerprinting, anchors could provide an alternative ``href`` -in case the main one is not handled, such as: - -.. code:: html - - <a href="taler://pay/..." handler-unavailable-href="https://wallet.taler.net/">...</a> +extension handling the ``taler://`` protocol is installed. Requirements ============ @@ -81,32 +75,87 @@ Requirements should work smoothly with future browsers that have native, built-in support for Taler payments. +Proposed Solution +================= -Alternatives -============ +.. note:: + + As of 2023-01-23, we've decided to go ahead with the approach + described in this section. + +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"> -* JavaScript API: The WebExtension could 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". - -* 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 +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. + +* Future ``window.taler`` injection should be based on user preferences on + sites where the user has explicitly accepted to disclose that is owner of a + Taler wallet. + +Other Alternatives +================== + + * Triggering interactions with the ``taler://`` URI in a ``Taler:`` HTTP header. This approach would allow browsers with native Taler support (or a WebExtension) to handle payment/withdrawal initiations directly, @@ -133,6 +182,10 @@ Alternatives the Web Payments API would not support the withdrawal flow (``taler://withdraw`` URIs). +* Browsers could provide anchor elements with a fallback when the protocol isn't supported, such as + ``<a href="taler://pay/..." handler-unavailable-href="https://wallet.taler.net/">...</a>``. + + Related Work and References =========================== |