22.7. challenger-send-post(1)

22.7.1. Name

challenger-send-post - transmit a Challenger TAN by physical mail

22.7.2. Synopsis

challenger-send-post ADDRESS

22.7.3. Description

challenger-send-post transmits a TAN to a postal address. It renders a one-page letter to PDF using typst(1) and submits it to the pingen.com API, which prints and posts it physically.

The command is not normally invoked by hand. It is named in the AUTH_COMMAND option of a [challenger] configuration section (see challenger.conf(5)), and is executed by challenger-httpd(1) whenever a TAN must be delivered. The same invocation contract is used by the Anastasis authorization plugins and by the GNU Taler merchant backend, so the helper may be executed by any of those services.

ADDRESS is the user-supplied address object, as compact JSON. The fields consulted are CONTACT_NAME, ADDRESS_LINES and ADDRESS_COUNTRY, and their names derive from the enter-$ADDRESS_TYPE-form template on the Challenger side. ADDRESS_COUNTRY is a two-letter ISO 3166 alpha-2 code, which is translated to an English country name because pingen requires the country spelled out. An unrecognised code is passed through unchanged with a warning.

The message to transmit — including the TAN — is read from standard input. It is the MESSAGE_TEMPLATE_FILE of challenger-httpd(1) after expansion. The TAN is never passed on the command line.

The letter geometry places the addressee so that it shows through a window envelope. The letter is always exactly one page: the message body is scaled down in steps until the closing and signature still fit. A message too long to fit even at the smallest size causes the helper to fail rather than post a letter with a truncated TAN.

Posting a letter establishes only that pingen accepted it for printing and dispatch. This helper therefore never reports confirmed delivery: a successful run exits with status 1, meaning accepted for delivery. Physical delivery takes days and is not reported back.

Address fields are passed to typst(1) as string inputs and are never interpreted as markup, so addresses containing characters such as & are rendered correctly and are not a template injection risk.

22.7.4. Files

$HOME/authorization-post.log

Progress log.

$HOME/authorization-post.err

Error log. Also records the working directory retained after a failure.

The helper renders the letter in a temporary directory under /tmp/$USER-challenger-postal-generator-XXXXXX. On success the directory is removed. On any failure it is deliberately retained, because it holds the typst source, the rendered PDF and the API responses needed to diagnose the failure. Its location is noted in the error log.

22.7.5. Environment

PINGEN_CLIENT_ID

pingen.com API client identifier. Required.

PINGEN_CLIENT_SECRET

pingen.com API client secret. Required.

PINGEN_ORG_ID

pingen.com organisation identifier the letter is posted under. Required.

The helper fails with status 40 if any is unset or empty. Credentials are taken from the environment of the invoking daemon, never from a configuration file.

typst(1) must be installed and must support the --no-pdf-tags option.

22.7.6. Exit Status

An exit status below 10 means the TAN was transmitted, or will be. Any other status means it was not.

1

pingen accepted the letter for printing and dispatch. This is the success case; status 0 is never reported, as physical delivery cannot be confirmed.

10

The postal address is unusable: a required field is missing from the address object, or the address block does not fit the letter geometry.

30

pingen is unavailable or reported an internal error.

31

pingen rejected the letter or the upload.

40

One of the PINGEN_ variables is not set, the helper was invoked with the wrong number of arguments, or typst(1) is missing or too old.

41

pingen refused the credentials or the organisation identifier.

42

The pingen account has insufficient balance to post the letter.

50

The transmission failed for a reason that could not be classified, including a message too long to be rendered on a single page.

22.7.7. See Also

challenger-send-sms(1), challenger-send-email(1), challenger-httpd(1), challenger.conf(5), typst(1).

22.7.8. Bugs

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.