Design Doc 006: Extensions for GNU Taler
#############################################

Summary
=======

This design document describes a generic framework for how extensions (i.e.
optional features) to GNU Taler can be offered and used by the exchange,
merchants and wallets.

Motivation
==========

GNU Taler's list of supported features evolves over time.  For example, the
following features are going to be designed and implemented during the course
of 2021 and 2022:

* Peer-to-peer payments
* Anonymous age-restriction
* Escrow service for anonymous auctions

We call a feature an *extension* when it is *optional* for either the
exchange, wallet or merchant to enable and support it. (However, enabling
a feature might *require* the other parties to support the feature, too)

For optional features we therefore need a mechanism to express the
availability, version and configuration of a particular feature, f.e. p2p or
age-restriction offered by an exchange, and make it verifiable by the other
participants.

Requirements
============

TODO. Not sure if we have any requirements - other than particular
ideas/designs for extensions?


Proposed Solution
=================

Exchange
^^^^^^^^

The exchange will add two new REQUIRED fields in response to ``/keys``:

#. The (but maybe empty) field ``extensions`` which contains a dictionary of
   extension-names and their configuration, see below.

#. The field ``extensions_sig`` that contains the EdDSA signature of the SHA256-hash
   of the normalized JSON-string of the ``extenstions`` object.


The necessary changes to ``ExchangeKeysResponse`` are highlighted here:

.. ts:def:: ExchangeKeysResponse

   interface ExchangeKeysResponse {
   //...

   // Required (but maybe emtpy) field with a dictionary of (name, object)
   // pairs defining the supported extensions.
   // The name MUST be unique and SHOULD include version information in Taler's
   // protocol version ranges notation as suffix, starting with letter 'v',
   // f.e.: "age_restriction.v1" or "p2p.v1:2:3".
   extensions: { name: Extension };

   // Signature by the exchange master key of the SHA-512 hash of the
   // normalized JSON-object of field ``extenstions``.
   // The signature MUST have purpose ``TALER_SIGNATURE_MASTER_EXTENSIONS``.
   extensions_sig: EddsaSignature;

   //...
   }


Extension names
---------------

The names of extensions MUST be unique and SHOULD include a version information
in Taler's `protocol version ranges notation`_ as suffix starting with letter
'``v``', f.e.: ``age_restriction.v1`` or ``p2p.v1:2:3``.

.. _protocol version ranges notation: https://docs.taler.net/core/api-common.html#protocol-version-ranges

The full name MUST be registered with GANA_ along with a full description of
the extension. (TODO: be more specific)

.. _GANA: https://git.gnunet.org/gana.git


Extension object
----------------

The definition of ``Extension`` object itself is mostly up to the particular
feature.  **However**, it MUST contain the boolean field ``critical`` that has
the same semantics as as "critical" has for extensions in X.509_: if true, the
client must "understand" the extension before proceeding, if "false" clients
can safely skip extensions they do not understand.

.. _X.509: https://datatracker.ietf.org/doc/html/rfc5280#section-4.2


.. ts:def:: Extension

   interface Extension {
     // Same semantics as "critical" for extensions in X.509, see
     // https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.
     // If "true", the client must "understand" the extension before proceeding.
     // If "false", clients can safely skip extensions they do not understand.
     critical: boolean;

     // Additional fields defined by the feature itself
     ...

   }


**TODO**:

* Add examples for age-restriction and p2p.

Merchant
^^^^^^^^

TODO:

* Needs to express support for particular extensions, too.  F.e. age-restriction.

Alternatives
============

TODO.  None yet.


Drawbacks
=========

* We do not offer (yet) any lifetime cycle of a feature, that is:  There are
  only two states that a feature can be in: "available" or "not-available".

* The existing design for peer-to-peer payments must be adapted to this.

Discussion / Q&A
================

The initial ideas presented here are based on discussions between Özgür Kesim
and Christian Grothoff.