45. pepsi-stage-auto-pay

Bezahlt GNU-Taler-Zustellforderungen automatisch (die Sendeseite von Pay-to-Send).

45.1. Rolle

pepsi-stage-auto-pay hat zwei automatisch erkannte Rollen. Auf dem eingehenden Pfad ist es das sendende Gegenstück zu pepsi-stage-anti-spam: Wenn von dieser Installation weitergeleitete Mail am fernen Ende hinter einer Pay-to-Send-Schranke zurückgehalten wird, mailt diese Schranke dem ursprünglichen Absender eine Zahlungsforderung, und diese Stage erkennt solche Forderungen und begleicht sie automatisch, sodass die zurückgehaltene Nachricht freigegeben und zugestellt wird. Auf dem Submission-Pfad ist es ein Wallet-Self-Service-Endpunkt (durch RESPONSE_STAGE aktiviert; siehe unten). Referenz: pepsi-stage-auto-pay(1).

Eine Forderung wird am Header-Feld Taler: erkannt, einer der beiden privaten Header-Erweiterungen, die in SMTP-Protokollerweiterungen dokumentiert sind; sowohl mehrere URIs in einem Feld als auch mehrere Felder werden akzeptiert. Erkennung ist keine Autorisierung: Die Stage bezahlt nur für Mail, die diese Installation nachweislich selbst erzeugt hat, was sie aus dem Pepsi-Origin:-Header feststellt, den sie aus der zurückgekommenen Nachricht wiedergewinnt — ein RFC-2104-HMAC über den sendenden Host, den Absender und eine Nonce, die in pepsi.origin_nonce noch geführt sein muss.

Keiner der beiden Header ist nach RFC 3864 registriert, und keiner trägt gemäß RFC 6648 ein X--Präfix. Die taler://-URI, die sie tragen, ist GNU Talers eigenes Schema und kein IANA-registriertes (RFC 7595 legt dieses Verfahren fest); die Überweisungsanweisungen, die der Self-Service-Befehl withdraw zurückgibt, verwenden das payto:-URI-Schema von RFC 8905. (Die Stage besitzt kein Händler-Credential: Sie zahlt über eine Wallet, und nur die kassierende Seite, pepsi-stage-anti-spam, authentifiziert sich gegenüber einem Händler-Backend.)

45.2. Wallet-Self-Service (Submission-Pfad)

