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: false or paid: true → forward to NEXT_STAGE (an explicit classification overrides the payment flow).

  • paid: false present → 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 no BOUNCE_STAGE is wired;

    • unpaid but still before the deadline → with DELAY_DSN_AFTER set, this is the delay checkpoint: e-mail the sender a one-shot delayed DSN (RFC 3461, only if they asked for NOTIFY=DELAY) without releasing the message, then re-pause until PAYMENT_DEADLINE; otherwise re-pause until the deadline with a warning (should not happen). The row stays paused, never pending, which would busy-loop against the early wake-up.

  • no paid field, but the message is one that this deployment injected itself → forward to NEXT_STAGE without 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 a Pepsi-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 paid field → create a v1 order priced by ORDER_CHOICES (order_id is the message token), pause until PAYMENT_DEADLINE (or until the DELAY_DSN_AFTER checkpoint when that falls earlier), recording paid: false and pay_deadline in state, 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 (recipient notify/orcpt).

  • Outputs: on the first encounter, {paid: false, pay_deadline} merged into state, the row paused, and a payment-request reply injected at BLOCK_RESPONSE_STAGE; delay_sent: true once a delay DSN has gone out; last_error while the merchant is unavailable; on rejection, a state.bounce object (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).