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 ```` 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:: To enable additional communication features between a website and the GNU Taler Wallet webextension, the page must include the following meta tag: .. code:: where ``$features`` is a comma-separated list of features. The following features are supported: * ``uri`` will hijack anchor elements (````) 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 ``...``. 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