Wenn RESPONSE_STAGE gesetzt ist, lässt eine lokal erzeugte (authentifizierte) Nachricht an <CONTROL_LOCAL_PART>@<served-domain> (Standard-Local-Part pepsi-wallet) den Absender sein eigenes Wallet per E-Mail bedienen — parallel zu pepsi-stage-edit-settings, aber auf den Umschlagabsender geschlüsselt. Der Befehl ist das Subject: der Nachricht: balance, withdraw CUR:VAL EXCHANGE-URL (eine manuelle Aufladung vom benannten GNU-Taler-Exchange — pro Anfrage gewählt, da ein Wallet mehrere Währungen und mehrere Exchanges führt — die Antwort gibt Bank-Überweisungsanweisungen), pull CUR:VAL [subject] (ein Peer-Pull — die Antwort gibt eine taler://pay-pull/…-URI zum Weiterleiten) oder push <taler://pay-push/…> (einen Peer-Push annehmen; die URI darf im Nachrichtentext stehen). Die lokalisierte Antwort (wallet.<lang>.body-Vorlage, Null-Absender) wird bei RESPONSE_STAGE injiziert und das Original verbraucht; eine fehlerhafte Anfrage erhält Verwendungshinweise. Wenn das Wallet auf eine KYC-Anforderung stößt, trägt die Antwort stattdessen den KYC-Link (nur Self-Service — nie beim Bezahlen eingehender Forderungen). Jede andere Nachricht läuft zu NEXT_STAGE durch.

45.3. Entscheidung

Getrieben von den Headern der Nachricht (nicht ihrem state):

  • kein Taler:-Header → keine Forderung; weiterleiten zu NEXT_STAGE unberührt (sodass die Stage gefahrlos früh auf dem eingehenden Pfad platziert werden kann).

  • ein Taler:-Header, aber die Forderung ist nicht nachweislich unsere — kein gültiger Pepsi-Origin:-Nachweis (gefälscht/abgelaufen oder jede Forderung, wenn [pepsi-origin] nicht konfiguriert ist) → nie bezahlen; weiterleiten zu NEXT_STAGE.

  • nachweislich unsere → für jede taler://pay/…-URI, den privilegierten pepsi-helper-auto-pay(1)-Wallet-Helper antreibend: ihren Preis erfragen (das preview des Helpers), sie gegen das Budget pro ursprünglicher Nachricht (MAX_TOTAL) und das Tagesbudget der zahlenden Wallet (MAX_TOTAL_PER_DAY) buchen, und wenn sie in beide passt, sie begleichen (das pay des Helpers).

    • jede Forderung beglichen → den nun überflüssigen Bounce verwerfen (den Datensatz löschen);

    • eine Forderung, die nicht bepreist werden kann, eines der beiden Budgets überschreitet oder in der Währung abweicht → weiterleiten zu NEXT_STAGE, sodass die Nachricht als gewöhnlicher Bounce fortfährt und der Absender informiert wird;

    • eine unter dem Budget gebuchte Forderung, die dann nicht bezahlt werden kann → die Reservierung wird beiden Hauptbüchern gutgeschrieben (die nicht ausgegebene Zahlung darf keines der beiden Budgets verbrauchen) und die Nachricht wird weitergeleitet. Auto-Pay versucht zu bezahlen; wenn es nicht kann, tut es nichts (protokolliert den Fehler) und lässt den Bounce durch.

45.4. Kumulatives Budget

Das Budget ist auf die Pepsi-Origin-Nonce geschlüsselt, die die ursprüngliche ausgehende Nachricht identifiziert. Eine an eine Mailingliste aufgefächerte Nachricht zieht mehrere Forderungen — eine je Mitglied, dessen Standort Gebühren erhebt — die alle die gleiche, vom Original zurückgespiegelte Nonce tragen, sodass sie sich ein Budget teilen. Das nachrichtenweise Hauptbuch liegt in pepsi.origin_nonce.amount; jede Begleichung schreibt es atomar fort (die auto_pay_try_spend-Funktion sperrt den Datensatz), und eine Forderung, die die laufende Summe über MAX_TOTAL treiben würde, wird verweigert. Die Obergrenze gilt nur für eine Währung. Ein Konto kann sein eigenes MAX_TOTAL per E-Mail über pepsi-stage-edit-settings überschreiben (die Überschreibung ist auf das Konto geschlüsselt, das die Forderung erhält — den ursprünglichen Absender).

MAX_TOTAL allein begrenzt eine Nachricht, nicht einen Korrespondenten: Jeder, der eine unserer Nachrichten erhalten hat, hält einen gültigen Nachweis, sodass jemand, der k davon erhalten hat, MAX_TOTAL k-mal fordern kann. MAX_TOTAL_PER_DAY ist die Summe: was eine Wallet in beliebigen 24 Stunden ausgeben darf — die eigene des Benutzers unter WALLET_MODE = local-user, die des Absenders unter shared/per-sender, die der Installation unter shared/unified. Es gilt nie pro Korrespondent, denn Mailinglisten und Aliase machen diesen unerkennbar. Derselbe Aufruf von auto_pay_try_spend prüft beide Budgets und hält die Buchung in pepsi.auto_pay_spend fest — pro Wallet serialisiert, sodass nebenläufige Forderungen für verschiedene Nachrichten es nicht überschreiten können —, und auto_pay_refund löscht die Buchung wieder, wenn sich die Zahlung nicht begleichen lässt. Das Fenster umfasst gleitende 24 Stunden; das Limit gilt für eine einzige Währung, die von MAX_TOTAL; ist es nicht gesetzt, gibt es keines.

Die Verifikation verwendet die Herkunftsnachweis-Maschinerie wieder: siehe SMTP-Protokollerweiterungen und pepsi-stage-relay-to-internet (das Pepsi-Origin auf ausgehende Mail stempelt und die Nonce festhält).

45.5. Wallet-Konto und der Helper

Die gesamte Wallet-Interaktion wird vom setuid-root pepsi-helper-auto-pay(1)-Helper durchgeführt, der die Privilegien vor dem Ausführen von taler-wallet-cli an den richtigen Benutzer abgibt. WALLET_MODE wählt das Konto: local-user zahlt aus dem eigenen lokalen Wallet des Bounce-Empfängers (dem ursprünglichen Absender; der Empfänger muss auf ein erlaubtes lokales Konto auflösen), während shared (der Standardwert) aus einem einzelnen dedizierten WALLET_USER-Konto zahlt (Standardwert pepsi-wallets), dessen Home die Wallet-Datenbank(en) enthält — eine pro Absender (WALLET_SCOPE = per-sender) oder ein einzelnes von allen geteiltes vereinheitlichtes Wallet (WALLET_SCOPE = unified, z. B. ein Unternehmen). Weil die Stage den Helper ausführt, wird ihr Binärprogramm eigenständig und SGID pepsi-wallets installiert (der Helper ist setuid-root, root:pepsi-wallets, Modus 4750).

Bemerkung

Alles, was von der Version von taler-wallet-cli abhängt, ist auf pepsi-helper-auto-pay beschränkt: die Schreibweise von Unterbefehl und Schaltern, die jede Operation verwendet (build_wallet_args), und die kleinen Parser, die einen Betrag, eine payto:-URI, eine taler://-URI und einen KYC-Link aus dessen Ausgabe lesen. Die Stage selbst spricht nur mit dem Helfer, sodass eine künftige Änderung der CLI dort eingegrenzt bleibt.

45.6. Konfiguration

[stage-<name>]: PROGRAM = pepsi-stage-auto-pay, MAX_TOTAL (ein Taler-Betrag CURRENCY:VALUE, der die Gesamtausgabe pro ursprünglicher Nachricht begrenzt, erforderlich), MAX_TOTAL_PER_DAY (optional, dieselbe Währung, begrenzt die Ausgaben einer Wallet in beliebigen 24 Stunden), NEXT_STAGE (erforderlich — wohin eine Nicht-Forderung oder unbezahlte Nachricht weitergeleitet wird) und die Wallet-Stellschrauben WALLET_MODE, WALLET_USER, WALLET_SCOPE, WALLET_CLI, WALLET_PAY_OPTIONS und HELPER; die Self-Service-Rolle ergänzt RESPONSE_STAGE (aktiviert sie), CONTROL_LOCAL_PART, RESPONSE_FROM und RESPONSE_SUBJECT (ein withdraw benennt seinen Exchange in der Anfrage, sodass keiner konfiguriert wird). Das Geheimnis für den Herkunftsnachweis ist der gemeinsame [pepsi-origin]-Abschnitt. Siehe pepsi-stage-auto-pay(1).

45.7. State

  • Eingaben: die Taler:- und Pepsi-Origin:-Header der Nachricht (der Nachrichtentext wird ebenfalls nach einem eingebetteten Pepsi-Origin durchsucht). Die Ausgaben-Hauptbücher sind pepsi.origin_nonce.amount (pro Nachricht) und pepsi.auto_pay_spend (pro Wallet, letzte 24 Stunden), nicht das Nachrichten-state.

  • Ausgaben: keine an der Nachricht; sie wird zu NEXT_STAGE weitergeschaltet oder gelöscht.

45.8. Siehe auch

pepsi-stage-anti-spam, pepsi-stage-relay-to-internet, pepsi-stage-edit-settings, SMTP-Protokollerweiterungen, pepsi-stage-auto-pay(1).