taler-docs

070-alias-directory-mailbox.rst (14785B)

---

 DD 70: Alias Lookup and Mailbox
 ###############################
 
 :Design status: Accepted
 :Implementation status: Partial
 :DD shepherd: TBD
 :Historical contributors: Martin Schanzenbach
 :First published: 2025-09-19
 :Last substantive change: 2025-11-10
 :Implementation evidence: ``taler-typescript-core`` (2025-11-07; 2026-07-14; 2026-07-16; 2026-08-20)
 :Normative references: ``core/api-mailbox.rst`` and ``core/mailbox/get-H_MAILBOX.rst``
 
 Summary
 =======
 
 GNU Taler is a payment system that makes privacy-contactly online transactions
 fast and easy.
 This project will facilitate the support of peer-to-peer payments (P2P) for the
 GNU Taler payment system between users by implementing a privacy-contactly
 directory service and lightweight inbox service (TALer DIRectory).
 The services will allow users to securely associate their
 online identities (such as email addresses, phone numbers, X/Twitter/Mastodon handles or other suitable verifiable addresses and accounts) with their wallet
 public keys and the URL of an inbox service and use it for P2P payments.
 Storage and retrieval may also be offloaded to distributed directory services
 such as DNS or GNS (RFC 9498) instead of a database
 and web service while maintaining the respective privacy guarantees.
 
 Motivation
 ==========
 
 The Digital Euro is currently in development and as a part of it the
 so-called "Alias Lookup Service" is being developed for at least
 28 Millon Euros (Tender "PRO-009485").
 
 To enable peer-to-peer payments for the GNU Taler payment system
 between users such a directory service and lightweight inbox service are also required.
 We believe that the estimated development costs from the ECB tender
 are unreasonably and unexplicably high. We can demostrate how an efficient,
 privacy-contactly and lean service that offers this kind of functionality can be
 developed within this proposal at a fraction of the cost of the
 "Alias Lookup Service":
 
 The directory service will allow users to securely associate their
 online identities (such as email addresses, phone numbers, X/Twitter/Mastodon handles or other suitable verifiable addresses and accounts) with their wallet
 public keys and the URL of an inbox service.
 Additionally we found that storage and retrieval may also be offloaded to distributed directory services such as DNS or GNS (RFC 9498) instead of a database
 and web service while maintaining the respective privacy guarantees.
 We have added such a task to the estimate.
 
 In order to facilitate fund transfers in the P2P context, we
 will extend the Taler wallet (in particular, the browser-based
 WebExtension) to allow users to associate the wallet with one or more
 (wallet) addresses, to query the directory to send money or invoices, to
 encrypt the payment messages to the public key obtained from the
 directory, to transmit the message via the lightweight inbox service,
 and to poll the inbox service for incoming requests and show them to
 the user.
 Both the key directory service and the inbox service may provide their
 services for a fee to compensate the operator for operational costs
 including the validation of addresses.
 
 Requirements
 ============
 
 The implementation must take great care to ensure the privacy and
 integrity of the mappings from the identity to the wallet keys.
 For this, plain text identity information such as email addresses should
 only be processed as part of the validation and registration processes.
 The actual mappings will be indexed using salted hashes.
 
 Queries for wallet keys also should require the caller to provide the
 already hashed identity to minimize data leakage from requests.
 
 This minimizes the handling of personally identifyable information (PII)
 at the service and limits exposure in case of data leaks at the operator.
 
 The service must be suitable to be operated at very high availability constraints.
 As such, the service must be scalable and ideally have a small footprint and
 computing base.
 
 User Stories
 ============
 
 Both the Mailbox server URI and the Taldir server URI have hard-coded defaults that can be overriden in expert settings.
 In the user stories, we use the placeholders ``$MAILBOX_SERVER`` and
 ``$TALDIR_SERVER`` for those URIs.
 
 Alias Registration
 ------------------
 
   Prerequisites: Alice has installed Taler Wallet
 
 Alice opens the Taler Wallet and browses to ``Settings -> Aliases``.
 The interface offers registration of any Alias type supported by the Taldir instance through
 a ``+`` button and suitable follow-up screens.
 
   **Technical Note**: Alice registers an Alias with the Mailbox URI that corresponds to her Wallet ID (See also :ref:`Mailbox API <api-mailbox>`). The interface does not require Alice to input the URI manually, the Wallet can synthesize the Mailbox URI from an address: ``$MAILBOX_SERVER/SHA512(WalletPublicKey)``.
 
 
   **Technical Note**: Supported alias types are found in the ``$TALDIR_SERVER/config`` endpoint.
 
 
 Alice chooses an alias type and is then prompted to provide her type-specific alias, e.g. *alice@example.com* would be an alias of type *email*.
 This initiates the Alias validation procedure.
 
   **Technical Note**: This initiates the alias registration flow provided in :ref:`Taldir API <api-taldir>`.
 
 The registration procedure may succeed or fail.
 Alice may retry on failure to register the same Alias.
 Alice may also register other Aliases.
 
 .. _dd-70-us-alias-mgmt:
 
 Alias Management
 ----------------
 
   Prerequisites: Alice has registered one or more aliases
 
 Alice opens ``Settings -> Aliases`` to manage her aliases.
 The UI shows all registered aliases with expiration times.
 The UI allows Alice to delete registrations (or disable auto-renewal) and renew a registration pre-emptively before it expires.
 Alice may use this screen to display a QR code (an ``add-contact`` Taler URI) of her own contact, see also :ref:`Contacts Management <dd-70-us-contacts-mgmt>`.
 
   This may require separation into two or three stories.
 
 Send Payment Request
 --------------------
 
   Prerequisites: Bob has installed Taler Wallet, Bob knows one of Alice's aliases
 
 Bob wants to request money from Alice.
 He opens his Taler wallet and opens ``Taler Button->Receive`` screen from the menu.
 A screen that allows to create a payment request is shown to Bob.
 Once Bob has entered all necessary details, a payment request (:ref:`DD 13 <dd-13>`) is
 created and the screen with QR code is shown.
 This screen now also allows to send the request to a contact by using the contact list.
 The *Request from Contact* screen brings up the contacts list to select a contact.
 (Optional): Bob may also import a contact here ad-hoc, see :ref:`Contacts Management <dd-70-us-contacts-mgmt>`.
 Bob selects the contact and the request is sent to Alice.
 
   **Technical Note**: This will trigger the wallet to send the payment request to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`.
 
 The request may fail, for example if Alice's Mailbox is full.
 
   **Note**: Sending messages via Mailbox API may incur fees.
 
 
 Receive Payment Request
 -----------------------
 
   Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias, Bob has sent a payment request.
 
   **Technical Note**: The Wallet periodically checks Mailboxes using the :ref:`Mailbox API <api-mailbox>` for new payment requests and downloads the messages locally. Remote messages are deleted after download.
 
 
 The new payment request by Bob is received by the Wallet and it notifies Alice.
 
   **Technical Note**: Notice request is *NEW*. This requires requests to have unique IDs. Also, maybe notifications should happen even if the ID is already seen, but the message is new.
 
 Alice interacts with the notification or manually browses to ``Settings->Mailbox``.
 
 There, the wallet provides a screen with payment request overviews (e.g. list of messages
 in the local mailbox).
 Alice selects Bob's payment request either through the notification or from the list
 of payment requests.
 The messages contain Taler URIs, so the application may simply offer to process the respective
 URI as is usually done.
 
   **Note**: When are local messages deleted?
 
 .. _dd-70-us-contacts-mgmt:
 
 Contacts Management
 -------------------
 
   Prerequisites: Alice has installed Taler Wallet
 
 Alice opens ``Settings->Contacts``.
 The list of contacts is empty in the beggining.
 There is a button to *Add a contact* which opens a UI.
 The UI consists of a search input and an Alias type selector.
 Alice selects the Alias type (e.g. GitHub or Email) and inputs a contacts Alias.
 
   **Technical Note**: This will initiate a lookup request using the :ref:`Taldir API <api-taldir>`.
 
 If no results were found, Alice cannot import this contact.
 If found, Alice will be able to import this contact into the contact list.
 
 Alternatively, the contact can also be imported using an ``add-contact`` Taler
 URI, see :ref:`Alias Management <dd-70-us-alias-mgmt>`.
 
   **Technical Note**: The wallet periodically performs lookups for contacts where their Taldir registrations have expired and refresh accordingly.
 
 Send Money
 ----------
 
   Prerequisites: Alice has installed Taler Wallet, Alice has registered an Alias.
 
 Bob wants to directly send money to Alice (e.g. PayPal style).
 He opens his Taler wallet and opens ``Taler Button->Send``.
 A screen that allows to create a payment offer is shown to Bob.
 Once Bob has entered all necessary details, the payment offer is created and the screen with the QR code is shown.
 There, he selects the *Send to Contact*.
 The *Send to Contact* screen consists of a search input and an Alias type selector.
 This screen now also allows to send the request to a contact by using the contact list.
 Bob selects *Send to Contact*.
 The *Send to Contact* screen brings up the contacts list to select a contact.
 
   **Note**: At this point, Bob may now also import a contact here ad-hoc, see :ref:`Contacts Management <dd-70-us-contacts-mgmt>`.
 
 Bob selects the contact and the payment offer is sent to Alice.
 
   **Technical Note**: The offer is sent to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`.
 
 This request may fail, for example if Alice's Mailbox is full.
 
   **Note**: Sending messages via Mailbox API may incur fees. So does creating a purse in the offer. This should probably be done in a single user action.
 
 Resend Payment Request
 ----------------------
 
   Prerequisites: Bos has already sent a payment request to Alice
 
 Bob may want to resend a payment request if it expired or if Alice lost the request.
 
   **Technical Note**: This does not mean that the request can get lost in transit. It means that it is possible that Alice lost her phone and needed to setup her Wallet again.
 
 Bob opens the open payment request and selects the contact to send it to again.
 
   **Technical Note**: This likely implies the creation of a new payment request, with the same detail of the already sent request. Sending the same request again is probably not a good idea. This, however, requires a new field to the contract terms (``idempotency_nonce``?) that we keep identical between both requests. That way, the receiving wallet can detect that it is a duplicate and act accordingly --- if already paid, ignore, if hard-rejected/banned ignore, and if merely expired show again.
 
 
 Open Questions
 ==============
 
 
 Proposed Solution
 =================
 
 The directory and mailbox services will be implemented as two distinct services.
 Both with have an open REST API which will be specified as part of the protocol.
 
 Directory
 ---------
 
 The directory will support an extensible interface for alias *validators*.
 Validators will ensure that users that want to register mailbox URIs under an alias
 are actually the owner/in control over the particular alias.
 For example, in order to use an email address as the alias a verification link will be
 sent to that address and the user needs to confirm registration.
 
 In addition to the REST API, the directory will support an extensible interface for
 alias *disseminators*.
 Disseminators will publish the alias-mailbox mapping.
 For example, DNS or GNS validators will publish the mappings under zones of the operator.
 
 Mailbox
 -------
 
 .. note::
 
    The normative mailbox API now specifies exactly 256-byte messages beginning
    with the sender's ephemeral public key; see
    :ref:`api-mailbox`.  The type-prefixed framing below records an earlier
    proposal and is not the current wire format.
 
 Messages are retuned from the API with a fixed length.
 The configured messages length must be obtained through the
 mailbox service configuration endpoint.
 The first two bytes of the message are 16 bit unsigned integers
 in network byte order that specify the message type.
 The remaining bytes contain the encrypted message (including the MAC).
 Messages are encrypted using HPKE (X25519 with ChaChaPoly1305 as AEAD).
 The proposed outer framing has a single message type carrying a Taler URI;
 after decryption, the payload is one of the two URI variants defined below.
 This type is identified by the bytes ``0x00 0x00``.
 This message type number is in network byte order prefixed before the HPKE ciphertext.
 The HPKE ciphertext starts with a 32 byte
 encapsulation followed by the encrypted URI.
 The encrypted URI is followed by a 16 byte MAC.
 The message type is part of the MAC (the additional data portion of the AEAD scheme).
 
 Wire format MailboxMessage:
 
 .. _MailboxMessage:
 .. ts:def:: MailboxMessage
 
    type MailboxMessage = (PaymentInvoiceMessage | MoneyTransferMessage) & MailboxMessageCommon
 
 
 .. _PaymentInvoiceMessage:
 .. ts:def:: PaymentInvoiceMessage
 
   interface PaymentInvoiceMessage {
     // Message type
     type: "payment-invoice";
 
     // Pay pull URI.
     payPullUri: string;
 
 
   }
 
 .. _MoneyTransferMessage:
 .. ts:def:: MoneyTransferMessage
 
   interface MoneyTransferMessage {
     // Message type
     type: "money-transfer";
 
     // Pay push URI.
     payPushUri: string;
 
 
   }
 
 .. ts:def:: MailboxMessageCommon
 
    interface MailboxMessageCommon {
      // Message type
      messageType: string;
 
      // Message identifier
      messageId: string;
 
      // Freeform text from sender.
      senderHint: string;
 
    }
 
 Definition of Done
 ==================
 
 (Only applicable to design documents that describe a new feature.  While the
 DoD is not satisfied yet, a user-facing feature **must** be behind a feature
 flag or dev-mode flag.)
 
 - :ref:`Taldir API <api-taldir>` implemented and deployed with at least SMS and Email validators. (DONE)
 - :ref:`Mailbox API <api-mailbox>` implemented and deployed.
 - Wallet functionality to support user stories implemented.
 
 Alternatives
 ============
 
 Drawbacks
 =========
 
 Discussion / Q&A
 ================
 
 (This should be filled in with results from discussions on mailing lists / personal communication.)