commit f96cbe0e106947f21ae5f7463934288173f54f83
parent 03f3b96138999431f117c4fec5001c43c8ae5665
Author: Florian Dold <florian@dold.me>
Date: Mon, 7 Sep 2026 11:26:27 +0200
DD103
Diffstat:
2 files changed, 96 insertions(+), 0 deletions(-)
diff --git a/design-documents/103-https-wallet-links.rst b/design-documents/103-https-wallet-links.rst
@@ -0,0 +1,95 @@
+DD 103: HTTPS Links for Wallet Actions
+######################################
+
+:Design status: Draft
+:Implementation status: Not started
+:DD shepherd: Florian Dold
+:Historical contributors: Florian Dold
+:First published: 2026-09-07
+:Last substantive change: 2026-09-07
+
+Summary
+=======
+
+This design document proposes using ``https://`` URLs as a fallback for ``taler://`` URIs.
+
+Motivation
+==========
+
+Some users of the Taler wallet have reported that applications they use
+don't support ``taler://`` URIs nicely. Some applications don't render them correctly,
+linking only the second part (after the ``taler://``) as a link, which then
+usually leads them to an invalid page.
+
+Requirements
+============
+
+* The solution should still allow alternative implementations of the wallet
+ not provided by the Taler project.
+
+Proposed Solution
+=================
+
+In addition to ``taler://`` URIs, wallets also register themselves as handlers
+for ``https://wallet.taler.net/#``. The taler action is provided
+after the ``#``. These ``https://`` URLs are directly
+mapped to ``taler://`` URIs and interpreted by the wallet:
+
+The following URLs
+
+* ``https://wallet.taler.net/#taler://${action}/${rest}``
+* ``https://wallet.taler.net/#/${action}/${rest}``
+* ``https://wallet.taler.net/#${action}/${rest}``
+
+are all mapped to ``taler://${action}/${rest}``.
+
+
+Security Considerations
+=======================
+
+* Since the payload of the encoded Taler action is in the fragment of the ``https://``
+ URL, navigating to the URL does not send any data from the Taler action
+ to the server.
+* If ``https:/wallet.taler.net/`` is compromised, an attacker
+ can intercept ``taler://`` URIs on a devices that does **not**
+ already have a wallet installed.
+* Using ``https://wallet.taler.net/`` links consistently on Websites would
+ allow the WebExtension wallet to run with considerably less broad
+ permissions.
+
+Ecosystem Considerations
+========================
+
+* We can allow developers of alternative Taler wallets
+ to register themselves on Android / iOS.
+* For F-Droid, packages are signed with the F-Droid key anyway, so allowing
+ this key to handle ``https://wallet.taler.net/`` would allow alternative
+ Taler wallet implementations on F-Droid automatically.
+
+Alternatives
+============
+
+* Push for widespread adoption of ``taler://`` URI support.
+
+ * That's what would happen in an ideal world, and we should still
+ push for it.
+
+* Use the domain of exchanges to encode Taler actions, e.g. ``https://exchange.taler-ops.ch/#pay/...``.
+
+ * This requires trusting *more* servers
+ * It leads to an ``NxM`` issues where ``N`` wallets would
+ need to apply at ``M`` exchanges to be allowed to register
+ as a handler for their URL.
+
+Discussion / Q&A
+================
+
+* Why use ``https://wallet.taler.net/``?
+
+ * The link is easily recognizeable as a link for the Taler wallet.
+
+ * When no wallet is installed, this is exactly the location we want the user
+ to be navigated to, as it asks the user to install a wallet
+
+ * Since ``wallet.taler.net`` is owned by the Taler project and links to the
+ wallets, they can be considered part of the same trust domain.
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -116,4 +116,5 @@ documents. The lifecycle metadata in each document is authoritative. See
100-shares
101-semantic-token-families
102-systemd-service-restart-policy
+ 103-https-wallet-links
999-template
