1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
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
|
