From 7e50e0f1c424c96052e16e297e03089fc1be7aef Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 31 May 2017 16:26:54 +0200 Subject: removing 'docs' directory --- docs/conf.py | 285 ----------------------------- docs/configuration-basics.rst | 79 -------- docs/deployment.rst | 203 -------------------- docs/dev-merchant.rst | 38 ---- docs/dev-talerdotnet.rst | 178 ------------------ docs/dev-wallet-wx.rst | 212 --------------------- docs/exts/__pycache__/tsref.cpython-35.pyc | Bin 7458 -> 0 bytes docs/exts/tsref.py | 233 ----------------------- docs/global-licensing.rst | 215 ---------------------- docs/index.rst | 98 ---------- docs/integration-bank.rst | 81 -------- docs/integration-general.rst | 82 --------- docs/integration-merchant.rst | 256 -------------------------- docs/operate-merchant.rst | 210 --------------------- docs/releases.rst | 103 ----------- docs/versioning.rst | 60 ------ 16 files changed, 2333 deletions(-) delete mode 100644 docs/conf.py delete mode 100644 docs/configuration-basics.rst delete mode 100644 docs/deployment.rst delete mode 100644 docs/dev-merchant.rst delete mode 100644 docs/dev-talerdotnet.rst delete mode 100644 docs/dev-wallet-wx.rst delete mode 100644 docs/exts/__pycache__/tsref.cpython-35.pyc delete mode 100644 docs/exts/tsref.py delete mode 100644 docs/global-licensing.rst delete mode 100644 docs/index.rst delete mode 100644 docs/integration-bank.rst delete mode 100644 docs/integration-general.rst delete mode 100644 docs/integration-merchant.rst delete mode 100644 docs/operate-merchant.rst delete mode 100644 docs/releases.rst delete mode 100644 docs/versioning.rst diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 2fafeb95..00000000 --- a/docs/conf.py +++ /dev/null @@ -1,285 +0,0 @@ -""" - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU Lesser General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold - @author Benedikt Muller - @author Sree Harsha Totakura - @author Marcello Stanisci -""" -# -*- coding: utf-8 -*- -# -# neuro documentation build configuration file, created by -# sphinx-quickstart on Sat May 31 13:11:06 2014. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.3' - -sys.path.append(os.path.abspath('exts')) - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'tsref', - 'sphinx.ext.todo', - 'sphinx.ext.imgmath', - 'sphinxcontrib.httpdomain' -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Taler' -copyright = u'2014, 2015, 2016, 2017 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.2' -# The full version, including alpha/beta/rc tags. -release = '0.2.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -html_show_sphinx = False - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'neurodoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ('index', 'taler.tex', u'Taler Documentation', - u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff', - 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'taler', u'GNU Taler Exchange Operator Manual', - [u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff'], - 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'taler', u'GNU Taler Exchange Operator Manual', - u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff', - 'Taler', 'One-Click Cash Payments.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False diff --git a/docs/configuration-basics.rst b/docs/configuration-basics.rst deleted file mode 100644 index 50c3d532..00000000 --- a/docs/configuration-basics.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Marcello Stanisci - -====================== -Configuration in Taler -====================== - -In Taler realm, any component obeys to the same pattern to get configuration -values. According to this pattern, once the component has been installed, the -installation deploys default values in `${prefix}/share/taler/config.d/`, in -`.conf` files. In order to override these defaults, the user can write a custom -`.conf` file and either pass it to the component at execution time, or name it -`taler.conf` and place it under `$HOME/.config/`. - - --------------------- -Configuration format --------------------- - -A config file is a text file containing `sections`, and each section contains -its `values`. The right format follows:: - - [section1] - value1 = string - value2 = 23 - - [section2] - value21 = string - value22 = /path22 - -Throughout any configuration file, it is possible to use ``$``-prefixed variables, -like ``$VAR``, especially when they represent filesystem paths. -It is also possible to provide defaults values for those variables that are unset, -by using the following syntax: ``${VAR:-default}``. -However, there are two ways a user can set ``$``-prefixable variables: - -by defining them under a ``[paths]`` section, see example below, :: - - [paths] - TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data - .. - [section-x] - path-x = ${TALER_DEPLOYMENT_SHARED}/x - -or by setting them in the environment:: - - $ export VAR=/x - -The configuration loader will give precedence to variables set under ``[path]``, -though. - -The utility ``taler-config``, which gets installed along with the exchange, serves -to get and set configuration values without directly editing the `.conf`. -The option ``-f`` is particularly useful to resolve pathnames, when they use -several levels of ``$``-expanded variables. See ``taler-config --help``. - -Note that, in this stage of development, the file ``$HOME/.config/taler.conf`` -can contain sections for *all* the component. For example, both an exchange and -a bank can read values from it. - -The repository ``git://taler.net/deployment`` contains examples of configuration -file used in our demos. See under ``deployment/config``. - -.. note:: - - Expectably, some components will not work just by using default values, as their - work is often interdependent. For example, a merchant needs to know an exchange - URL, or a database name. diff --git a/docs/deployment.rst b/docs/deployment.rst deleted file mode 100644 index 4d18dec5..00000000 --- a/docs/deployment.rst +++ /dev/null @@ -1,203 +0,0 @@ -=================== -Deployment Protocol -=================== - ------- -Wallet ------- - -.. code-block:: none - - $ cd wallet-webex - - # check dependencies - $ ./configure - - # edit version and version_name - $ $EDITOR manifest.json - - $ make package-stable - -The built wallet is now ready in `taler-wallet-stable-${version_name}${version}.zip`. - -FIXME: here, we should do some semi-automated testing with selenium, to see -that everything works against `demo.taler.net`. - -The package can now be uploaded to https://chrome.google.com/webstore/developer/dashboard - -FIXME: include asset links and descriptions we use in the webstore in this document - -FIXME: include instructions for other app stores - ------------------ -Deploying to test ------------------ - -1. From a clean home directory, first clone the deployment repository - -.. note:: - in case you clean some existing environment, make sure the ``~/.config`` - and other hidden directories are deleted as well. Make also sure that - a symlink to /test/shared-data exists before going on with the deployment. - -.. code-block:: none - - $ git clone /var/git/deployment.git - -2. Run the bootstrap script; this will checkout any needed repository - -.. code-block:: none - - $ deployment/bootstrap-bluegreen test - -3. Compile the project - -.. code-block:: none - - $ source activate - $ taler-deployment-build - -4. Create configuration file - -.. code-block:: none - - $ taler-deployment-config-generate - -5. Create denomination and signing keys - -.. note:: - This step takes care of creating auditor's signature too. - -.. code-block:: none - - $ taler-deployment-keyup - -6. Sign exchange's /wire response file - -.. code-block:: none - - taler-deployment-config-sign - - --------------------- -Deploying to stable --------------------- - -First, make sure that the deployment *AND* the deployment scripts work on the `test.taler.net` deployment. - -For all repositories that have a separate stable branch (currently exchange.git, -merchant.git, merchant-frontends.git, bank.git, landing.git) do: - -.. code-block:: none - - $ cd $REPO - $ git pull origin master stable - $ git checkout stable - - # option a: resolve conflicts resulting from hotfixes - $ git merge master - $ ... - - # option b: force stable to master - $ git update-ref refs/heads/stable master - - $ git push # possibly with --force - - # continue development - $ git checkout master - - -Log into taler.net with the account that is *not* active by looking -at the `sockets` symlink of the `demo` account. - -The following instructions wipe out the old deployment completely. - -.. code-block:: none - - $ ls -l ~demo/sockets - - [...] sockets -> /home/demo-green/sockets/ - -In this case, `demo-green` is the active deployment, and `demo-blue` should be updated. -After the update is over, the `/home/demo/sockets` symlink will be pointed to `demo-blue`. - -.. code-block:: none - - # Remove all existing files - $ find $HOME -exec rm -fr {} \; - - $ git clone /var/git/deployment.git - $ ./deployment/bootstrap-bluegreen demo - - # set environment appropriately - $ . activate - $ taler-deployment-build - - # upgrade the database! this - # process depends on the specific version - - $ taler-deployment-start - - # look at the logs, verify that everything is okay - -Now the symlink can be updated. - ----------------------------------------- -Deploying to developer personal homepage ----------------------------------------- - -.. note:: - Specific to the `tripwire` machine. Ask for a personal Taler - development environment at taler@gnu.org! - -1. From your clean homepage, clone the deployment repository - -.. code-block:: none - - $ git clone /var/git/deployment.git - -Please, *IGNORE* the message saying to start the database in the following way: -`/usr/lib/postgresql/9.5/bin/pg_ctl -D talerdb -l logfile start`. This is Postgres -specific and overridden by our method of starting services. - -2. Run the bootstrap script; this will checkout any needed repository - -.. code-block:: none - - $ deployment/bootstrap-standalone - -3. Build the project - -.. code-block:: none - - $ source activate - $ taler-deployment-build - -4. Generate configuration - -.. code-block:: none - - $ taler-deployment-config-generate - # This will sign exchange's /wire response - $ taler-deployment-config-sign - -5. Generate denomination keys - -.. code-block:: none - - # This will also get denomination keys signed by - # the auditor. - $ taler-deployment-keyup - -6. Start all services - -.. note:: - Notify the sysadmin to add the user 'www-data' to your group, - otherwise nginx won't be able to open your unix domain sockets. - -.. code-block:: none - - # NOTE: some services might need an explicit reset of the DB. - # For example, the exchange might need 'taler-exchange-dbinit -r' - # to be run before being launched. - $ taler-deployment-start diff --git a/docs/dev-merchant.rst b/docs/dev-merchant.rst deleted file mode 100644 index e4cd4cbc..00000000 --- a/docs/dev-merchant.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Marcello Stanisci - -======== -Merchant -======== - -.. _merchant-arch: - ------- -Design ------- - -In order for a merchant to be Taler-compatible, they need to run two distinct Web -services: a *frontend* and a *backend*. The former is typically the Web site where -the merchant exposes their goods, whereas the latter is a C program in charge of -making all the Taler-related cryptography. - -In details, the frontend gathers all the information from customers about sales, -and forwards it to the backend via its RESTful API. Typically, the backend will either -cryptographically process this data or just forward it to the exchange. - -That saves the frontend developers from dealing with cryptography in scripting -languages and from commmunicating at all with any exchange. - -Additionally, the backend RESTful API is such that a frontend might be run completely -database-less. diff --git a/docs/dev-talerdotnet.rst b/docs/dev-talerdotnet.rst deleted file mode 100644 index 760b7420..00000000 --- a/docs/dev-talerdotnet.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold - -============================ -Infrastructure on taler.net -============================ - -------------------------------- -The test and demo environments -------------------------------- - -FIXME: describe - -------------------------------- -Per-user environments -------------------------------- - -.. - NOTE: this is already documented in deployment.rst. - -Every user that is in the `www-data` group can set up a custom environment, -available under `https://env.taler.net/$USER/`. - -.. code-block:: none - - $ cd $HOME - $ git clone /var/git/ - $ cd deployment - $ ./bootstrap-standalone - -This will set up a full Taler environment (with exchange, -merchant, merchant frontends, bank) as well as a per-user postgres instance. - -Sourcing the `~/.activate` script makes the following commands available: - -* `taler-deployment-update` to build the environment -* `taler-deployment-config-generate` to generate an unsigned configuration -* `taler-deployment-config-sign` to sign parts of the config like the wire transfer -* `taler-deployment-start` to start the environment (including the postgres instance) -* `taler-deployment-stop` to stop the environment (including the postgres instance) - --------- -Buildbot --------- -.. note:: - `worker` and `slave` are used interchangeably - -The user running the buildbot master is `containers`. - -++++++ -Master -++++++ - -To start the master, log in as `containers`, and run: - -.. code-block:: none - - $ ~/buildbot/start.sh - - # To stop it, run: - $ ~/buildbot/stop.sh - -There is also a "restart" script, runnable as follows: - - -.. code-block:: none - - $ ~/buildbot/restart.sh - -+++++++++++++++ -Selenium worker -+++++++++++++++ - -This worker is responsible for running the Selenium wallet test: -an automatic clicker that performs the cycle withdraw-and-spend. - -The `containers` user is also responsible for running the Selenium -buildbot worker. - -Start it with: - -.. code-block:: none - - $ source ~/buildbot/venv/bin/activate - $ buildbot-worker start ~/buildbot/selenium_worker/ - - # stop it with: - $ buildbot-worker stop ~/buildbot/selenium_worker/ - - # deactivate the virtual env with - $ deactivate - -+++++++++++ -Lcov worker -+++++++++++ - -The worker is implemented by the `lcovslave` user and is responsible -for generating the HTML showing the coverage of our tests, then available -on `https://lcov.taler.net`. - -.. - NOTE: document https://lcov.taler.net/ set-up - -To start the worker, log in as `lcovslave` and run: - -.. code-block:: none - - $ source ~/activate - $ taler-deployment-bbstart - - # To stop it: - $ taler-deployment-bbstop - -+++++++++++++++ -Switcher worker -+++++++++++++++ - -Taler.net uses a "blue/green" fashion to update the code it -uses in demos. Practically, there are two users: `test-green` -and `test-blue`, and only one of them is "active" at any time. - -Being `active` means that whenever nginx receives a HTTP request -for one of the Taler services (at our demo), it routes the request -to either test-blue or test-green via unix domain sockets. - -Upon any push to any of the Taler's subprojects, this worker is -responsible for building the code hosted at the inactive user and, -if all tests succeed, switching the active user to the one whose code -has just been compiled and tested. - -The worker is implemented by the `testswitcher` user. This user -has some additional "sudo" rights, since it has to act as `test-blue`, -`test-green` and `test` user in order to accompish its task. -Note that the "sudo file" is tracked in this (`deployment`) repository, -under the `sudoers` directory. - -To start the worker, log in as `testswitcher` and run: - -.. code-block:: none - - $ source ~/venv/bin/activate - $ buildbot-worker start ~/buildbot/slave - - # To stop it: - $ buildbot-worker stop ~/buildbot/slave - - # To exit the virtual env - $ deactivate - -+++++++++++++ -Manual switch -+++++++++++++ - -After the desired blue/green party has been compiled, it is possible to -log-in as `test` and run the script ``~/.ln-.sh``, in order to make -``test-`` active. - -------------------- -Site lcov.taler.net -------------------- - -The directory ``/var/www/lcov.taler.net`` contains the following two symlinks - -* `exchange` --> ``/home/lcovslave/exchange/doc/coverage`` -* `merchant` --> ``/home/lcovslave/merchant/doc/coverage`` - -The pointed locations are updated by the `lcovslave`. diff --git a/docs/dev-wallet-wx.rst b/docs/dev-wallet-wx.rst deleted file mode 100644 index 8ba29975..00000000 --- a/docs/dev-wallet-wx.rst +++ /dev/null @@ -1,212 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold - -===================== -WebExtensions Wallet -===================== - ------------- -Introduction ------------- - -The WebExtensions Wallet (*wxwallet*) can be used to pay with GNU Taler on web -sites from within modern web browsers. The `WebExtensions -`_ API enables the development of -cross-browser extensions. Google Chrome / Chromium, Mozilla Firefox, Opera and -Microsoft Edge will all offer support for WebExtensions and thus be able to support Taler. - -Currently Chrome hast the best support for WebExtensions (since the API is a -superset of Chrome's extension API). - ------------------------ -Development Environment ------------------------ - -The *wxwallet* mainly written in the `TypeScript -`_ language, which is a statically typed -superset of JavaScript. - -While the *wxwallet* is mainly intended to be run from inside a browser, the -logic is implemented in browser-independent modules that can also be called -from other environments such as `nodejs `_. This is -especially useful for automatically running unit tests. - - ------------------ -Project Structure ------------------ - -.. parsed-literal:: - - **manifest.json** extension configuration - **package.json** node.js package configuration - **tsconfig.json** TypeScript compiler configuration - **gulpfile.js** Build tasks script - **lib/** - **vendor/** 3rd party libraries - **wallet/** actual application logic - **emscripten/** emscripten object file and glue - **test/** - **run_tests.js** nodejs entry point for tests - **tests/** test cases - **content_scripts/notify.ts** wallet<->website signaling - **backgrond/main.ts** backend entry point - **img/** static image resources - **style/** CSS stylesheets - **pages/** pages shown in browser tabs - **popup/** pages shown the extension popup - - -------------------- -Building the Wallet -------------------- - -To build the extension for use during development, simply run the TypeScript compiler -from the extension directory: - -.. code-block:: sh - - $ cd wallet.git/wallet_webextension/extension/ - $ tsc - -This will use the ``tsconfig.json`` with development options such as `source map`_ support. - -.. _`source map`: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit - -When TypeScript source files are added or deleted to the project, make sure that the -globs in ``gulpfile.js`` match them so that they will be compiled. The ``tsconfig.json`` -is generated by running: - - -.. code-block:: sh - - $ gulp tsconfig - -.. caution:: - - Do not edit the ``tsconfig.json`` manually. The source files should be defined in - one place, and that is ``gulpfile.js``. - -To pack the extension in a format that can be uploaded to the Google Webstore, run: - -.. code-block:: sh - - $ gulp package - -This will build the wallet without source maps, copy resource files (which also need to be -specified in ``gulpfile.js``) and create an archive. - - ----------- -Emscripten ----------- - -`Emscripten `_ is C/C++ -to JavaScript compiler. Emscripten is used in the *wxwallet* to access -low-level cryptography from *libgcrypt*, and miscellaneous functionality from -*libgnunetutil* and *libtalerwallet*. - -TODO: say things about wrappers - - --------------------------------------- -Target Environments and Modularization --------------------------------------- - -Modules in the wallet are declared in TypeScript with -the ES6 module syntax. These modules are then compiled -to `SystemJS `_ `register` modules. - -SystemJS modules can be loaded from the browser as well as from nodejs. -However they require special entry points that configure the module system, -load modules and execute code. Examples are `backgrond/main.ts` for the -browser and `test/run_tests.js` for nodejs. - -Note that special care has to be taken when loading the Emscript code, -as it is not compatible with the SystemJS module, even in the `globals` -compatibility mode. - -The TypeScript sources in the *wxwallet* are compiled down to ES5, both to -enable running in node.js without transpilers and to avoid a `bug -`_ in the TypeScript -compiler. - ----------------------------- -IndexedDB Query Abstractions ----------------------------- - -The *wxwallet* uses a fluent-style API for queries on IndexedDB. - -TODO: say more about this - - -------- -Testing -------- - -Test cases for the wallet are written in TypeScript and -run with `mochajs `_ and the `better-assert `_ assertion -library. - -Run the default test suite with ``npm run test``, which will -call `mocha` with the right parameters. - - --------------------- -Internationalisation --------------------- - -Strings in the JavaScript code are internationalised using the following functions: - -- *i18n*: translate string with arbitrary arguments, the result is returned as string. - -.. code-block:: js - - i18n`You have ${n} coins.` - -- *i18n.parts*: Interpolate i18nized values with arbitrary objects. - Useful for example to include HTML elements. - -.. code-block:: js - - i18n.parts`Visit ${link} to get more coins.` - -- *i18n.pluralize*: translate with plural form. - The i18n.number() function returns a ``PluralNumber`` object - that specifies the argument that determines the plural form, - if not present the first numeric argument is used. - -.. code-block:: js - - i18n.pluralize( - i18n`${i}: you have ${i18n.number(n)} coin.`, - `${i}: you have ${i18n.number(n)} coins.`); - -These functions are defined in ``lib/i18n.ts``. -Include ``lib/vendor/jed.js``, ``lib/i18n.js``, ``lib/i18n-strings.js`` to use them. - -To extract strings from sources and update the .po files, run: - -.. code-block:: sh - - $ make i18n - -In static HTML files the ``lang`` attribute is used for language-specific strings: - -.. code-block:: html - -

