48. pepsi-stage-anti-spam¶
Gate a message behind a GNU Taler payment (pay-to-send).
48.1. Role¶
pepsi-stage-anti-spam requires a GNU Taler payment for an
otherwise-unclassified message before it may continue down the pipeline. On first
sight it creates a merchant order and pauses the message. When the message is
woken again, the stage forwards it, rejects it or lets it wait. Two things wake
it: the pepsi-resume merchant webhook, which pepsi-setup provisions on
the Taler backend to call POST /resume on pepsi-httpd, and the
deadline running out. Reference: pepsi-stage-anti-spam(1).
48.2. Decision¶
The message’s state JSON decides:
spam: true→ drop (delete the row).spam: falseorpaid: true→ forward toNEXT_STAGE(an explicit classification overrides the payment flow).paid: falsepresent → ask the merchant whether the order is paid:paid → forward to
NEXT_STAGE;unpaid past the stored deadline → reject: reroute to
BOUNCE_STAGE(a pepsi-stage-bounce rejection DSN, or a pepsi-stage-discard silent drop), or delete when noBOUNCE_STAGEis wired;unpaid but still before the deadline → with
DELAY_DSN_AFTERset, this is the delay checkpoint: e-mail the sender a one-shot delayed DSN (RFC 3461, only if they asked forNOTIFY=DELAY) without releasing the message, then re-pause untilPAYMENT_DEADLINE; otherwise re-pause until the deadline with a warning (should not happen). The row stayspaused, neverpending, which would busy-loop against the early wake-up.
no
paidfield, but the message is one that this deployment injected itself → forward toNEXT_STAGEwithout an order. Such a message is either a reply composed in the secure-link portal (state.secure_link.reply), or a message whose own header block carries aPepsi-Origin:stamp that was minted for injected mail and also binds the envelope recipients (for=) under the HMAC. The stamp must verify and name every envelope recipient of the row, and its nonce must still be tracked. These are the secure-link notifications coming back in through this deployment’s MX. An ordinary outbound stamp never exempts a message, since every recipient of our mail holds one; a stamp quoted in a body or an attached message does not count either.no
paidfield → create a v1 order priced byORDER_CHOICES(order_idis the message token), pause untilPAYMENT_DEADLINE(or until theDELAY_DSN_AFTERcheckpoint when that falls earlier), recordingpaid: falseandpay_deadlineinstate, and e-mail the sender a payment request (see below). The exception is a sender that failed SPF or DMARC outright (fail). Such a sender is never sent the request, so nobody could pay; the message therefore gets no order and is rejected as unpaid at once (BOUNCE_STAGE, else deleted) rather than held for two days in the merchant’s order table and the queue (Resource exhaustion of a postage quota enforcer).
The deadline is kept in state.pay_deadline because the dispatcher clears the
row’s timeout when it requeues a paused message.
A message with the null envelope sender (a bounce or auto-reply) is never
gated: the stage instead tries to verify it as a reply to mail this deployment
genuinely sent, using the Pepsi-Origin: proof-of-origin header (see
SMTP Protocol Extensions). A bounce whose embedded header verifies is forwarded
to NEXT_STAGE. A bounce with a forged or expired header is unverifiable, and
so is any bounce when proof-of-origin is unconfigured. An unverifiable bounce
is routed to BOUNCE_TARGET_STAGE when one is configured, and forwarded to
NEXT_STAGE unchanged, past the gate, when it is not. The wizard wires BOUNCE_TARGET_STAGE = discard-rejected
(a pepsi-stage-discard sink that it also emits), so a forged bounce is dropped
rather than delivered; a site that wants to review the legitimate bounces that
cannot be verified either points the option at a quarantine stage instead.
pepsi-setup warns about a hand-written section without the option.
If the merchant backend cannot be reached or answers with an error, the message
is held: it stays paused with the reason in state.last_error and the
merchant is asked again every five minutes, never past the deadline, which is
fixed at the first attempt. If the merchant still cannot be asked once the
deadline has passed, the stage fails open and forwards the message to
NEXT_STAGE with a warning. An order the merchant does not know (404)
counts as unpaid.
48.3. Payment-request reply¶
After that first pause, the stage originates an auto-reply to the sender when
BLOCK_RESPONSE_STAGE is set. It sends no reply when RFC 3834 says that the
message must not be answered automatically (Auto-Submitted other than
no, Precedence: bulk|list|junk, X-Auto-Response-Suppress, any
List-* field, a service sender such as mailer-daemon or a VERP list
bounce address, a multipart/report), or when REQUIRE_AUTHENTICATED is on
and the sender did not pass SPF or DMARC (softfail, neutral, none
and temporary errors are otherwise answered; a fail gets no order at all, as
above). These are the same shared rules that the vacation responder applies. The
message is held for payment either way; only the prompt is withheld, so the gate
does not turn list traffic and other responders into backscatter. The same holds
within BLOCK_RESPONSE_SUPPRESS (default 1 h) of a previous request to the
same sender for the same protected mailbox: a flood bearing one forged sender
draws one request per window, not one per message. The window is claimed and
recorded in one statement (payment_request_should_send over
pepsi.payment_request_reply, the vacation_should_reply pattern), so
concurrent workers cannot both send. The reply explains that the recipient
requires unknown senders to pay first, and carries the taler://pay/<backend>/<token> URI as a
link and as a QR code (an inline image/png referenced by cid:, so it
renders in the widest range of clients while the message stays self-contained),
the acceptable payment options (the ORDER_CHOICES, omitting token-family
choices), and a pointer to https://wallet.taler.net/ for senders without a
wallet. When the sender passed SPF or DMARC and the original From:
carries a display name, the sender is addressed by it and the subject is
quoted; any other sender gets the request without its own words, since a
forger would otherwise have this host deliver text of their choosing to a third
party (Provider notification workflows send attacker-controlled mail). The body is rendered from the
payment-request.<lang>.body Mustache template under
[pepsi] TEMPLATE_DIR, one chunk per detected language that has a template,
falling back to PAYMENT_MESSAGE_DEFAULT_LANGUAGE (en by default). The reply uses
the null sender <> and enters at BLOCK_RESPONSE_STAGE (normally a
signing/relay chain), so it is signed and delivered like any other mail. The
reply is rendered before the pause; when it cannot be produced (a missing
default-language template, say) the message is held for payment without one and
a warning is logged. Queueing the rendered reply afterwards is best-effort: a
failure is logged, the suppression window claimed for it is given back, and the
pause is never undone.
The reply also carries two machine-readable headers so a sending Pepsi can settle
the demand automatically (see pepsi-stage-auto-pay): a Taler: header
with the taler://pay/… URI, and the original message’s Pepsi-Origin: header
copied verbatim (when present), letting the originating site verify that the
demand is for its own mail and meter its per-message spend.
48.4. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-anti-spam, NEXT_STAGE
(required — a paid message, one classified as not spam and a verified bounce all
go there), BOUNCE_STAGE, ORDER_CHOICES (the verbatim Taler v1 order
choices JSON array, required), PAYMENT_DEADLINE (h/m/s units;
default 2 days), DELAY_DSN_AFTER (h/m/s; optional, send a delayed
DSN mid-window — see above), SUMMARY (default E-mail delivery) and
FULFILLMENT_MESSAGE. For the payment-request reply: BLOCK_RESPONSE_STAGE
(where to inject it; unset disables the reply), BLOCK_RESPONSE_FROM (its
From:; default the original recipient), BLOCK_RESPONSE_SUBJECT,
BLOCK_RESPONSE_SUPPRESS (h/m/s; default 1 h, 0 s answers
every message), REQUIRE_AUTHENTICATED (default off; on, the request goes
only to a sender that passed SPF or DMARC) and
PAYMENT_MESSAGE_DEFAULT_LANGUAGE (default en, and its
payment-request.<lang>.body template must exist — pepsi-setup enforces
that when BLOCK_RESPONSE_STAGE is set). BOUNCE_TARGET_STAGE takes an
unverifiable bounce (the wizard writes discard-rejected); when it is unset
such a bounce is forwarded to NEXT_STAGE unchanged. Requires the shared
[pepsi-payments] merchant backend and, for the resume webhook,
[pepsi-httpd] RESUME_AUTHORIZATION_TOKEN. See
pepsi-stage-anti-spam(1).
48.5. State¶
Inputs:
state.spam/state.paid(booleans),state.pay_deadline(epoch seconds),state.dsn(recipientnotify/orcpt).Outputs: on the first encounter,
{paid: false, pay_deadline}merged intostate, the row paused, and a payment-request reply injected atBLOCK_RESPONSE_STAGE;delay_sent: trueonce a delay DSN has gone out;last_errorwhile the merchant is unavailable; on rejection, astate.bounceobject (permanent) for the bounce stage.
48.6. Security¶
The gate answers an envelope sender that nobody has verified, so the payment request
obeys the shared automatic-reply rules and a per-sender window; the stage is part
of the defences against A remote sender (no backscatter, forged bounces
routed aside) and of the per-sender limits in Availability. The
recipient-bound Pepsi-Origin exemption and its key are covered under
Somebody holding the configuration or a secret: whoever holds the proof-of-origin secret can mint stamps
that pass the gate. Do not list the stage in EDITABLE_STAGES where filtering
is meant to be mandatory (Per-address settings are a trust boundary).
48.7. See also¶
pepsi-stage-bounce, pepsi-stage-discard, pepsi-httpd, pepsi-setup, SMTP Protocol Extensions, pepsi-stage-anti-spam(1).