taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

challenger-send-post.1.rst (4755B)

      1 challenger-send-post(1)
      2 #######################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-post** - transmit a Challenger TAN by physical mail
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-post** *ADDRESS*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-post** transmits a TAN to a postal address. It renders a
     22 one-page letter to PDF using typst(1) and submits it to the pingen.com API,
     23 which prints and posts it physically.
     24 
     25 The command is not normally invoked by hand. It is named in the
     26 ``AUTH_COMMAND`` option of a ``[challenger]`` configuration section (see
     27 challenger.conf(5)), and is executed by challenger-httpd(1) whenever a TAN must
     28 be delivered. The same invocation contract is used by the Anastasis
     29 authorization plugins and by the GNU Taler merchant backend, so the helper may
     30 be executed by any of those services.
     31 
     32 *ADDRESS* is the user-supplied address object, as compact JSON. The fields
     33 consulted are ``CONTACT_NAME``, ``ADDRESS_LINES`` and ``ADDRESS_COUNTRY``, and
     34 their names derive from the ``enter-$ADDRESS_TYPE-form`` template on the
     35 Challenger side. ``ADDRESS_COUNTRY`` is a two-letter ISO 3166 alpha-2 code,
     36 which is translated to an English country name because pingen requires the
     37 country spelled out. An unrecognised code is passed through unchanged with a
     38 warning.
     39 
     40 The message to transmit — including the TAN — is read from **standard input**.
     41 It is the ``MESSAGE_TEMPLATE_FILE`` of challenger-httpd(1) after expansion. The
     42 TAN is never passed on the command line.
     43 
     44 The letter geometry places the addressee so that it shows through a window
     45 envelope. The letter is always exactly one page: the message body is scaled down
     46 in steps until the closing and signature still fit. A message too long to fit
     47 even at the smallest size causes the helper to fail rather than post a letter
     48 with a truncated TAN.
     49 
     50 Posting a letter establishes only that pingen accepted it for printing and
     51 dispatch. **This helper therefore never reports confirmed delivery**: a
     52 successful run exits with status 201, meaning accepted for delivery. Physical
     53 delivery takes days and is not reported back.
     54 
     55 Address fields are passed to typst(1) as string inputs and are never
     56 interpreted as markup, so addresses containing characters such as ``&`` are
     57 rendered correctly and are not a template injection risk.
     58 
     59 
     60 Files
     61 =====
     62 
     63 *$HOME*\ ``/authorization-post.log``
     64    Progress log.
     65 
     66 *$HOME*\ ``/authorization-post.err``
     67    Error log. Also records the working directory retained after a failure.
     68 
     69 The helper renders the letter in a temporary directory under
     70 ``/tmp/$USER-challenger-postal-generator-XXXXXX``. On success the directory is
     71 removed. **On any failure it is deliberately retained**, because it holds the
     72 typst source, the rendered PDF and the API responses needed to diagnose the
     73 failure. Its location is noted in the error log.
     74 
     75 
     76 Environment
     77 ===========
     78 
     79 **PINGEN_CLIENT_ID**
     80    pingen.com API client identifier. Required.
     81 
     82 **PINGEN_CLIENT_SECRET**
     83    pingen.com API client secret. Required.
     84 
     85 **PINGEN_ORG_ID**
     86    pingen.com organisation identifier the letter is posted under. Required.
     87 
     88 The helper fails with status 40 if any is unset or empty. Credentials are taken
     89 from the environment of the invoking daemon, never from a configuration file.
     90 
     91 typst(1) must be installed and must support the ``--no-pdf-tags`` option.
     92 
     93 
     94 Exit Status
     95 ===========
     96 
     97 An exit status of 0, or in the 200 to 210 band, means the TAN was
     98 transmitted, or will be. Any other status means it was not. The success
     99 band starts at 200 rather than at 1 because GNUnet reports a helper it
    100 could not execute as exit status 1, which must not be mistaken for a
    101 delivery.
    102 
    103 **201**
    104    pingen accepted the letter for printing and dispatch. This is the success
    105    case; status 0 is never reported, as physical delivery cannot be confirmed.
    106 
    107 **10**
    108    The postal address is unusable: a required field is missing from the address
    109    object, or the address block does not fit the letter geometry.
    110 
    111 **30**
    112    pingen is unavailable or reported an internal error.
    113 
    114 **31**
    115    pingen rejected the letter or the upload.
    116 
    117 **40**
    118    One of the **PINGEN_** variables is not set, the helper was invoked with the
    119    wrong number of arguments, or typst(1) is missing or too old.
    120 
    121 **41**
    122    pingen refused the credentials or the organisation identifier.
    123 
    124 **42**
    125    The pingen account has insufficient balance to post the letter.
    126 
    127 **50**
    128    The transmission failed for a reason that could not be classified, including
    129    a message too long to be rendered on a single page.
    130 
    131 
    132 See Also
    133 ========
    134 
    135 challenger-send-sms(1), challenger-send-email(1), challenger-httpd(1),
    136 challenger.conf(5), typst(1).
    137 
    138 
    139 Bugs
    140 ====
    141 
    142 Report bugs by using https://bugs.taler.net or by sending electronic
    143 mail to <taler@gnu.org>.