Hello World!

-

Hallo Welt!

- -``lib/i18n.js`` and ``style/lang.css`` needs to be included for this to work. diff --git a/docs/exts/__pycache__/tsref.cpython-35.pyc b/docs/exts/__pycache__/tsref.cpython-35.pyc deleted file mode 100644 index 51886dd1..00000000 Binary files a/docs/exts/__pycache__/tsref.cpython-35.pyc and /dev/null differ diff --git a/docs/exts/tsref.py b/docs/exts/tsref.py deleted file mode 100644 index 8187f67f..00000000 --- a/docs/exts/tsref.py +++ /dev/null @@ -1,233 +0,0 @@ -""" - This file is part of GNU TALER. - Copyright (C) 2014, 2015 GNUnet e.V. and INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU Lesser General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold -""" - -""" -This extension adds a new lexer "tsref" for TypeScript, which -allows reST-style links inside comments (`LinkName`_), -and semi-automatically adds links to the definition of types. - -For type TYPE, a reference to tsref-type-TYPE is added. - -Known bugs and limitations: - - The way the extension works right now interferes wiht - Sphinx's caching, the build directory should be cleared - before every build. -""" - - -from pygments.util import get_bool_opt -from pygments.token import Name, Comment, Token, _TokenType -from pygments.filter import Filter -from sphinx.highlighting import PygmentsBridge -from sphinx.builders.html import StandaloneHTMLBuilder -from sphinx.pygments_styles import SphinxStyle -from pygments.formatters import HtmlFormatter -from docutils import nodes -from docutils.nodes import make_id -import re - - -_escape_html_table = { - ord('&'): u'&', - ord('<'): u'<', - ord('>'): u'>', - ord('"'): u'"', - ord("'"): u''', -} - - -class LinkingHtmlFormatter(HtmlFormatter): - def __init__(self, **kwargs): - super(LinkingHtmlFormatter, self).__init__(**kwargs) - self._builder = kwargs['_builder'] - - def _fmt(self, value, tok): - cls = self._get_css_class(tok) - href = tok_getprop(tok, "href") - caption = tok_getprop(tok, "caption") - content = caption if caption is not None else value - if href: - value = '%s' % (href, content) - if cls is None or cls == "": - return value - return '%s' % (cls, value) - - def _format_lines(self, tokensource): - """ - Just format the tokens, without any wrapping tags. - Yield individual lines. - """ - lsep = self.lineseparator - escape_table = _escape_html_table - - line = '' - for ttype, value in tokensource: - link = get_annotation(ttype, "link") - - parts = value.translate(escape_table).split('\n') - - if len(parts) == 0: - # empty token, usually should not happen - pass - elif len(parts) == 1: - # no newline before or after token - line += self._fmt(parts[0], ttype) - else: - line += self._fmt(parts[0], ttype) - yield 1, line + lsep - for part in parts[1:-1]: - yield 1, self._fmt(part, ttype) + lsep - line = self._fmt(parts[-1], ttype) - - if line: - yield 1, line + lsep - - -class MyPygmentsBridge(PygmentsBridge): - def __init__(self, builder, trim_doctest_flags): - self.dest = "html" - self.trim_doctest_flags = trim_doctest_flags - self.formatter_args = {'style': SphinxStyle, '_builder': builder} - self.formatter = LinkingHtmlFormatter - - -class MyHtmlBuilder(StandaloneHTMLBuilder): - name = "html-linked" - def init_highlighter(self): - if self.config.pygments_style is not None: - style = self.config.pygments_style - elif self.theme: - style = self.theme.get_confstr('theme', 'pygments_style', 'none') - else: - style = 'sphinx' - self.highlighter = MyPygmentsBridge(self, self.config.trim_doctest_flags) - - def write_doc(self, docname, doctree): - self._current_docname = docname - super(MyHtmlBuilder, self).write_doc(docname, doctree) - - -def get_annotation(tok, key): - if not hasattr(tok, "kv"): - return None - return tok.kv.get(key) - - -def copy_token(tok): - new_tok = _TokenType(tok) - # This part is very fragile against API changes ... - new_tok.subtypes = set(tok.subtypes) - new_tok.parent = tok.parent - return new_tok - - -def tok_setprop(tok, key, value): - tokid = id(tok) - e = token_props.get(tokid) - if e is None: - e = token_props[tokid] = (tok, {}) - _, kv = e - kv[key] = value - - -def tok_getprop(tok, key): - tokid = id(tok) - e = token_props.get(tokid) - if e is None: - return None - _, kv = e - return kv.get(key) - - -link_reg = re.compile(r"`([^`<]+)\s*(?:<([^>]+)>)?\s*`_") - -# Map from token id to props. -# Properties can't be added to tokens -# since they derive from Python's tuple. -token_props = {} - - -class LinkFilter(Filter): - def __init__(self, app, **options): - self.app = app - Filter.__init__(self, **options) - - def filter(self, lexer, stream): - id_to_doc = self.app.env.domaindata.get("_tsref", {}) - for ttype, value in stream: - if ttype in Token.Keyword.Type: - defname = make_id('tsref-type-' + value); - t = copy_token(ttype) - if defname in id_to_doc: - docname = id_to_doc[defname] - href = self.app.builder.get_target_uri(docname) + "#" + defname - tok_setprop(t, "href", href) - - yield t, value - elif ttype in Token.Comment: - last = 0 - for m in re.finditer(link_reg, value): - pre = value[last:m.start()] - if pre: - yield ttype, pre - t = copy_token(ttype) - x1, x2 = m.groups() - if x2 is None: - caption = x1.strip() - id = make_id(x1) - else: - caption = x1.strip() - id = make_id(x2) - if id in id_to_doc: - docname = id_to_doc[id] - href = self.app.builder.get_target_uri(docname) + "#" + id - tok_setprop(t, "href", href) - tok_setprop(t, "caption", caption) - else: - self.app.builder.warn("unresolved link target in comment: " + id) - yield t, m.group(1) - last = m.end() - post = value[last:] - if post: - yield ttype, post - else: - yield ttype, value - - - -def remember_targets(app, doctree): - docname = app.env.docname - id_to_doc = app.env.domaindata.get("_tsref", None) - if id_to_doc is None: - id_to_doc = app.env.domaindata["_tsref"] = {} - for node in doctree.traverse(): - if not isinstance(node, nodes.Element): - continue - ids = node.get("ids") - if ids: - for id in ids: - id_to_doc[id] = docname - - -def setup(app): - from sphinx.highlighting import lexers - from pygments.lexers import TypeScriptLexer - from pygments.token import Name - from pygments.filters import NameHighlightFilter - lexer = TypeScriptLexer() - lexer.add_filter(LinkFilter(app)) - app.add_lexer('tsref', lexer) - app.add_builder(MyHtmlBuilder) - app.connect("doctree-read", remember_targets) diff --git a/docs/global-licensing.rst b/docs/global-licensing.rst deleted file mode 100644 index 7a5e8226..00000000 --- a/docs/global-licensing.rst +++ /dev/null @@ -1,215 +0,0 @@ -=========================== -Taler licensing information -=========================== - -This file gives an overview of all Taler component's licensing and of -runtime dependencies thereof. For "component" here is meant a set of -source files which can be retrieved from a single repository. If -components consist of sources under different licensing regimes, i.e. -because we want to enable third party developments to easily integrate -with Taler, those are described as well. - -All components are generally released under Lesser GPL, GPL or Affero -GPL. The main strategy is for libraries that third parties may need -to integrate with Taler to be under LGPL, standalone binaries and -testcases to be under GPL, and Web servers implementing Web services -to be under AGPL. - -+++++++++++++++++++++++++ -API (git://taler.net/api) -+++++++++++++++++++++++++ - -The specification has been jointly developed by INRIA and by individuals -being under the juridical subject called 'GNUnet e.V.'. For each source -file, the header indicated whose is holding the copyright, since some -parts have been taken "verbatim" from the GNUnet e.V. foundation, and -some other have been developed at INRIA "ex novo". - -Generally, GNU GPLv3 license is used for them; see COPYING.GPL. - - --------------------- -Runtime dependencies --------------------- -This component has no runtime dependencies as it is supposed to generate -HTML. - - -++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Firefox/Android/Python Wallet (git://taler.net/wallet) -++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -This project includes contributions from INRIA and GNUnet -e.V. developers. Please refer to each source file to obtain -information about the copyright holder. The GNU GPLv3 is used as the -license for Wallets. Some components may be under the LGPL. - --------------------- -Runtime dependencies --------------------- - -The following list encompasses all the runtime dependencies for this -project, and gives the copyright holder for each of them: - -* libgnunetutil: GPLv3+, GNUnet e.V. -* libgnunetjson: GPLv3+, GNUnet e.V. -* libgcrypt: LGPL, Free Software Foundation -* libunistring: LGPL, Free Software Foundation -* Python: Python Software Foundation License, LGPL-Compatible, Python Software Foundation -* Mozilla Firefox: Mozilla Public License, LGPL-Compatible, Mozilla Foundation - - -+++++++++++++++++++++++++++++++++++++++++++++++++++ -WebExtensions Wallet (git://taler.net/wallet-webex) -+++++++++++++++++++++++++++++++++++++++++++++++++++ - -The TypeScript code was developed 100% at INRIA, but the project -involves compiling libgnunetutil and libtalerutil to JavaScript, and -thus depends on software from GNUnet e.V. - -Each source carries its own copyright holder(s), but it is generally -licensed under GPLv3+. - --------------------- -Runtime dependencies --------------------- - -The following list encompasses all the runtime dependencies for this -project, and gives the copyright holder for each of them: - -* libgnunetutil: GPLv3+, GNUnet e.V. -* libgnunetjson: GPLv3+, GNUnet e.V. -* libgcrypt: LGPL, Free Software Foundation -* libunistring: LGPL, Free Software Foundation - -Note that these dependencies are compiled into the extension and do -not appear as separate binary files. - - -+++++++++++++++++++++++++++++++++++ -Merchant (git://taler.net/merchant) -+++++++++++++++++++++++++++++++++++ - -This project contains code under two different licenses, and whose -copyright is held by INRIA and/or GNUnet e.V.. Please refer to each -source file to know which party holds the copyright. - -Source files are located in the following directories: - -* src/lib/ -* src/backend/ -* src/backenddb/ -* src/include/ -* src/tests/ -* examples/blog/ -* examples/shop/ -* copylib/ - -In examples/blog/articles/ we included a book by Richard Stallman. -It comes with its own permissive license (see COPYING in the -directory). - - -The merchant's backend (i.e. all the code in src/backend/) is under -the GNU Affero GPL as it depends on libgnunetutil. Note that the use -of the Affero GPL has little impact as the backend is not supposed to -be directly accessible to the Internet). The license for this code is -in COPYING.GPL and COPYING.AGPL. - -The merchant's frontend logic (i.e. JavaScript interacting with -the wallet, sample code for a shop) is under the GNU LGPL (but -we may choose to change this to be in the public domain or -BSD-licensed if necessary; the code is so short that there is -anyway the question whether it is copyrightable). Under this same -license, it comes the merchant library (src/lib/) as it can be linked -with more diverse licensed software. The license text for this code -is in COPYING.LGPL. - - - --------------------- -Runtime dependencies --------------------- - -The following list encompasses all the runtime dependencies for this -project, and gives the copyright holder for each of them: - -* libjansson: MIT License, AGPL- and LGPL-Compatible, owned by Petri Lehtinen and other individuals -* libgcrypt: LGPL, owned by Free Software Foundation -* postgresql: PostgreSQL License, AGPL- and LGPL-Compatible, owned by The PostgreSQL Global Development Group -* libgnunetutil (in all of its variants): GPLv3+, owned by GNUnet e.V. -* PHP: PHP License, AGPL- and LGPL-Compatible, owned by The PHP Group - -+++++++++++++++++++++++++++ -Bank (git://taler.net/bank) -+++++++++++++++++++++++++++ - ---------- -Licensing ---------- - -This project has been developed by INRIA. For each source file, the -header indicated whose is holding the copyright. The licensing plan -for the bank is to use the Affero GPLv3+. - -Source files of interest are located in the following directories: -(The repository holds also scaffolded files autogenerated by Django, -which do not have legal significance in this context.) - -* TalerBank/Bank/ -* TalerBank/Bank/templates/ -* TalerBank/my-static/ -* website/ - --------------------- -Runtime dependencies --------------------- - -The following list encompasses all the runtime dependencies for this -project, and gives the copyright holder for each of them: - -* Django: BSD License, AGPL-Compatible, owned by Django Software Foundation -* validictory: BSD License, AGPL-Compatible, owned by James Turk -* django-simple-math-captcha: Apache Software License, LGPL-Compatible (FIXME), Brandon Taylor -* requests: Apache2 License, AGPL-Compatible, owned by Kenneth Reitz -* Python: Python Software Foundation License, AGPL-Compatible, Python Software Foundation -* PHP: PHP License, AGPL-Compatible, owned by The PHP Group - - -.. _exchange-repo: - -+++++++++++++++++++++++++++++++++++ -Exchange (git://taler.net/exchange) -+++++++++++++++++++++++++++++++++++ - -This component is based on code initially developed in Munich for -GNUnet e.V. Most recent improvements and maintenance has been done at -Inria. The copyright is thus shared between both institutions. - -The licensing for exported libraries to access the exchange is LGPL, -the exchange itself is under AGPL, and testcases and standalone -binaries are under GPL. - - --------------------- -Runtime dependencies --------------------- - -The following list encompasses all the runtime dependencies for this -project, and gives the copyright holder for each of them: - -* libjansson: MIT License, AGPL- and LGPL-Compatible, owned by Petri Lehtinen and other individuals -* libgcrypt: LGPL, owned by Free Software Foundation -* postgresql: PostgreSQL License, AGPL- and LGPL-Compatible, owned by The PostgreSQL Global Development Group -* libgnunetutil (in all of its variants): GPLv3+, owned by GNUnet e.V. -* libgnunetjson: GPLv3+, GNUnet e.V. - - -+++++++++++++++++++++++++++++++++++++++++ -Web includes (git://taler.net/web-common) -+++++++++++++++++++++++++++++++++++++++++ - -All copyright owned by INRIA (but questionable whether creativity -threshold for copyright is even met). - -Sources are licensed under the GNU LGPL. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 5b3bed44..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 GNUnet e.V. - - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold - @author Benedikt Muller - @author Sree Harsha Totakura - -GNU Taler Documentation -======================= - -We are building an anonymous, taxable payment system using modern -cryptography. Customers will use traditional money transfers to send -money to a digital Exchange and in return receive (anonymized) digital -cash. Customers can use this digital cash to anonymously pay -Merchants. Merchants can redeem the digital cash for traditional -money at the digital Exchange. As Merchants are not anonymous, they can -be taxed, enabling income or sales taxes to be withheld by the state -while providing anonymity for Customers. - -Cryptography is used to ensure that none of the participants can -defraud the others without being detected immediately; however, in -practice a fradulent Exchange might go bankrupt instead of paying the -Merchants and thus the Exchange will need to be audited regularly like -any other banking institution. - -The system will be based on free software and open protocols. - -In this document, we describe the REST-based APIs between the various -components, internal architecture of key components, and how to get them -installed. - ------------------ -Operator Handbook ------------------ - -The *Operator Handbook* is for people who want to run a exchange or a merchant. -It focuses on how to install, configure and run the required software. - -.. toctree:: - :maxdepth: 2 - - global-licensing - configuration-basics - operate-merchant - versioning - ------------------------- -Web Integration Handbook ------------------------- - -The *Web Integration Handbook* is for those who want to interact with Taler -wallets on their own website. Integrators will also have to be familiar with -the material covered in the *Operator Handbook*. - - -.. toctree:: - :maxdepth: 2 - - integration-general - integration-bank - integration-merchant - example-essay-store - ------------------- -Developer Handbook ------------------- - -The *Developer Handbook* brings developers up to speed who want to hack on the -core components of the Taler reference implementation. - -.. toctree:: - :maxdepth: 2 - - dev-talerdotnet - dev-wallet-wx - dev-merchant - deployment - releases - ------------------- -Indices and tables ------------------- - -.. toctree:: - :hidden: - diff --git a/docs/integration-bank.rst b/docs/integration-bank.rst deleted file mode 100644 index 1dc2ec8d..00000000 --- a/docs/integration-bank.rst +++ /dev/null @@ -1,81 +0,0 @@ -============================== -Interaction with bank websites -============================== - -This section describes how bank websites can interact with the -Taler wallet. - -Currently the following functionality is supported: - * Querying for the presence of a Taler wallet. - * Receiving change notifications from the Taler wallet. - * Creating a reserve. - - -For JavaScript code examples, see :ref:`communication`. - -------------------------- -Reserve Creation Request -------------------------- - -The bank website can request the creation of a :term:`reserve`. This operation -will require the user to specify the exchange where he wants to create the reserve -and the resolution of a CAPTCHA, before any action will be taken. - -As a result of the reserve creation request, the following steps will happen in sequence: - 1. The user chooses the desired amount from the bank's form - 2. Upon confirmation, the wallet fetches the desired amount from the user-filled form and - prompts the user for the *exchange base URL*. Then ask the user to confirm creating the - reserve. - 3. The wallet will create a key pair for the reserve. - 4. The wallet will request the CAPTCHA page to the bank. In that request's parameters it - communicates the desired amount, the reserve's public key and the exchange base URL to the - bank - 5. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve - creation according to the gotten parameters. Together with `200 OK` status code sent back - to the wallet, it gets also a `ReserveCreated`_ object. - -Note that the reserve creation can be done by a SEPA wire transfer or some other means, -depending on the user's bank and chosen exchange. - -In response to the reserve creation request, the Taler wallet MAY cause the -current document location to be changed, in order to navigate to a -wallet-internal confirmation page. - -The bank requests reserve creation with the ``taler-create-reserve`` event. -The event data must be a `CreateReserveDetail`_: - - -.. _CreateReserveDetail: -.. code-block:: tsref - - interface CreateReserveDetail { - - // JSON 'amount' object. The amount the caller wants to transfer - // to the recipient's count - amount: Amount; - - // CAPTCHA's page URL which needs the following parameters - // query parameters: - // amount_value - // amount_fraction - // amount_currency - // reserve_pub - // exchange - // wire_details (URL encoding of /wire output from the exchange) - callback_url: string; - - // list of wire transfer types supported by the bank - // e.g. "SEPA", "TEST" - wt_types: Array - } - -.. _ReserveCreated: -.. code-block:: tsref - - interface ReserveCreated { - - // A URL informing the user about the succesfull outcome - // of his operation - redirect_url: string; - - } diff --git a/docs/integration-general.rst b/docs/integration-general.rst deleted file mode 100644 index 308ecf5a..00000000 --- a/docs/integration-general.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _integration-general: - -================================ -Taler Wallet Website Integration -================================ - -.. note:: - The wallet-Websites communication is switching to a new policy which - is NOT based on DOM events, therefore obsoleting this page. To be soon - documented. - - -Websites (such as banks and online shops) can communicate with -the Taler wallet by a standardized protocol. - -From a technical perspective, the Taller wallet communicates with -the website by sending and receiving `DOM events `_ -on the bank website's ``HTMLDocument``. - -DOM events used by Taler have the prefix ``taler-``. - -------------------------- -Wallet Presence Awareness -------------------------- - -The bank website queries the wallet's presence by sending a ``taler-probe`` event. The -event data should be `null`. - -If the wallet is present and active, it will respond with a ``taler-wallet-present`` event. - -While the user agent is displaying a website, the user might deactivate or -re-activate the wallet. A Taler-aware *should* react to those events, and -indicate to the user that they should (re-)enable the wallet if necessary. - -When the wallet is activated, the ``taler-wallet-load`` event is sent -by the wallet. When the wallet is deactivated, the ``taler-wallet-unload`` event -is sent by the wallet. - -.. _communication: - ----------------------- -Communication Example ----------------------- - -The bank website can send the event ``taler-XYZ`` with the event data ``eventData`` -to the wallet with the following JavaScript code: - -.. sourcecode:: javascript - - const myEvent = new CustomEvent("taler-XYZ", eventData); - document.dispatchEvent(myEvent); - -Events can be received by installing a listener: - - -.. sourcecode:: javascript - - function myListener(talerEvent) { - // handle event here! - } - document.addEventListener("taler-XYZ", myListener); - - --------------------- -Normalized Base URLs --------------------- - -Exchanges and merchants have a base URL for their service. This URL *must* be in a -canonical form when it is stored (e.g. in the wallet's database) or transmitted -(e.g. to a bank page). - -1. The URL must be absolute. This implies that the URL has a schema. -2. The path component of the URL must end with a slash. -3. The URL must not contain a fragment or query. - -When a user enters a URL that is, technically, relative (such as "alice.example.com/exchange"), wallets -*may* transform it into a canonical base URL ("http://alice.example.com/exchange/"). Other components *should not* accept -URLs that are not canonical. - -Rationale: Joining non-canonical URLs with relative URLs (e.g. "exchange.example.com" with "reserve/status") -results in different and slightly unexpected behavior in some URL handling libraries. -Canonical URLs give more predictable results with standard URL joining. diff --git a/docs/integration-merchant.rst b/docs/integration-merchant.rst deleted file mode 100644 index 53187503..00000000 --- a/docs/integration-merchant.rst +++ /dev/null @@ -1,256 +0,0 @@ -.. - This file is part of GNU TALER. - -.. - Note that this page is more a protocol-explaination than a guide that teaches - merchants how to work with Taler wallets - - Copyright (C) 2014, 2015, 2016 INRIA - - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Marcello Stanisci - @author Christian Grothoff - -================================== -Interaction with merchant websites -================================== - -.. _payprot: - -+++++++++++++++++++ -The payment process -+++++++++++++++++++ - -By design, the Taler payment process ensures the following properties: - -1. The user must see and accept a contract in a secure context before the payment happens. - That contract accounts for all the items which are supposed to be bought. - -2. The payment process must be idempotent, that is at any later time the customer must - be able to replay the payment and retrieve the resource he paid for. - In case where a physical item was bought, this online resource is the merchant's - order status page, which may contain tracking information for the customer. - Note that by `replaying the payment` we mean reusing the `same coins` used to pay for - the product the first time to get the `same product` the user got the first time. - So the replay does NOT subtract further credit from the user's total budget. - -3. Purchases are shareable: any purchase is given a URL that allows other users to - buy the same item(s). - -We call an *offer URL* any URL at the merchant's Web site that notifies the -wallet that the user needs to pay for something. The offer URL must take into -account that the user has no wallet installed, and manage the situation accordingly -(for example, by showing a credit card paywall). The notification can happen either -via JavaScript or via HTTP headers. - -The merchant needs to have a *contract URL* which generates the JSON -contract for Taler. Alternatively, the contract may be embedded -within the page returned by the offer URL and given to the wallet -via JavaScript or via an HTTP header. - -The merchant must also provide a *pay URL* to which the wallet can -transmit the payment. Again, how this URL is made known from the merchant -to the wallet, it is managed by the HTTP headers- or JavaScript-based protocol. - -The merchant must also have a *fulfillment URL*, that addresses points 2 and 3 above. -In particular, fulfillment URL is responsible for: - -* Deliver the final product to the user after the payment -* Instruct the wallet to send the payment to the pay URL -* Redirect the user to the offer URL in case they hit a shared fulfillment URL. - -Again, Taler provides two ways of doing that: JavaScript- and HTTP headers-based. - -Taler helps merchants on the JavaScript-based interaction by providing the -``taler-wallet-lib``. See https://git.taler.net/web-common.git/tree/taler-wallet-lib.ts - -------- -Example -------- - -For example, suppose Alice wants to pay for a movie. She will first -select the movie from the catalog, which directs her to the offer URL -*https://merchant/offer?x=8ru42*. This URL generates a "402 Payment -Required" response, and will instruct the wallet about the contract's -URL. Then the wallet downloads the contract that states that Alice is -about to buy a movie. The contract includes a fresh transaction ID, say 62. -Alice's browser detects the response code and displays the contract -for Alice. - -Alice then confirms that she wants to buy the movie. Her wallet -associates her confirmation with the details and a hash of the contract. -After Alice confirms, the wallet redirects her to the fulfillment URL, say -*https://merchant/fulfillment?x=8ru42&tid=62* that is specified in the -contract. - -The first time Alice visits this URL, the merchant will again -generate a "402 Payment Required" response, this time not including -the full contract but merely the hash of the contract (which includes -Alice's transaction ID 62), as well as the offer URL (which Alice -will ignore) and the pay URL. Alice's wallet will detect that -Alice already confirmed that she wants to execute this particular -contract. The wallet will then transmit the payment to the pay URL, -obtain a response from the merchant confirming that the payment was -successful, and then reload the fulfillment URL. - -This time (and every time in the future where Alice visits the -fulfillment URL), she receives the movie. If the browser has lost the -session state, the merchant will again ask her to pay (as it happened the -very first time she visited the fulfillment URL), and she will authenticate -by replaying the payment. - -If Alice decides to share the fulfillment URL with Bob and he visits -it, his browser will not have the right session state and furthermore -his wallet will not be able to replay the payment. Instead, his wallet -will automatically redirect Bob to the offer URL and allow him to -purchase the movie himself. - -.. _offer: - ---------------- -Making an offer ---------------- - -When a user visits a offer URL, the merchant returns a page that can interact -with the wallet either via JavaScript or by returning a "402 Payment Required". -This page's main objective is to inform the wallet on where it should get the -contract. In case of JavaScript interaction, the merchant should just return -a page whose javascript contains an invocation to ``offerContractFrom()`` -from ``taler-wallet-lib``. This function will download the contract from -`` and hand it to the wallet. - -In case of HTTP headers-based protocol, the merchant needs to set the header -`X-Taler-contract-url` to the contract URL. Once this information reaches the -browser, the wallet will takes action by reading that header and downloading -the contract. - -Either way, the contract gets to the wallet which then renders it to the user. - -.. _fulfillment: - -------------------------------- -Fulfillment interaction details -------------------------------- - -A payment process is triggered whenever the user visits a fulfillment -URL and he has no rights in the session state to get the items -accounted in the fulfillment URL. Note that after the user accepts a -contract, the wallet will automatically point the browser to the -fulfillment URL. - -Becasue fulfillment URLs implements replayable and shareable payments -(see points 2,3 above), fulfillment URL parameter must encompass all the -details necessary to reconstruct a contract. - -That saves the merchant from writing contracts to disk upon every contract -generation, and defer this operation until customers actually pay. - -.................. -HTTP headers based -.................. - -Once the fulfillment URL gets visited, deliver the final product if the user has -paid, otherwise: the merchant will reconstruct the contract and re-hash it, sending -back to the client a "402 Payment required" status code and some HTTP headers which -will help the wallet to manage the payment. Namely: - -* `X-taler-contract-hash` -* `X-taler-pay-URL` -* `X-taler-offer-URL` - -The wallet then looks at `X-taler-contract-hash`, and can face two situations: - -1. This hashcode is already present in the wallet's database (meaning that the user did accept the related contract), so the wallet can send the payment to `X-taler-pay-URL`. During this operation, the wallet associates the coins it sent to `X-taler-pay-URL` with this hashcode, so that it can replay payments whenever it gets this hashcode again. - -2. This hashcode is unknown to the wallet (meaning that the user visited a shared fulfillment URL). The wallet then points the browser to `X-taler-offer-URL`, which is in charge of generating a contract referring to the same items accounted in the fulfillment URL. Of course, the user is then able to accept or not the contract. - -................ -JavaScript based -................ - -Once the fulfillment URL gets visited, deliver the final product if the user has paid, otherwise: -the merchant will reconstruct the contract and re-hash it. Then it will return a page whose JavaScript -needs to include a call to ``taler.executeContract(..)``. See the following example: - -.. sourcecode:: html - - - - - - - .. - - - -The logic which will take place is the same as in the HTTP header based protocol. -Once ``executePayment(..)`` gets executed in the browser, it will hand its three -parameters to the wallet, which will: - -1. Send the payment to `` if `` is found in its database (meaning that the user accepted it). -2. Redirect the browser to ``, if `` is NOT found in its database, meaning that the user visited a shared fulfillment URL. - -.. - .................. - State and security - .................. - - The server-side state gets updated in two situations, (1) when an article is - "about" to be bought, which means when the user visits the fulfillment URL, - and (2) when the user actually pays. For (1), we use the contract hascode to - access the state, whereas in (2) we just define a list of payed articles. - For example: - - .. sourcecode:: python - - session[] = {'article_name': 'How_to_write_a_frontend'} # (1) - session['payed_articles'] = ['How_to_write_a_frontend', 'How_to_install_a_backend'] # (2) - - The list of payed articles is used by the frontend to deliver the article to the user: - if the article name is among ``session['payed_articles']``, then the user gets what they - paid for. - - The reason for using `` as the key is to prevent the wallet to send bogus - parameters along the fulfillment URL. `` is the contract hashcode that - the fulfillment handler gets from the backend using the fulfillment URL parameters. - - In fact, when the wallet sends the payment to the frontend pay handler, it has to provide - both coins and contract hashcode. That hascode is (1) verified by the backend when it - receives the coins, (2) used by the frontend to update the list of payed articles. - - See below an example of pay handler: - - .. sourcecode:: python - - ... - - # 'deposit_permission' is the JSON object sent by the wallet - # which contains coins and the contract hashcode. - response = send_payment_to_backend(deposit_permission) - - # The backend accepted the payment - if 200 == response.status_code: - # Here we pick the article name from the state defined at - # fulfillment time. - # deposit_permission['h_proposal_data'] is the contract hashcode - payed_article = session[deposit_permission['h_proposal_data']]['article_name'] - session['payed_articles'].append(payed_article) - - - So the wallet is forced to send a valid contract hashcode along the payment, - and since that hashcode is then used to update the list of payed articles, - the wallet is forced to send fulfillment URL parameters that match that hashcode, - therefore being valid parameters. diff --git a/docs/operate-merchant.rst b/docs/operate-merchant.rst deleted file mode 100644 index 7f88a00b..00000000 --- a/docs/operate-merchant.rst +++ /dev/null @@ -1,210 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Marcello Stanisci - @author Florian Dold - -============================== -Operating the Merchant Backend -============================== - -+++++++++++++ -Configuration -+++++++++++++ - -The following data and facilities have to be set up, in order to run a merchant backend: - -* Serving -* Currency -* Database -* Exchanges -* Keying -* Bank account -* Instances - -In this document, we assume that ``$HOME/.config/taler.conf`` is being customized. - -------- -Serving -------- - -The merchant backend can serve HTTP over both TCP and UNIX domain socket. - -The following values are to be configured under the section `[merchant]`: - -* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket -* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`. -* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix` -* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----). - --------- -Currency --------- - -The merchant backend supports only one currency. This data is set under the respective -option `currency` in section `[taler]`. - --------- -Database --------- - -The option `db` under section `[merchant]` gets the DB backend's name the merchant -is going to use. So far, only `db = postgres` is supported. After choosing the backend, -it is mandatory to supply the connection string (namely, the database name). This is -possible in two ways: - -* via an environment variable: `TALER_MERCHANTDB_POSTGRES_CONFIG`. -* via configuration option `config`, under section `[merchantdb-BACKEND]`. For example, the demo merchant is configured as follows: - -.. code-block:: text - - [merchant] - ... - db = postgres - ... - - [merchantdb-postgres] - config = postgres:///talerdemo - ---------- -Exchanges ---------- - -The options `uri` and `master_key`, under section `[merchant-exchange-MYEXCHANGE]`, let -the merchant add the exchange `MYEXCHANGE` among the exchanges the merchant wants to work -with. `MYEXCHAGE` is just a mnemonic name chosen by the merchant (which is not currently used -in any computation), and the merchant can add as many exchanges as it is needed. -`uri` is the exchange's base URL. Please note that a valid `uri` complies with the following -pattern:: - - schema://hostname/ - -`master_key` is the base32 encoding of the exchange's master key -(see `/keys `_). -In our demo, we use the following configuration:: - - [merchant-exchange-test] - URI = https://exchange.test.taler.net/ - MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 - ------- -Keying ------- - -The option `keyfile` under section `[merchant-instance-default]` is the path to the -merchant's :ref:`default instance ` private key. This key is needed to -sign certificates and other messages sent to wallets and exchanges. -To generate a 100% compatible key, it is recommended to use the ``gnunet-ecc`` tool. - ------------- -Bank account ------------- - -This piece of information is used when the merchant redeems coins to the exchange. -That way, the exchange will know to which bank account it has to transfer real money. -The merchant must specify which system it wants receive wire transfers with. We support -a `test` wire format so far, and supporting `SEPA` is among our priorities. - -The wire format is specified in the option `wireformat` under section `[merchant]`, -and the wire details are given via a JSON file, whose path must be indicated in the -option `X_response_file` under section `[default-wireformat]`, where `X` matches -the chosen wireformat. In our demo, we have:: - - [merchant] - .. - wireformat = test - .. - - [merchant-instance-wireformat-default] - test_response_file = ${TALER_CONFIG_HOME}/merchant/wire/test.json - -The file `test.json` obeys to the following specification - -.. code-block:: tsref - - interface WireDetails { - // matches wireformat - type: string; - - // base URL of the merchant's bank - bank_uri: string; - - // merchant's signature (unused, can be any value) - signature: string; - - // merchant's account number at the bank - account_number: Integer; - - // the salt (unused, can be any value) - salt: any; - } - -As an example, `test.json` used in our demo is shown below:: - - { - "type": "test", - "bank_uri": "https://bank.test.taler.net/", - "sig": "MERCHANTSIGNATURE", - "account_number": 6, - "salt": "SALT" - } - - - -.. _instances-lab: - ---------- -Instances ---------- - -In Taler, multiple shops can rely on the same :ref:`merchant backend `. -In Taler terminology, each of those shops is called `(merchant) instance`. Any instance -is defined by its private key and its wire details. In order to add the instance `X` to -the merchant backend, we have to add the sections `[merchant-instance-X]` and `[X-wireformat]`, -and edit them as we did for the `default` instance. For example, in our demo we add the -instance `Tor` as follows:: - - [merchant-instance-Tor] - KEYFILE = ${TALER_DATA_HOME}/merchant/tor.priv - - .. - - [merchant-instance-wireformat-Tor] - TEST_RESPONSE_FILE = ${TALER_CONFIG_HOME}/merchant/wire/tor.json - -Please note that `Taler messagging `_ -is designed so that the merchant frontend can instruct the backend on which instance has to -be used in the various operations. This information is optional, and if not given, -the backend will act as the `default` instance. - -++++++++++++ -Installation -++++++++++++ - -In order to compile your merchant backend, you firstly need to install the GNU Taler -exchange. As of other dependencies, the merchant backend needs exactly the same ones -as the exchange does. Follow :ref:`those instructions ` to build -everything needed. - -Assuming all the dependencies have been correctly installed, we can now build the -merchant backend using the following commands:: - - $ git clone git://taler.net/merchant - $ cd merchant - $ ./bootstrap - $ ./configure [--prefix=PFX] \ - [--with-gnunet=GNUNETPFX] \ - [--with-exchange=EXCHANGEPFX] - $ # Each dependency can be fetched from non standard locations via - $ # the '--with-' option. See './configure --help'. - $ make - $ make install diff --git a/docs/releases.rst b/docs/releases.rst deleted file mode 100644 index d0191ba0..00000000 --- a/docs/releases.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2016 INRIA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Florian Dold - - -============================== -Release Process and Checklists -============================== - -This document describes the process for releasing a new version of the various -Taler components to the official GNU mirrors. - -The following components are published on the GNU mirrors - -* taler-exchange (exchange.git) -* taler-merchant (merchant.git) -* talerfrontends (merchant-frontends.git) -* taler-bank (bank.git) -* taler-wallet-webex (wallet-webex.git) - - -------- -Tagging -------- - -Tag releases with an *annotated* commit, like - -:: - - git tag -a v0.1.0 -m "Official release v0.1.0" - git push origin v0.1.0 - ------------------- -Database for tests ------------------- - -For tests in the exchange and merchant to run, make sure that -a database `talertest` is accessible by `$USER`. Otherwise tests -involving the database logic are skipped. - ------------------- -Exchange, merchant ------------------- - -Set the version in `configure.ac`. The commit being tagged -should be the change of the version. - -For the exchange test cases to pass, `make install` must be run first. -Without it, test cases will fail because plugins can't be located. - -:: - - ./bootstrap - ./configure # add required options for your system - make dist - tar -xf taler-$COMPONENT-$VERSION.tar.gz - cd taler-$COMPONENT-$VERSION - make install check - --------------------- -Wallet WebExtension --------------------- - -The version of the wallet is in `manifest.json`. The `version_name` should be -adjusted, and `version` should be increased independently on every upload to -the WebStore. - -:: - - ./configure - make dist - - - -FIXME: selenium test cases - - ----------------------- -Upload to GNU mirrors ----------------------- - -See https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads - -Directive file: - -:: - - version: 1.2 - directory: taler - filename: taler-exchange-0.1.0.tar.gz - - -Upload the files in *binary mode* to the ftp servers. diff --git a/docs/versioning.rst b/docs/versioning.rst deleted file mode 100644 index 14336da0..00000000 --- a/docs/versioning.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU General Public License as published by the Free Software - Foundation; either version 2.1, or (at your option) any later version. - - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - You should have received a copy of the GNU Lesser General Public License along with - TALER; see the file COPYING. If not, see - - @author Christian Grothoff - -================== -GNU Taler Versions -================== - -This text describes how we assign version numbers for Taler software. -This is about the version numbers of package releases, not of the -libraries. For Taler libraries, we use libtool semantic versioning -conventions. - -Taler software release version numbers use the scheme -MAJOR.MINOR-PACKAGE. - -Here, MAJOR is used to indicate the compatibility level and is -increased for all significant releases that are always made across all -Taler components. - -The MINOR numbers is used for small updates that may address minor -issues but do not break compatibility. MINOR release may be made only -for a particular component, leaving other components untouched. Hence -you should expect to see say an exchange version 4.5 and a wallet -version 4.10. As they both start with "4", they are expected to be -protocol-compatible. - -PACKAGE is reserved for distributions, such as Debian. These distributions -may apply their own patch sets or scripting, and they are expected to -increment PACKAGE. The upstream Taler releases will just be of the -format MAJOR.MINOR. - ------------------------ -Alpha and Beta releases ------------------------ - -Before Taler is considered reasonably stable for actual use, we will -prefix the number "0." to the release version. Thus, all alpha and -beta releases will have a three-digit release number of the form -"0.MAJOR.MINOR". - ------------------------ -Roadmap ------------------------ - -A roadmap with the features we plan to have in each release is -in our bugtracker at https://gnunet.org/bugs/. The roadmap -is subject to change. -- cgit v1.2.3