commit a7c04285a4d1c0398a2fbb72f972b3fd7abcb2ec
parent ddbf8a397bfc21b62d4e150a99e3dcdaf6f85c6e
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 11 Aug 2026 13:29:10 +0200
add missing manpages for taler-helper-challenger
Diffstat:
12 files changed, 859 insertions(+), 19 deletions(-)
diff --git a/conf.py b/conf.py
@@ -368,6 +368,48 @@ man_pages = [
1,
),
(
+ "manpages/challenger-send-email.1",
+ "challenger-send-email",
+ "transmit a Challenger TAN by electronic mail",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/challenger-send-post.1",
+ "challenger-send-post",
+ "transmit a Challenger TAN by physical mail",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/challenger-send-sms.1",
+ "challenger-send-sms",
+ "transmit a Challenger TAN by SMS",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/challenger-send-sms-aspsms.1",
+ "challenger-send-sms-aspsms",
+ "transmit a Challenger TAN by SMS via ASPSMS",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/challenger-send-sms-clicksend.1",
+ "challenger-send-sms-clicksend",
+ "transmit a Challenger TAN by SMS via ClickSend",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/challenger-send-sms-telesign.1",
+ "challenger-send-sms-telesign",
+ "transmit a Challenger TAN by SMS via Telesign",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
"manpages/challenger.conf.5",
"challenger.conf",
"Challenger configuration file",
diff --git a/core/challenger/post-authorize-NONCE.rst b/core/challenger/post-authorize-NONCE.rst
@@ -117,11 +117,11 @@
// @since **v2**
retransmission_time: Timestamp;
- // how many times might the PIN still be retransmitted
+ // how many times might the TAN still be retransmitted
// @since **v2**
pin_transmissions_left: Integer;
- // how many times might the user still try entering the PIN code
+ // how many times might the user still try entering the TAN code
// @since **v2**
auth_attempts_left: Integer;
}
diff --git a/core/challenger/post-challenge-NONCE.rst b/core/challenger/post-challenge-NONCE.rst
@@ -83,7 +83,7 @@
permitted *address changes* was exhausted. The user must obtain a
fresh nonce from the client.
* ``TALER_EC_CHALLENGER_TOO_MANY_PIN_TRANSMISSIONS`` --- the number of
- permitted *PIN transmissions* for the current address was exhausted.
+ permitted *TAN transmissions* for the current address was exhausted.
The user may still try a different address if address changes remain.
Note that merely being within the retransmission cooldown is
@@ -96,7 +96,7 @@
* ``TALER_EC_GENERIC_DB_FETCH_FAILED`` --- reading the previously stored
address failed (``detail`` is ``"get_validation_address"``).
* ``TALER_EC_GENERIC_DB_STORE_FAILED`` --- storing the address or
- confirming the transmitted PIN failed (``detail`` is
+ confirming the transmitted TAN failed (``detail`` is
``"do_challenge_address"`` or ``"do_challenge_address_confirm_pin"``).
* ``TALER_EC_GENERIC_FAILED_TO_EXPAND_TEMPLATE`` --- expanding
``MESSAGE_TEMPLATE_FILE`` for the challenge message failed.
diff --git a/core/challenger/post-solve-NONCE.rst b/core/challenger/post-solve-NONCE.rst
@@ -17,7 +17,7 @@
If the request ask for application/json the response is
a `ChallengeSolveResponse`. Since protocol **v2**.
Note that this status is only used for the *successful* outcome; an
- incorrect or unusable PIN is reported with 403, 409 or 429 (see below).
+ incorrect or unusable TAN is reported with 403, 409 or 429 (see below).
:http:statuscode:`302 Found`:
Only possible if request didn't ask for application/json. Since protocol **v2**.
The user is redirected to the redirect URI of the client to pass the
@@ -39,7 +39,7 @@
* ``TALER_EC_GENERIC_PARAMETER_MISSING`` --- there is no ``pin`` field in
the body (``detail`` is ``"pin"``).
:http:statuscode:`403 Forbidden`:
- The PIN was checked and did not match.
+ The TAN was checked and did not match.
The response is `InvalidPinResponse`. Since protocol **v1**.
Returned with ``TALER_EC_CHALLENGER_INVALID_PIN``.
:http:statuscode:`404 Not found`:
@@ -73,10 +73,10 @@
the cases below, which are told apart by the error code:
* ``TALER_EC_CHALLENGER_NO_PIN_ATTEMPTS_LEFT`` --- the user has run out
- of PIN guesses but may still request a retransmission or change the
+ of TAN guesses but may still request a retransmission or change the
address. ``exhausted`` is true. Since protocol **v8**.
* ``TALER_EC_CHALLENGER_TOO_MANY_ATTEMPTS`` --- the user has exhausted
- address changes, PIN guesses *and* retransmissions, so the situation
+ address changes, TAN guesses *and* retransmissions, so the situation
is terminal and all three counters are zero. Since protocol **v8**
this returns an `InvalidPinResponse` as well; it previously returned
a plain error object with only ``code``, ``hint`` and ``detail``.
@@ -131,17 +131,17 @@
// address entry form
addresses_left: Integer;
- // how many times might the PIN still be retransmitted
+ // how many times might the TAN still be retransmitted
pin_transmissions_left: Integer;
- // how many times might the user still try entering the PIN code
+ // how many times might the user still try entering the TAN code
auth_attempts_left: Integer;
- // if true, the PIN was not even evaluated as the user previously
+ // if true, the TAN was not even evaluated as the user previously
// exhausted the number of attempts
exhausted: boolean;
- // if true, the PIN was not even evaluated as no challenge was ever
+ // if true, the TAN was not even evaluated as no challenge was ever
// issued (the user must have skipped the step of providing their
// address first!)
no_challenge: boolean;
diff --git a/deployments/tops.rst b/deployments/tops.rst
@@ -38,7 +38,7 @@ Establishing a Business Relationship
2. To do this, the customer must complete the corresponding VQF forms online
and upload documents. The customer's address is then verified by sending a
- PIN letter. The customer must also submit a certified copy of their ID by
+ TAN letter. The customer must also submit a certified copy of their ID by
postal mail. This is then digitally and physically filed. Alternatively, an
identity check can in principle also be carried out manually by TOPS
employees on site (in person) at the customer's premises. In this case, the
@@ -317,12 +317,12 @@ MROS Reporting (see ``INVESTIGATION_STATE`` property):
* ``INCR_INVESTIGATION_CONCLUDED`` / ``DECR_INVESTIGATION_CONCLUDED``
-PIN Letter
+TAN Letter
----------
After gathering initial information (``vqf_902_1_officer``), a letter with a
-PIN code is generated and sent to the customer. The customer needs to enter
-the PIN in the KYC SPA in order to validate their address. The letter
+TAN code is generated and sent to the customer. The customer needs to enter
+the TAN in the KYC SPA in order to validate their address. The letter
also needs to ask the customer to send a certified copy of certain documents.
The KYC SPA should also specify which documents are still needed.
@@ -942,7 +942,7 @@ Initial collection of basic attributes about customer during onboarding.
Depending on ``CUSTOMER_TYPE``, the customer is asked to fill out another
form:
-* ``NATURAL``: No other form to fill out. A PIN letter will be directly
+* ``NATURAL``: No other form to fill out. A TAN letter will be directly
sent to the customer.
* ``OPERATIONAL``: Form ``vqf_902_11_customer``
* ``FOUNDATION``: Form ``vqf_902_12``
diff --git a/manpages/challenger-send-email.1.rst b/manpages/challenger-send-email.1.rst
@@ -0,0 +1,93 @@
+challenger-send-email(1)
+########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **challenger-send-email** - transmit a Challenger TAN by electronic mail
+
+
+Synopsis
+========
+
+**challenger-send-email** *ADDRESS*
+
+
+Description
+===========
+
+**challenger-send-email** transmits a TAN to an e-mail address by handing the
+message to the local mail transfer agent via mail(1).
+
+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 field
+consulted is ``CONTACT_EMAIL``, and its name derives from the
+``enter-$ADDRESS_TYPE-form`` template on the Challenger side.
+
+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.
+
+Handing a message to a mail transfer agent establishes only that the agent
+accepted it for delivery. Whether it reaches the recipient's mailbox is decided
+later and asynchronously, and is never reported back. **This helper therefore
+never reports confirmed delivery**: a successful run exits with status 1,
+meaning accepted for delivery.
+
+Delivery requires a working local mail transfer agent. The helper does not
+configure one.
+
+
+Environment
+===========
+
+**challenger-send-email** reads no environment variables of its own. The
+behaviour of mail(1) and of the local mail transfer agent may be affected by the
+environment of the invoking daemon.
+
+
+Exit Status
+===========
+
+An exit status below 10 means the TAN was transmitted, or will be. Any other
+status means it was not.
+
+**1**
+ The mail transfer agent accepted the message for delivery. This is the
+ success case; status 0 is never reported, as delivery to a mailbox cannot be
+ confirmed.
+
+**10**
+ The address is malformed, or the ``CONTACT_EMAIL`` field is missing from the
+ address object.
+
+**30**
+ The local mail transfer agent failed or was unavailable.
+
+**40**
+ Invocation error, or mail(1) is not installed.
+
+**50**
+ The transmission failed for a reason that could not be classified.
+
+
+See Also
+========
+
+challenger-send-sms(1), challenger-send-post(1), challenger-httpd(1),
+challenger.conf(5), mail(1).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/challenger-send-post.1.rst b/manpages/challenger-send-post.1.rst
@@ -0,0 +1,140 @@
+challenger-send-post(1)
+#######################
+
+.. only:: html
+
+ Name
+ ====
+
+ **challenger-send-post** - transmit a Challenger TAN by physical mail
+
+
+Synopsis
+========
+
+**challenger-send-post** *ADDRESS*
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+See Also
+========
+
+challenger-send-sms(1), challenger-send-email(1), challenger-httpd(1),
+challenger.conf(5), typst(1).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/challenger-send-sms-aspsms.1.rst b/manpages/challenger-send-sms-aspsms.1.rst
@@ -0,0 +1,132 @@
+challenger-send-sms-aspsms(1)
+#############################
+
+.. only:: html
+
+ Name
+ ====
+
+ **challenger-send-sms-aspsms** - transmit a Challenger TAN by SMS via ASPSMS
+
+
+Synopsis
+========
+
+**challenger-send-sms-aspsms** *PHONE_NUMBER*
+
+
+Description
+===========
+
+**challenger-send-sms-aspsms** transmits a TAN to a mobile phone number using
+the ASPSMS web API.
+
+It is normally invoked by challenger-send-sms(1) as one provider in a fallback
+chain, and not directly. Its calling convention differs from that of the
+dispatcher: *PHONE_NUMBER* is the **bare phone number**, already extracted from
+the address object and already checked for general E.164 form. The message to
+transmit, including the TAN, is read from **standard input**.
+
+Each submission carries a generated transaction reference number, which is then
+used to poll the ASPSMS send log for a delivery report, for a bounded period. A
+message still in flight when the polling window closes is reported as accepted,
+not as a failure.
+
+ASPSMS accepts a message and reports errors in the body of an otherwise
+successful HTTP response; the integer ``ErrorCode`` field carries the outcome,
+and a value of 1 means success. The accompanying description text is not stable
+and is not used for classification.
+
+**ASPSMS has no error code for an unusable recipient number.** A malformed or
+unallocated number is accepted at submission, consuming a credit, and the
+problem is only revealed later in the delivery report as a reason code. A
+message to a switched-off handset may remain buffered for up to 24 hours before
+a final status is reported, far longer than the polling window, so such a
+message is reported as accepted rather than failed.
+
+
+Environment
+===========
+
+**ASPSMS_USERKEY**
+ ASPSMS account user key. Required.
+
+**ASPSMS_PASSWORD**
+ ASPSMS API password. Required.
+
+The helper fails with status 40 if either is unset or empty. Credentials are
+taken from the environment of the invoking daemon, never from a configuration
+file.
+
+
+Exit Status
+===========
+
+An exit status below 10 means the TAN was transmitted, or will be. Any other
+status means it was not. The subset below is what this helper can actually
+report; see challenger-send-sms(1) for the full table.
+
+**0**
+ Delivery to the handset was confirmed.
+
+**1**
+ ASPSMS accepted the message but delivery was not confirmed within the polling
+ window, including the common case of a message still buffered for a handset
+ that is switched off.
+
+**13**
+ The destination is not equipped for SMS, is not a subscriber, or the facility
+ is not supported or not provided by the network.
+
+**14**
+ The subscriber is unknown, or the destination address is invalid.
+
+**15**
+ The number is barred, either for calls or for the requested operation.
+
+**20**
+ The subscriber is absent: the handset is switched off or out of coverage.
+
+**21**
+ The message expired after the network gave up retrying delivery.
+
+**22**
+ A mobile network component failed, or a service centre was congested.
+
+**30**
+ ASPSMS is unavailable, timed out, or reported a transmission error.
+
+**31**
+ ASPSMS rejected the request, for instance because the message exceeded the
+ maximum length or a parameter was invalid.
+
+**40**
+ **ASPSMS_USERKEY** or **ASPSMS_PASSWORD** is not set, or the helper was
+ invoked with the wrong number of arguments.
+
+**41**
+ ASPSMS refused the credentials, denied access to the account, or the
+ configured originator is not authorized.
+
+**42**
+ The pre-paid ASPSMS account has insufficient credits.
+
+**50**
+ The delivery report carried a reason code that could not be classified.
+
+ASPSMS documents no rate limit and no rate-limit code, so status 32 is never
+reported by this helper.
+
+
+See Also
+========
+
+challenger-send-sms(1), challenger-send-sms-clicksend(1),
+challenger-send-sms-telesign(1), challenger-httpd(1), challenger.conf(5).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/challenger-send-sms-clicksend.1.rst b/manpages/challenger-send-sms-clicksend.1.rst
@@ -0,0 +1,141 @@
+challenger-send-sms-clicksend(1)
+################################
+
+.. only:: html
+
+ Name
+ ====
+
+ **challenger-send-sms-clicksend** - transmit a Challenger TAN by SMS via ClickSend
+
+
+Synopsis
+========
+
+**challenger-send-sms-clicksend** *PHONE_NUMBER*
+
+
+Description
+===========
+
+**challenger-send-sms-clicksend** transmits a TAN to a mobile phone number using
+the ClickSend v3 SMS API.
+
+It is normally invoked by challenger-send-sms(1) as one provider in a fallback
+chain, and not directly. Its calling convention differs from that of the
+dispatcher: *PHONE_NUMBER* is the **bare phone number**, already extracted from
+the address object and already checked for general E.164 form. The message to
+transmit, including the TAN, is read from **standard input**.
+
+ClickSend reports per-message outcomes in the response body rather than in the
+HTTP status, and its documentation states explicitly that the HTTP status does
+not reflect the status of an individual message. A successful submission
+therefore only means the message was **queued**; delivery is confirmed
+separately by polling, for a bounded period. A message still in flight when the
+polling window closes is reported as accepted, not as a failure.
+
+ClickSend validates the number format and prefix before submitting to the
+network. A number failing either check is reported immediately, is never sent,
+and is not charged for. This makes ClickSend the most reliable of the
+configured providers for detecting an unusable number, though it does not
+distinguish a number that is too short from one that is too long.
+
+ClickSend suppresses a message whose body is identical to one recently sent to
+the same recipient. Because the suppressed message is by definition identical to
+one already accepted, the TAN will still reach the user, and this is reported as
+a success.
+
+Delivery failures are all reported under a single status code, with the
+distinguishing information carried only in accompanying free text whose wording
+ClickSend does not guarantee to be stable. A failure whose text is not
+recognised is therefore reported as unclassified rather than guessed at.
+
+
+Environment
+===========
+
+**CLICKSEND_USERNAME**
+ ClickSend account username. Required.
+
+**CLICKSEND_API_KEY**
+ ClickSend API key. Required.
+
+The helper fails with status 40 if either is unset or empty. Credentials are
+taken from the environment of the invoking daemon, never from a configuration
+file.
+
+
+Exit Status
+===========
+
+An exit status below 10 means the TAN was transmitted, or will be. Any other
+status means it was not. The subset below is what this helper can actually
+report; see challenger-send-sms(1) for the full table.
+
+**0**
+ Delivery to the handset was confirmed.
+
+**1**
+ ClickSend queued the message but delivery was not confirmed within the
+ polling window.
+
+**2**
+ The message was suppressed as a duplicate of one recently sent to the same
+ recipient. The earlier copy carries the same TAN and is in flight.
+
+**14**
+ The number is invalid: it failed ClickSend's format or prefix check, or the
+ network reported an unknown, unidentified or illegal subscriber.
+
+**15**
+ The message was blocked: stopped by ClickSend's compliance review, rejected
+ by a network anti-spam filter, or sent to a country or sender identity not
+ enabled on the account.
+
+**20**
+ The subscriber is absent, or the handset has insufficient memory to accept
+ the message.
+
+**21**
+ The delivery receipt expired before a final status was reported.
+
+**22**
+ The recipient network rejected the message, was congested, timed out, or
+ could not route it.
+
+**30**
+ ClickSend is unavailable or reported an internal error.
+
+**31**
+ ClickSend rejected the request as malformed or incomplete.
+
+**32**
+ A ClickSend rate limit was exceeded.
+
+**40**
+ **CLICKSEND_USERNAME** or **CLICKSEND_API_KEY** is not set, or the helper was
+ invoked with the wrong number of arguments.
+
+**41**
+ ClickSend refused the credentials, or the account is not activated.
+
+**42**
+ The ClickSend account is out of message credits.
+
+**50**
+ Delivery failed for a reason ClickSend did not report in a form that could be
+ classified.
+
+
+See Also
+========
+
+challenger-send-sms(1), challenger-send-sms-aspsms(1),
+challenger-send-sms-telesign(1), challenger-httpd(1), challenger.conf(5).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/challenger-send-sms-telesign.1.rst b/manpages/challenger-send-sms-telesign.1.rst
@@ -0,0 +1,127 @@
+challenger-send-sms-telesign(1)
+###############################
+
+.. only:: html
+
+ Name
+ ====
+
+ **challenger-send-sms-telesign** - transmit a Challenger TAN by SMS via Telesign
+
+
+Synopsis
+========
+
+**challenger-send-sms-telesign** *PHONE_NUMBER*
+
+
+Description
+===========
+
+**challenger-send-sms-telesign** transmits a TAN to a mobile phone number using
+the Telesign Messaging API.
+
+It is normally invoked by challenger-send-sms(1) as one provider in a fallback
+chain, and not directly. Its calling convention differs from that of the
+dispatcher: *PHONE_NUMBER* is the **bare phone number**, already extracted from
+the address object and already checked for general E.164 form. The message to
+transmit, including the TAN, is read from **standard input**.
+
+The message is submitted to the Telesign messaging endpoint. Telesign accepts a
+message for delivery without confirming that it reached the handset, so the
+delivery status is then polled for a bounded period. A message still in flight
+when the polling window closes is reported as accepted, not as a failure.
+
+Telesign reports the outcome in the ``status.code`` field of the response body,
+for successful and unsuccessful requests alike, and its documentation directs
+callers to use that field in preference to the HTTP status. A malformed number
+is reported as ``11000`` with an HTTP status of 400, so the response body must
+be retained even when the HTTP request is unsuccessful.
+
+Telesign does not distinguish a number that is too short from one that is too
+long; both are reported as ``11000``. Detecting that a number belongs to a
+landline or VoIP service requires Telesign's separate PhoneID product and is not
+attempted here.
+
+
+Environment
+===========
+
+**TELESIGN_AUTH_TOKEN**
+ Basic authentication token for the Telesign REST API. Required. The helper
+ fails with status 40 if it is unset or empty.
+
+Credentials are taken from the environment of the invoking daemon, never from a
+configuration file.
+
+
+Exit Status
+===========
+
+An exit status below 10 means the TAN was transmitted, or will be. Any other
+status means it was not. The subset below is what this helper can actually
+report; see challenger-send-sms(1) for the full table.
+
+**0**
+ Delivery to the handset was confirmed.
+
+**1**
+ Telesign accepted the message but delivery was not confirmed within the
+ polling window, or Telesign reported that the final status is unknown.
+
+**13**
+ SMS is not supported by this phone, carrier or subscription.
+
+**14**
+ The number is invalid, unallocated, or the subscriber is unknown.
+
+**15**
+ The message was blocked: by a rule configured on the Telesign account, by
+ Telesign's global blocklist, by a carrier spam filter, or by the subscriber.
+
+**20**
+ The subscriber is absent: the handset is switched off, out of coverage, or
+ roaming.
+
+**21**
+ The message expired in the mobile provider's queue before delivery.
+
+**22**
+ The carrier or mobile operator rejected the message or failed.
+
+**30**
+ Telesign, or a Telesign delivery partner, is unavailable or reported an
+ internal error.
+
+**31**
+ Telesign rejected the request as malformed or unsupported.
+
+**32**
+ A Telesign rate limit or transaction cap was exceeded.
+
+**40**
+ **TELESIGN_AUTH_TOKEN** is not set, or the helper was invoked with the wrong
+ number of arguments.
+
+**41**
+ Telesign refused the credentials, or the account is suspended.
+
+**42**
+ The pre-paid Telesign wallet has insufficient funds.
+
+**50**
+ Telesign reported a status that could not be classified.
+
+
+See Also
+========
+
+challenger-send-sms(1), challenger-send-sms-aspsms(1),
+challenger-send-sms-clicksend(1), challenger-httpd(1), challenger.conf(5).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/challenger-send-sms.1.rst b/manpages/challenger-send-sms.1.rst
@@ -0,0 +1,165 @@
+challenger-send-sms(1)
+######################
+
+.. only:: html
+
+ Name
+ ====
+
+ **challenger-send-sms** - transmit a Challenger TAN by SMS
+
+
+Synopsis
+========
+
+**challenger-send-sms** *ADDRESS*
+
+
+Description
+===========
+
+**challenger-send-sms** transmits a TAN to a mobile phone number. It is not
+itself an SMS sender: it validates the number, then tries each installed
+provider helper in turn until one of them accepts the message.
+
+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 field
+consulted is ``CONTACT_PHONE``, and its name derives from the
+``enter-$ADDRESS_TYPE-form`` template on the Challenger side; an address object
+without that field is rejected.
+
+The message to transmit — including the TAN itself — 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**, so that it does not
+appear in the process table.
+
+Standard error is inherited from the invoking daemon and is used for
+diagnostics.
+
+Before contacting any provider, the number is checked against the general
+E.164 form: a leading ``+`` followed by 7 to 15 digits. This is deliberately a
+generic check. It rejects grossly malformed input such as ``+41`` without
+consulting a provider, but it cannot enforce per-country lengths, so a number
+that is merely one digit short or long, or that has a transposed digit, is
+passed on and will be reported by whichever provider first classifies it.
+
+Providers are resolved by name from the directory holding
+**challenger-send-sms** itself, as ``challenger-send-sms-``\ *PROVIDER*, and are
+tried in the order ``telesign``, ``clicksend``, ``aspsms``. A provider whose
+helper is absent or not executable is skipped silently.
+
+Whether a failing provider causes the next one to be tried depends on the class
+of the failure. An address that one provider rejects will be rejected by all of
+them, so such a failure is reported immediately; a provider that is
+misconfigured, out of credit, rate limited or down does not prevent another
+provider from succeeding, so those cause a fall-through.
+
+If every provider has been tried without success, the most actionable code seen
+is reported, preferring address errors, then recipient errors, then
+configuration errors, then provider errors.
+
+
+Environment
+===========
+
+**challenger-send-sms** itself reads no environment variables, but the provider
+helpers it invokes require credentials to be present in the environment of the
+invoking daemon. See challenger-send-sms-telesign(1),
+challenger-send-sms-clicksend(1) and challenger-send-sms-aspsms(1).
+
+
+Exit Status
+===========
+
+An exit status below 10 means the TAN was transmitted, or will be. Any other
+status means it was not.
+
+**0**
+ The TAN was delivered and receipt on the handset was confirmed.
+
+**1**
+ A provider accepted the TAN for delivery, but delivery was not confirmed
+ within the polling window. This is a success: the message is in flight.
+
+**2**
+ A provider suppressed the message as a duplicate, because an identical
+ message was recently accepted for the same recipient. The earlier copy is in
+ flight, so this too is a success.
+
+**10**
+ The address is malformed: the ``CONTACT_PHONE`` field is missing, or its
+ value is not of the form ``+`` followed by digits.
+
+**11**
+ The phone number is too short.
+
+**12**
+ The phone number is too long.
+
+**13**
+ The number is not a mobile subscription. Reported only on a best-effort
+ basis; most providers cannot make this distinction.
+
+**14**
+ The number is syntactically plausible but unallocated, or the subscriber is
+ unknown. This is the status reported for a number with a missing, extra or
+ transposed digit that the local check cannot catch.
+
+**15**
+ Delivery to this number is blocked, barred, or the number is on a blocklist.
+
+**20**
+ The handset is switched off or out of coverage.
+
+**21**
+ The message expired before it could be delivered to the handset.
+
+**22**
+ The mobile operator or an intermediate carrier failed.
+
+**30**
+ The SMS provider is down or reported an internal error.
+
+**31**
+ The SMS provider rejected the request.
+
+**32**
+ A provider rate limit was exceeded.
+
+**33**
+ No verdict: the outcome of the submission could not be determined.
+
+**40**
+ Local configuration or invocation error: a required credential is absent
+ from the environment, or the helper was called with the wrong arguments.
+
+**41**
+ A provider refused the configured credentials.
+
+**42**
+ A provider account has insufficient balance. All supported providers are
+ pre-paid.
+
+**50**
+ The transmission failed for a reason that could not be classified.
+
+
+See Also
+========
+
+challenger-send-sms-aspsms(1), challenger-send-sms-clicksend(1),
+challenger-send-sms-telesign(1), challenger-send-email(1),
+challenger-send-post(1), challenger-httpd(1), challenger.conf(5).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/challenger.conf.5.rst b/manpages/challenger.conf.5.rst
@@ -70,7 +70,7 @@ TOKEN_EXPIRATION
Optional, defaults to 1 hour if not given.
PIN_RETRANSMISSION_FREQUENCY
- Minimum time that must pass before the same challenge code (PIN/TAN) is (re)transmitted to the same address again. Users may ask the challenger to re-send the challenge, but such requests are ignored if the last transmission happened more recently than this. Should be (much) smaller than ``VALIDATION_DURATION``. Optional, defaults to 5 minutes if not given.
+ Minimum time that must pass before the same challenge code (TAN) is (re)transmitted to the same address again. Users may ask the challenger to re-send the challenge, but such requests are ignored if the last transmission happened more recently than this. Should be (much) smaller than ``VALIDATION_DURATION``. Optional, defaults to 5 minutes if not given.
AUTH_COMMAND
Which command should we execute to transmit the challenge code to the address. The address is given as the first argument, while the message to send is provided on stdin. Templates (possibly without the necessary credentials) for such commands are provided as challenger-send-email.sh, challenger-send-post.sh and challenger-send-sms.sh.
@@ -85,7 +85,7 @@ ADDRESS_RESTRICTIONS
JSON object with a map of keys (names of the fields of the address to be entered by the user) to objects with a "regex" (string) containing an extended Posix regular expression for allowed address field values, and a "hint"/"hint_i18n" giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. Examples would be '{"email":{"hint":"valid e-mail address required","regex":"^[a-zA-Z0-9\_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"}' or '{"zip":{"hint":"numeric zip code required","regex":"^[0-9]+$"}'.
MESSAGE_TEMPLATE_FILE
- Name of a file with a Mustach template to use to generate the challenge message for the customer. The template will be provided the PIN/TAN under ``{{pin}}``, the customer's address in JSON format under ``{{address}}`` and the URL of the challenger backend under ``{{challenger_url}}``.
+ Name of a file with a Mustach template to use to generate the challenge message for the customer. The template will be provided the TAN under ``{{pin}}``, the customer's address in JSON format under ``{{address}}`` and the URL of the challenger backend under ``{{challenger_url}}``.
BASE_URL
The base URL under which the challenger can be reached.
