# Taler Directory

This is the Taler Directory (TalDir) implementation.
The API can be found here: https://docs.taler.net/core/api-taldir.html

# Build and Run

Compile and run:

```
$ ./bootstrap
$ ./configure --prefix=PREFIX
$ make && make install
(You may have to set your $PATH to include the go/bin folder accordingly)
$ cp config/taldir-example.conf taldir.conf
(Edit taldir.conf to fit your needs)
$ ./taler-directory-httpd
```

# Test

```
$ go test -v ./cmd/talidir-server
```

# Configuration

The configuration file of taldir is `taldir.conf`.
You may copy the example configuration `config/taldir-example.conf` to your
runtime directory and modify it according to your needs.

The following configuration variables exist:

For the `[taldir]` section:

  * "production" (boolean): true for a production deployment. Causes verbose log messages to be inhibited.
  * "db_backend" (string): "sqlite" for the SQLite database backend to be used.
  * "validators" (array): An array of strings for the validators/identity types that can be used. Currently supported values: "email"
  * "email_sender" (string): For email validations, what should the sender address be.
  * "host" (string): For the validation link, which hostname should be used (useful if behind proxy).
  * "bind_to" (string): Where to bind and listen (HTTP server).
  * "salt" (string): The salt to use for identity key hashes in the database may alternatively be an environment variable `TALDIR_SALT`.
  * "monthly_fee" (string): The monthly fee for a registration (Default: "KUDOS:1")
  * "default_doc_filetype" (string): The default file type for the terms of service and privacy policy documents (Default: "text/markdown")
  * "default_doc_lang" (string): The default language for the terms of service and privacy policy documents (Default: "en-US")
  * "default_tos_path" (string): The path for the terms of service documents. Taldir will look for `<lang>.<extension>` depending on the requested file type ("Accept"-header) and locale ("Accept-Language"-header) (Default: "terms/")
  * "default_pp_path" (string): See `default_tos_path` (Default: "privacy/")
  * "challenge_bytes" (number): The number of bytes (entropy) of the generated challenge (Default: 16)
  * "validation_initiation_max" (number): How many challenges can be requested to validate an address (Default: 3)
  * "validation_timeframe" (string): The timeframe in which challenges can be requested up to `validation_initiation_max` times (Default: 10m)
  * "solution_attempt_max" (number): How often can the solution be attempted for a challenge in the `solution_attempt_timeframe` (Default: 3)
  * "solution_attempt_timeframe" (string): The timeframe in which the solution can be attempted `solution_attempt_max` times (Default: "1h")
  * "merchant_baseurl_privat" (string): The base URL for the merchant API to use (Default: "http://merchant.taldir/instances/myInstance")
  * "merchant_token" (string): The access token for the merchant API (Default: "superSecretToken")
  * "validation_landing" (string): The location of the HTML template to use for the validation landing displaying a QR code. (Default: "templates/validation_landing.html"
  * "validation_expiration" (string): The duration for which incomplete registration requests are kept. (Default: "24h")

For the `[taldir-pq]` section:

  * "host" (string): The host of the Postgres database to use (Default: "localhost")
  * "port" (number): The port of the Postres database to use (Default: 5432)
  * "user" (string): The database user (Default: "taldir")
  * "password" (string): The database user password (Default: "secret")
  * "db_name" (string): The database name (Default: "taldir")

Examples and defaults for the configuration can be found in the `taldir.conf` file shipped with this software.

# Disseminators

Aliases will be disseminated through the REST API of the taler-directory service itself by default.
It is also possible to use other external disseminators.
At this point in time, only the GNU Name System (RFC 9498) is available as an additional
dissemiantion mechanism.

You can activate it through the configuration:

```
[taldir-disseminator-gns]
enabled = true
zone = "testtaldir"
expiration = "1d"
```

If `enabled` is set to `true`, the disseminator is enabled.
The GNS zone with the name configured under the `zone` key is where records
will be stored upon dissemination.
`expiration` is a relative expiration string (`1d` is one day, `15m` would be 15 minutes).
This defines the TTL of the records in GNS after which a re-resolution by resolvers
is required.
The default value of 1 day should be fine in most cases.
Note that this means that there will be up to 1 day of delay between the deletion or update of an
alias mapping and its removal/availability through GNS.

The GNS dissemination plugin requires a working GNUnet (https://www.gnunet.org) peer to be installed and started and the respective configured zone to exist.

Aliases will then be available for resolution in GNS using the `$H_ADDRESS` (see https://docs.taler.net/core/api-taldir.html#address-lookup) in GNS as TXT record:

```

  $ gnunet-gns -u $H_ADDRESS.$ZONE
```

where `$ZONE` is either the zone public key of the configured dissemination zone or a human-readable mapping to it (See the documentation of GNS for details).

# Validators

Taldir validators are executable programs which are used to transfer a validation
code out of band to the client.
A Taldir validator is uniquely identified by a name.
In order to enable a validator, its `<name>` must be present in the `validators` field
in the `taldir` section in the Taldir configuration file.
Further, a `taldir-<name>` section must exists which contains the following
variables:

  * "challenge_fee" (amount): The cost of a single challenge using this validation method.
  * "command" (string): The program to use to trigger the out of band transfer of the validation code.

## Validator command

The validator command is an executable program which takes exactly two arguments:
For example:

```
$ validator-test <address> <code>
```

The first argument of the validator command is the address in a validation method-specific format.
For example, the email validation expects an email address, the Twitter validator expects a Twitter handle, etc.
The second argument is the activation code generated by Taldir and which is expected to be transferred using the validation method to the user.

# Terms of Service and Privacy Policy

You may edit the document templates under `contrib/pp` and `contrib/tos`
to your needs.
You can build the documents using:

```
$ make update-tos
$ make update-pp
```

And configure/copy the built localized documents into your configured
paths, e.g.:

```
$ cp -r contrib/tos/en terms/
$ cp -r contrib/pp/en terms/
```

# Funding

This project is funded through [NGI TALER Fund](https://nlnet.nl/taler), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/TALER-LookupService).

[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
