95.1.18. pepsi-stage-auto-pay¶
pay GNU Taler delivery demands automatically
- Manual section:
1
95.1.18.1.1. Name¶
pepsi-stage-auto-pay - the automatic pay-to-send settlement stage of the Pepsi pipeline.
95.1.18.1.2. Synopsis¶
pepsi-stage-auto-pay [GLOBAL-OPTIONS] worker
95.1.18.1.3. Description¶
pepsi-stage-auto-pay is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. It has two roles, chosen per message:
On the inbound path it is the sending counterpart to pepsi-stage-anti-spam(1): when mail that this site relayed is held at the far end behind a pay-to-send gate, that gate e-mails the original sender a payment demand, and this stage detects such demands and settles them automatically, so the held message is released and delivered.
On the submission path it is a wallet self-service endpoint: a locally submitted (authenticated) message addressed to the wallet control address lets the sender operate their own GNU Taler wallet by e-mail: check a balance, top it up, accept a peer push payment, or initiate a peer pull request. This role is enabled only when RESPONSE_STAGE is configured (see Wallet self-service below).
The two roles share one binary and are auto-detected, so a single
PROGRAM = pepsi-stage-auto-pay may be placed on either pipeline (or both, as two
[stage-<name>] sections).
A demand is recognised by the Taler: header that pepsi-stage-anti-spam(1)
adds to its payment-request auto-reply, carrying one or more taler://pay/…
URIs. Only taler://pay/ URIs are ever settled, and a URI repeated across the
header(s) counts once. Any other taler:// scheme in that header is ignored,
such as a pay-pull or withdraw URI, which could be used to drain the
wallet. A
message with no Taler: header is ordinary mail and is forwarded to
NEXT_STAGE untouched, so the stage is safe to place early on the inbound path.
Pepsi only pays for mail it provably originated. The same auto-reply echoes the
original message’s Pepsi-Origin: proof-of-origin header (see
pepsi-stage-anti-spam(1) and pepsi-stage-relay-to-internet(1)). This
stage verifies it the same way a returning bounce is verified: the HMAC must
check against our secret and the nonce must still be tracked in
pepsi.origin_nonce. A demand that carries no valid proof (including every
demand when [pepsi-origin] is not configured) is never paid: it is
forwarded to NEXT_STAGE unchanged.
Warning
The header authenticates the deployment, not the individual bounce. It is
stamped on the message that is delivered, so every recipient of that message
holds a valid copy of it, and verification is an HMAC check plus an
existence check of the nonce. The nonce is not consumed, not limited to one
use, and not bound to the message for which it was minted. Any recipient can
therefore replay the header on a message of their own for the rest of the
nonce’s validity window (14 days) and have this stage treat the Taler:
demands they attach as demands about mail we originated. MAX_TOTAL is the
only bound on what that costs, and it is per nonce, so set it to an amount you
are willing to lose per outbound message, not per pipeline.
The proof also names the account for which the original message was sent, and that
account is the only one whose wallet may settle the demand: the demand’s envelope
recipient must be that same account, compared case-insensitively. This binding is
what makes the proof mean anything about who pays. On its own, the proof says
only that this deployment sent some message under that nonce, and every
correspondent who has ever received Pepsi-relayed mail holds a valid,
still-tracked copy of such a header. Without the binding, a demand carrying
somebody else’s Pepsi-Origin and addressed to a different local user would
be settled out of that user’s wallet. A demand whose recipient is not the
account named is forwarded to NEXT_STAGE unpaid. (Note that this also means
that forwarded third-party mail, whose envelope sender was SRS-rewritten before
relay, draws no automatic payment: the proof names the rewritten address, not
the recipient to whom the bounce comes back.)
For a verified demand, the stage processes each taler://pay/… URI in turn,
driving the wallet through the privileged pepsi-helper-auto-pay(1) helper:
quote its price (the helper’s
previewoperation reads the order’s contract terms without paying);book it against a cumulative budget for the original message, capped by MAX_TOTAL, and against the paying wallet’s budget for the last 24 hours, capped by MAX_TOTAL_PER_DAY (when set); and
if it fits under both, settle it (the helper’s
payoperation spends wallet coins).
Every helper invocation is bounded (five minutes; the child is killed if it
runs over) and a timeout counts as a failure, so the demand goes unpaid and the
bounce is forwarded. A payment that timed out may nonetheless have gone
through, which nothing here can tell; it is logged as an error saying so. The
bound exists because the merchant backend that a demand names
is chosen by whoever wrote the Taler: header: an unbounded wallet command would
leave the row running with its worker unable to take another message, and
PARALLELISM such demands would stop the stage, including the wallet
self-service role if it shares the section.
The budget is keyed on the Pepsi-Origin nonce, which identifies the original
outbound message. A message fanned out to a mailing list draws several demands,
one per member whose site charges, and they all carry the same nonce. They
therefore share one budget: the per-message ledger in pepsi.origin_nonce.amount is
advanced atomically as each demand is settled (the auto_pay_try_spend function),
and a demand that would push the running total past MAX_TOTAL is refused. The
cap is single-currency: a demand whose currency differs from MAX_TOTAL is
not paid. The operator can give one account a different cap with
pepsi-settings(1) (the override applies to mail addressed to that account,
that is, to the original sender, who receives the demand), but an account cannot
change its own: pepsi-stage-edit-settings(1) refuses MAX_TOTAL and
MAX_TOTAL_PER_DAY in an e-mailed override however permissive its
EDITABLE_STAGES is, because the control message is authenticated by the
same submission password whose theft the limits bound. The options that select
the paying wallet (WALLET_MODE, WALLET_SCOPE, WALLET_USER) are
refused there too, so an account cannot move its demands onto a wallet shared
with other users. UNRESTRICTED_UNSAFE_STAGES on the edit stage lifts both
refusals.
The daily budget. MAX_TOTAL_PER_DAY bounds what one wallet spends
on demands in any 24 hours, however many original messages they are spread
over. It is metered per wallet because the wallet is the one thing the stage
always knows: under WALLET_MODE local-user each user’s own wallet; under
shared with WALLET_SCOPE per-sender each sender’s wallet database;
under unified the one wallet everybody shares, so the limit is then the
whole deployment’s. It is deliberately not per correspondent: mailing lists
and aliases mean the stage never knows for sure who is demanding. Every booking
is recorded in pepsi.auto_pay_spend by the same auto_pay_try_spend call
that advances the per-message ledger. Both checks and both writes happen in one
statement, serialised per wallet, so concurrent demands for different
messages cannot together pass the limit either, and a demand refused by either
budget books nothing against the other. The window is rolling, not a calendar
day (which would allow twice the limit across midnight), and rows that have left
it are pruned by the same function. The limit is single-currency and must be in
MAX_TOTAL’s currency. It is required whenever MAX_TOTAL is not zero:
a section with a non-zero MAX_TOTAL and no MAX_TOTAL_PER_DAY makes the
worker refuse to start, and pepsi-setup(1) validate refuses it, since
without it a stolen submission password drains the wallet at MAX_TOTAL per
message the thief sends behind a pay-to-send gate of their own. A stage that
pays nothing (MAX_TOTAL = EUR:0, the self-service role alone) needs none.
What MAX_TOTAL does and does not bound. The far end alone chooses the
Taler: header, with the merchant host, the order id and therefore the price,
and nothing covers it: the Pepsi-Origin MAC binds the version, our hostname, the
originating account, the nonce and a timestamp, and so proves only that this
deployment sent a message under this nonce for this account. It does not bind the
demand, the merchant, or an amount. Every correspondent obtains a valid, 14-day-live
proof simply by reading the mail you sent them, so a correspondent can always
present a self-priced demand for up to MAX_TOTAL and be paid. MAX_TOTAL is
therefore a bound per original message, not per correspondent and not per period:
total exposure to one determined correspondent scales with how many messages you
have sent them. Set it to a sum you are willing to pay for a single delivery, and
set MAX_TOTAL_PER_DAY to what a wallet may lose in a day when every
correspondent holding a proof cashes it in. That is the spend limit.
When every demand on a message has been settled, the now-redundant bounce is
discarded (the row is deleted). If any demand cannot be priced, would exceed
either budget, or differs in currency, the message is instead forwarded to
NEXT_STAGE, so it proceeds as an ordinary bounce and the original sender is
informed of the delivery problem as usual. A demand that was booked under the
budget but then fails to pay is rolled back, and the message is likewise
forwarded, with the error logged. The auto_pay_refund function refunds the
reservation to the per-message ledger and deletes its booking from the daily
one, so the failed, unspent payment consumes neither budget. Auto-pay
tries to pay; if it cannot, it does nothing and lets the bounce through.
The exception is a helper that cannot be started at all (a missing binary, a lost setuid bit): that is a fault of the host, not of the demand, so before any demand of the message has been paid the message is retried rather than let through, and auto-pay does not silently stop paying. Once a demand has been paid, no error on the same message is retried, because a retry would quote, book and pay the settled demands a second time. The bounce is then forwarded with the error logged.
95.1.18.1.4. Wallet account¶
The wallet the helper pays from is chosen by WALLET_MODE:
- local-user
The helper drops to the paying account’s own local login and uses that user’s default wallet. The paying account is the one that the verified
Pepsi-Originnames, which is also the demand’s envelope recipient (the original sender). It must resolve to a permitted local account (the same LOCAL_DOMAINS/TARGETS/RECIPIENT_DELIMITER test as pepsi-stage-relay-to-maildir(1)); a non-local account cannot be charged and the message is forwarded. The helper refuses a uid below/etc/login.defsUID_MINin this mode, and pepsi-setup(1) warns about a TARGETS token that reaches below it.- shared (default)
The helper drops to a single dedicated account (WALLET_USER, default
pepsi-wallets) whose home holds the wallet database(s). WALLET_SCOPE selects whether each original sender gets its own wallet database (per-sender, the default) or everyone shares one (unified, for example for a business where individual wallets make no sense).
All wallet interaction is performed by the setuid-root pepsi-helper-auto-pay(1)
helper; this stage spawns it and never touches a wallet directly. The stage binary
is therefore installed SGID pepsi-wallets so its unprivileged dispatcher
worker may exec the helper (see Installation).
95.1.18.1.5. Wallet self-service¶
When RESPONSE_STAGE is set, a locally-originated message addressed to
<CONTROL_LOCAL_PART>@<served-domain> is a wallet-control message, which
operates the sender’s own wallet. A locally-originated message has
state.local_origin true; the submission listener must authenticate and bind
the envelope sender. The default local part is pepsi-wallet, and the domain
is one of [pepsi-ingress] ACCEPTED_DOMAINS. The wallet is resolved by
WALLET_MODE/WALLET_SCOPE exactly as for the paying role, but keyed on the
sender. Any other message is forwarded to NEXT_STAGE untouched, so the stage is
safe to place anywhere on the submission path. A control message that also has
ordinary recipients is split first: the control address moves to a row of its
own, and the others continue as ordinary mail.
The command is taken from the message Subject: line: one verb plus its arguments (the verb is case-insensitive):
balanceReport the wallet balance.
withdrawCURRENCY:VALUE EXCHANGE-URL (also spelttopup/top-up)Set up a manual top-up of the given amount against the GNU Taler exchange at the given base URL (which must be an
http://orhttps://URL). The exchange is named in the request (not configured on the server) because a wallet is multi-currency and can withdraw from many exchanges. The reply carries the bankpayto://target and the wire-transfer subject to use; once the user’s bank transfer arrives, the funds appear in the wallet.pullCURRENCY:VALUE [subject]Initiate a peer pull payment; the rest of the Subject line, if any, becomes the payment subject. The reply carries a
taler://pay-pull/…URI to forward to whoever should pay.pushtaler://pay-push/… (also speltaccept)Accept an incoming peer push payment. The URI may be given in the Subject or in the message body.
helpReply with the usage instructions. An empty Subject, an unknown verb, or a missing or malformed argument gets the same reply.
When the sender resolves to no wallet at all (WALLET_MODE = local-user and a
sender that is not a permitted local account), nothing is run and the reply says
so.
The result is mailed back to the sender as a localised auto-reply (null sender,
Auto-Submitted: auto-replied), built from the operator-customisable
wallet.<lang>.body template and injected at RESPONSE_STAGE (where it is
DKIM-signed and relayed); the original control message is then deleted. A request
that cannot be understood is answered with usage instructions. A request that
was understood but failed is answered with a fixed “could not be completed”
message: the wallet’s own diagnostic goes to the operator log only, since it
describes a wallet (shared by everyone under WALLET_SCOPE = unified) rather
than the request.
The reply template is rendered once before the wallet command runs, so a missing template is retried with the wallet untouched. Once the command has run it is never run again for the same message: a reply that then cannot be rendered or queued is logged as an error and the request deleted.
If the wallet hits a KYC (identity-verification) requirement, the reply instead carries the KYC link for the user to open. This happens only for the self-service role, never while paying inbound demands.
95.1.18.1.6. Configuration¶
Options live in the stage’s own [stage-<name>] section
(PROGRAM = pepsi-stage-auto-pay): the required MAX_TOTAL (a GNU Taler
amount CURRENCY:VALUE bounding total spend per original message),
MAX_TOTAL_PER_DAY (the same currency, bounding one wallet’s spend in any 24
hours; required unless MAX_TOTAL is zero), a required
NEXT_STAGE, and the wallet knobs WALLET_MODE, WALLET_USER,
WALLET_SCOPE, WALLET_PAY_OPTIONS and HELPER. The wallet
self-service role adds RESPONSE_STAGE (its presence enables the role),
CONTROL_LOCAL_PART, RESPONSE_FROM and RESPONSE_SUBJECT (a withdraw
names its own exchange base URL in the Subject, so no exchange is configured).
They are documented in pepsi.conf(5). The
proof-of-origin secret is the shared [pepsi-origin] section (see
pepsi-stage-relay-to-internet(1)); without it the stage can verify no demand
and therefore pays none (it does not affect self-service).
95.1.18.1.7. Installation¶
Because the stage execs the setuid-root wallet helper, its binary is installed
standalone (not folded into the unified pepsi binary) and SGID
pepsi-wallets, with mode 2550 and owner pepsi:pepsi-wallets. The
mode grants owner-execute and not world-execute, because the setgid bit is the
gate on the helper; pepsi is deliberately not a member of the group, so the
exec right has to come from the owner bits. The helper is installed setuid-root,
root:pepsi-wallets, mode 4750. make install (targets
install-auto-pay-stage / install-auto-pay-helper) and the Debian package
apply these bits. The pepsi-wallets account and group are created by the
package; create them by hand otherwise.
Because the setgid bit is that gate, the program enforces the same rule itself
when the binary actually carries the bit. Unless the real user is root or
the pepsi service account, it exits with an error before any configuration
is read. Like the setuid crypto stages, it also strips the environment variables
that steer configuration loading (HOME, XDG_CONFIG_HOME, PG*,
TALER_*, PEPSI_*) and pins PATH to a safe default. (A build
installed without the setgid bit, such as a development tree or make check,
gained nothing and skips both steps.) The file mode is set by the deployment,
and this check is part of the program; neither has to give the protection on
its own.
95.1.18.1.8. State¶
Inputs: the Taler: and Pepsi-Origin: headers of the message (the body
is also scanned for an embedded Pepsi-Origin); for self-service,
state.local_origin (which marks a control message) and state.language
(the reply language, English when absent). The per-message spend ledger is
pepsi.origin_nonce.amount and the per-wallet daily one pepsi.auto_pay_spend,
not the message state.
Outputs: the stage does not modify the message; it advances or deletes it. The state layout is described in pepsi.state(7).
Transitions: finish (delete) when all demands are settled, or for a wallet
self-service control message (after injecting the reply at RESPONSE_STAGE);
back to this stage, on two rows, for a control message that has other recipients;
otherwise advance to NEXT_STAGE (not a demand, unverifiable, unpriceable,
over budget, or a settlement failure). The stage never pauses, bounces or rewrites a
message.
95.1.18.1.9. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.
95.1.18.1.10. Global Options¶
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations.
- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity (default
[pepsi] LOG, elseinfo).- -v, –verbose
Show log messages from all sources.
- -h, –help; -V, –version
Print a usage summary / the version and exit.
95.1.18.1.11. Exit Status¶
The outcome of each message is reported to pepsi-dispatch(1) on the
worker’s status line, not as the exit status. A message that is not
running, or a per-address setting that breaks the stage’s section, fails
that message; a fault of the host (the database, a template or helper that
cannot be used) is not a failure: the message is paused and retried, as
Stage errors in pepsi-dispatch(1) describes.
- 0
The worker ran until its standard input was closed.
- 1
A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.
- 78
The worker refused to start: a
[stage-*]section it serves does not parse (e.g. a missing MAX_TOTAL, or a non-zero one without MAX_TOTAL_PER_DAY). The dispatcher requeues what it handed over and retries the stage later.
95.1.18.1.12. Examples¶
A pipeline section that pays delivery demands for locally-originated mail, up to
five euro per original message and fifty a day in all, from a single shared
pepsi-wallets wallet:
[stage-auto-pay]
PROGRAM = pepsi-stage-auto-pay
MAX_TOTAL = EUR:5
MAX_TOTAL_PER_DAY = EUR:50
NEXT_STAGE = local-delivery
WALLET_MODE = shared
WALLET_SCOPE = unified
Or, paying from each original sender’s own local wallet:
[stage-auto-pay]
PROGRAM = pepsi-stage-auto-pay
MAX_TOTAL = EUR:5
MAX_TOTAL_PER_DAY = EUR:20
NEXT_STAGE = local-delivery
WALLET_MODE = local-user
Letting one account spend more (set by the operator; an account cannot raise its own limits by e-mail):
pepsi-settings -c /etc/pepsi/pepsi.conf set alice@example.com auto-pay MAX_TOTAL EUR:20
A wallet self-service section on the submission path (a message to
pepsi-wallet@example.com with a command in the Subject operates the sender’s
wallet):
[stage-wallet]
PROGRAM = pepsi-stage-auto-pay
MAX_TOTAL = EUR:0
MAX_TOTAL_PER_DAY = EUR:0
NEXT_STAGE = dkim-sign
RESPONSE_STAGE = dkim-sign
CONTROL_LOCAL_PART = pepsi-wallet
95.1.18.1.13. See Also¶
pepsi-helper-auto-pay(1), pepsi-stage-anti-spam(1), pepsi-stage-relay-to-internet(1), pepsi-stage-edit-settings(1), pepsi-config(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
The manual’s Threat model chapter (assets, the remote-sender and availability sections) states what automatic payment may cost; its Security model chapter (The privilege split, Resource limits) describes the setgid gate, the helper and the two budgets.
95.1.18.1.14. Bugs¶
Report bugs to the Pepsi issue tracker.