taler-docs

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

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


      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 **POSTAL_SUBJECT**
     92    Subject line of the letter. Optional; if it is unset or empty, the subject
     93    is ``Address validation``. Runs of whitespace, line breaks included, are
     94    printed as one space. A subject may wrap onto a second line; one that needs
     95    a third fails the letter with status 50.
     96 
     97 **POSTAL_OPENING**
     98    Salutation above the message. Optional; if it is unset or empty, it is
     99    ``To whom it may concern,``.
    100 
    101 **POSTAL_CLOSING**
    102    Closing below the message. Optional; if it is unset or empty, it is ``Best
    103    regards``.
    104 
    105 **POSTAL_SIGNATURE**
    106    Line under the closing, such as the sender's name and address. Optional; if
    107    it is unset or empty, it is ``Taler Operations AG, c/o Berner
    108    Fachhochschule, Höheweg 80, 2502 Biel/Bienne``. A deployment operated by
    109    anyone else should set it.
    110 
    111 Opening, closing and signature are printed with runs of whitespace as one
    112 space, on one line each; one that does not fit on a line fails the letter with
    113 status 50. The date above the subject is always in English.
    114 
    115 typst(1) must be installed and must support the ``--no-pdf-tags`` option.
    116 
    117 
    118 Exit Status
    119 ===========
    120 
    121 An exit status of 0, or in the 200 to 210 band, means the TAN was
    122 transmitted, or will be. Any other status means it was not. The success
    123 band starts at 200 rather than at 1 because GNUnet reports a helper it
    124 could not execute as exit status 1, which must not be mistaken for a
    125 delivery.
    126 
    127 **201**
    128    pingen accepted the letter for printing and dispatch. This is the success
    129    case; status 0 is never reported, as physical delivery cannot be confirmed.
    130 
    131 **10**
    132    The postal address is unusable: a required field is missing from the address
    133    object, or the address block does not fit the letter geometry.
    134 
    135 **30**
    136    pingen is unavailable or reported an internal error.
    137 
    138 **31**
    139    pingen rejected the letter or the upload.
    140 
    141 **40**
    142    One of the **PINGEN_** variables is not set, the helper was invoked with the
    143    wrong number of arguments, or typst(1) is missing or too old.
    144 
    145 **41**
    146    pingen refused the credentials or the organisation identifier.
    147 
    148 **42**
    149    The pingen account has insufficient balance to post the letter.
    150 
    151 **50**
    152    The transmission failed for a reason that could not be classified, including
    153    a message too long to be rendered on a single page, a **POSTAL_SUBJECT**
    154    too long for two lines, and a **POSTAL_OPENING**, **POSTAL_CLOSING** or
    155    **POSTAL_SIGNATURE** too long for one.
    156 
    157 
    158 See Also
    159 ========
    160 
    161 challenger-send-sms(1), challenger-send-email(1), challenger-httpd(1),
    162 challenger.conf(5), typst(1).
    163 
    164 
    165 Bugs
    166 ====
    167 
    168 Report bugs by using https://bugs.taler.net or by sending electronic
    169 mail to <taler@gnu.org>.