diff options
Diffstat (limited to 'design-documents/039-taler-browser-integration.rst')
| -rw-r--r-- | design-documents/039-taler-browser-integration.rst | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/design-documents/039-taler-browser-integration.rst b/design-documents/039-taler-browser-integration.rst new file mode 100644 index 00000000..980f3f25 --- /dev/null +++ b/design-documents/039-taler-browser-integration.rst @@ -0,0 +1,195 @@ +DD 39: Taler Wallet Browser Integration Considerations +###################################################### + +Summary +======= + +This design document discusses considerations for integrating the GNU Taler +wallet with browsers and highlights difficulties with the implementation of a +GNU Taler wallet as a cross-browser WebExtension. + +Motivation +========== + +GNU Taler is a payment system based on open standards with a free and open +source reference implementation. The GNU Taler wallet is the main component +used by end users to manage their electronic cash balance and payments. + +Payments with GNU Taler are typically initiated via a QR code or link that +contains a ``taler://pay/{merchant}/{order_id}`` URI. Navigating to such a +link should result in a context switch to the wallet, where the payment can can +be approved/declined, and the user is subsequently redirected to the merchant's +website again. + +Other ``taler://`` URIs (for withdrawals, refunds, etc.) are also commonly +used, but not explicitly discussed in this document, as very similar +considerations apply. + +There are multiple reference implementations available for multiple +platforms (command line, Android, iOS, WebExtension). + +While native applications can register themselves as a handler for the +``taler`` URI scheme, the story is different for WebExtensions: There is +currently no reasonable, cross-platform mechanism that allows a WebExtension to +register itself as the handler for the ``taler`` URI scheme. + +This is unfortunate, as a WebExtension could otherwise easily provide a Taler +wallet implementation without requiring the user to install a native App, +providing a better and safer user experience. + +The problems with individual browsers are: + +* Firefox allows specifying ``protocol_handlers`` in the extension manifest. + However, this list only allows schemes with the prefix ``ext+`` and + schemes that are included in an allowlist. The ``taler`` URI scheme + is not part of this list yet. +* Chromium / Google Chrome allows extensions to use the + ``registerProtocolHandler`` API. However, the same allowlist restrictions + apply. Furthermore, the registered protocol scheme is not listed as the + extension's required/optional permissions. Instead, a different permission + prompt is dynamically shown to the user. +* Safari currently neither supports ``registerProtocolHandler`` nor the + ``protocol_handlers`` mechanism. +* Opera does not seem to have any support for WebExtension protocol handlers + either. + +Another issue is that Websites can't easily find out whether a browser +extension handling the ``taler://`` protocol is installed. + +Requirements +============ + +* No vendor lock-in: The integration should not require merchant + Websites to rely on a particular list of extension IDs but instead + any WebExtension to potentially handle ``taler://`` URIs + or other mechanisms that Websites can use to interact with Taler + wallets. +* Security: The integration mechanism should require as few + permissions as possible. +* Ergonomic user experience: As few clicks and permission + prompts as possible should be shown to the user. +* Ergonomic developer experience: The code size and + effort to trigger a Taler payment on a merchant's Website + should be minimized. +* Forward compatibility: The integration mechanism + should work smoothly with future browsers that + have native, built-in support for Taler payments. + +Proposed Solution +================= + +.. 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"> + +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, + without rendering a page that shows the QR code or link. + However, the WebExtension APIs do not allow extensions to + read particular headers without excessive permissions. Furthermore, + more recent versions of Chrome/Chromium do not allow blocking + processing of headers, leading to flickering when the extension + redirects based on the presence of the ``Taler:`` header. + +* Browser and wallet presence detection. Merchants' Websites could include custom + code to detect the browser and/or presence of a Taler WebExtension and show + different instructions to guide the user towards processing the payment or to + show ``ext+taler`` URIs instead of ``taler`` URIs. This is not a viable + solution, as it requires a lot of extra and brittle logic on merchants' + Websites. + +* Always use ``ext+taler`` URIs. This would help with Firefox. + Bad for forward compatibility, as we have already provisionally registered the + ``taler`` URI scheme. + +* Web Payments API: Using the Web Payments API is not possible, because current + browsers do not allow specifying a WebExtension as a handler. Furthermore, + 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 +=========================== + +* **[1]** https://github.com/whatwg/html/issues/8596 +* **[2]** https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/protocol_handlers +* **[3]** https://github.com/ipfs/devgrants/blob/master/targeted-grants/protocol-handler-api-for-browser-extensions.md |