browser-integration.rst (4520B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 Wallet Browser Integration Manual 10 ################################# 11 12 Websites can advertise Taler actions and explicitly request browser-wallet 13 features without depending on a particular extension identifier. All page 14 integrations are subject to the wallet user's preferences. Websites must 15 retain an ordinary Taler link or another fallback because extension injection 16 and link interception are not available in every browser or navigation path. 17 18 Advertising a Taler action 19 ========================== 20 21 A page can advertise a wallet action in its document head: 22 23 .. code:: html 24 25 <meta name="taler-uri" content="taler://withdraw/bank.example/operation-id"> 26 27 The extension validates the URI before opening or presenting it. The first 28 ``taler-uri`` element in document order is the page's advertised action; an 29 invalid first element is not skipped in favor of a later element. Ordinary 30 Taler links are handled separately when activated. 31 32 When automatic opening is disabled, the extension can expose the current 33 page's validated action through its popup. Metadata inserted, removed, or 34 changed in the document head is observed; the page body is not scanned. 35 36 Requesting browser-wallet features 37 ================================== 38 39 Additional features are requested with a comma-separated list: 40 41 .. code:: html 42 43 <meta name="taler-support" content="uri, callback, api"> 44 45 Tokens are trimmed and compared case-insensitively. Unknown tokens are 46 ignored. Each known feature is independently controlled by the user's wallet 47 settings: 48 49 ``uri`` 50 Handle a primary-button activation of a link whose ``href`` is a recognized 51 Taler action. Pages must retain the Taler URI in ``href`` so that native 52 handlers and copy-link behavior remain available. 53 54 ``callback`` 55 If ``window.talerCallback`` is a function, call it with 56 ``{present: true}`` when the WebExtension becomes available. Callback 57 execution is best-effort. A page must not rely on receiving a later 58 ``present: false`` notification. 59 60 ``api`` 61 Inject the legacy-compatible ``window.taler`` object asynchronously. A 62 compatibility integration that needs to detect injection should also 63 request ``callback`` and wait for it. The object currently has no supported 64 callable methods; new integrations should use ``taler-uri``, the ``uri`` 65 feature, and ``talerCallback`` instead. 66 67 Without ``taler-support``, the page receives no callback or API and its links 68 are not intercepted. Advertising an action with ``taler-uri`` remains 69 independent of these requested features. 70 71 The page API 72 ============ 73 74 The ``api`` feature makes the legacy-compatible ``window.taler`` object 75 available after asynchronous injection. The extension does not overwrite a 76 value owned by the page. There are currently no supported callable methods 77 on this object. Implementation-specific properties are outside the website 78 contract and must be ignored. In particular, the object exposes no wallet 79 RPC, balance, transaction, identity, or storage capability. 80 81 ``window.talerCallback`` is supplied by the website and is separate from the 82 injected object. It is the supported way to learn that requested integration 83 became available; it is not a wallet-provided API method. 84 85 Security and privacy 86 ==================== 87 88 The content script only reads relevant head metadata and user activations; it 89 cannot access wallet-core or wallet data. Requests cross the extension 90 runtime channel, and the background rechecks both the sender and the current 91 preference before acting. Every URI candidate is parsed authoritatively 92 before it is stored or opened. 93 94 The compatibility entry point must be page-accessible and therefore treats 95 all URL input as untrusted. It rejects framing and does not connect to the 96 wallet host or render wallet controls inside a frame. On Chromium, a site 97 that already knows the stable extension identifier may still be able to probe 98 that resource. Disabling callback and API integration prevents the standard 99 presence signals but cannot make the installation undetectable by every 100 browser-specific probing technique. 101 102 Implementation history and rejected alternatives remain recorded in 103 :doc:`../design-documents/039-taler-browser-integration`.