95.1.64. pepsi-helper-auto-pay

drive taler-wallet-cli as the paying user

Manual section:

1

95.1.64.1.1. Name

pepsi-helper-auto-pay - privileged helper that prices or pays a GNU Taler delivery demand by running taler-wallet-cli as the right user.

95.1.64.1.2. Synopsis

pepsi-helper-auto-pay OP ( –uid N | –user NAME –wallet-db KEY ) [OP-OPTIONS]

where OP is one of preview/pay –uri TALER-URI [–pay-option OPT]…, balance, withdraw –amount CURRENCY:VALUE –exchange URL, push –uri TALER-URI, or pull –amount CURRENCY:VALUE [–subject TEXT].

95.1.64.1.3. Description

pepsi-helper-auto-pay is a minimal, security-hardened helper that runs taler-wallet-cli against exactly one wallet, as exactly one user, for one wallet operation. It exists so that a trusted but unprivileged caller (a member of the pepsi-wallets group, in practice pepsi-stage-auto-pay(1)) can operate the right wallet, and do nothing else.

The supported operations are: preview (price a taler://pay/… demand without paying) and pay (settle one) for the inbound demand-paying role; and balance, withdraw (set up a manual top-up against an exchange), push (accept an incoming taler://pay-push/… peer payment) and pull (initiate a peer pull, producing a taler://pay-pull/… URI) for the wallet self-service role.

The helper is installed setuid-root, owned root:pepsi-wallets with mode 4750. Only members of the pepsi-wallets group may execute it; when they do, the kernel runs it with an effective uid of root. The helper then:

  1. resolves the target account and, in shared mode, the wallet-database path inside that account’s home built from the validated KEY (the path can therefore never escape the home);

  2. drops privilege to the target user fully and irreversibly: it installs the user’s supplementary groups, then sets the gid, then the uid (real, effective and saved), and verifies that root cannot be regained. It refuses uid 0 and the login root. In local-user mode it also refuses any uid below /etc/login.defs UID_MIN (1000 when that file cannot be read), because a real recipient is expected there. Shared mode is exempt, since its target is the WALLET_USER service account that the operator configured (e.g. pepsi-wallets, typically with a low uid). There, the account’s primary group must instead be the group of this helper’s executable (pepsi-wallets), which no system account has. Like pepsi-helper-dot-forward(1) and pepsi-helper-maildir-writer(1), the helper sheds root completely;

  3. execs taler-wallet-cli for the requested operation (in shared mode with --wallet-db=…). The program is always the system-wide one that was fixed when the helper was built (/usr/bin/taler-wallet-cli by default; make TALER_WALLET_CLI=… or ./configure --with-taler-wallet-cli=…). The helper runs it only after checking that it and every directory above it are owned by root and writable by nobody else, and never takes it from the command line, the environment or the configuration. Its environment is built from scratch, not filtered: the child gets only HOME, USER/LOGNAME (the target account), a fixed PATH and SHELL, and nothing that the caller passed in. Privilege has already been dropped at that point, so the dynamic loader honours LD_PRELOAD/LD_AUDIT again, and the wallet is a Node.js program that honours NODE_OPTIONS/NODE_PATH. The caller chooses every variable in its own environment. If the helper only removed known-bad names, a caller could still turn “run the wallet as alice” into “run the caller’s code as alice”, which is exactly the escalation that this helper exists to prevent. The caller could also redirect the wallet’s exchange traffic (https_proxy/SSL_CERT_FILE). In shared mode the wallet-database directory ~NAME/wallets is created mode 0700 if absent.

    preview asks wallet-core for the proposal (api preparePayForUriV2) and reads the price from the contract terms. handle-uri cannot be used to quote a price: without --yes it stops at a confirmation prompt that does not end on EOF, and it prints no price anyway. pay runs handle-uri --choice-index 0 --yes plus any extra --pay-option arguments and runs to completion (a version-1 contract offers a list of choices and cannot be paid until one is named; the first is the one that preview priced). push takes two wallet commands: wallet-core’s preparePeerPushCredit (api) to record the incoming payment and get its transaction id, then continue-tx --yes --wait to accept it. (For such a URI handle-uri asks for confirmation whatever --yes says, and fails without a terminal.) pull runs peer-request, and balance and withdraw the subcommands of those names; each reports its result (the pay-pull URI, the balance text, or the withdrawal wire instructions). The exact taler-wallet-cli subcommands are the only part that depends on the wallet version, and they are confined to the helper.

Both peer operations wait for the wallet’s task loop. peer-request returns once the purse is at the exchange; before that, the URI that the user receives is not payable at all, and nothing else would ever create the purse, since a per-user wallet only wakes up when its owner sends the next command. The helper gives it 60 seconds and reports a failure after that. An accepted push is waited for until it is final, at most 30 seconds, so that its coins are spendable rather than pending. Each wait usually ends within a second or two; the limits apply when the exchange is unreachable or asks for KYC first. The helper needs a taler-wallet-cli with peer-request and continue-tx (1.6.46 and later).

If the wallet reports a KYC (identity verification) requirement for a self-service operation, the helper extracts the KYC URL and exits 3 with the URL on standard output, so the stage can e-mail the link to the user. The helper looks for KYC only when the operation produced no result of its own: an operation that succeeded is reported as a success even if the wallet’s diagnostic output mentions KYC somewhere, and the URL is taken from the text that mentions it rather than from wherever a URL first appears.

The caller selects one of two account models. With –uid the helper drops to that local uid and uses that user’s default wallet (WALLET_MODE = local-user in pepsi-stage-auto-pay(1)). With –user and –wallet-db it drops to the named shared account (default pepsi-wallets) and points the wallet at ~NAME/wallets/KEY.sqlite3 (WALLET_MODE = shared). A wallet left under the name KEY.json, a format that the current taler-wallet-cli no longer opens, is not migrated: the helper warns on standard error and starts a new wallet beside it.

This program is not meant to be run by hand; pepsi-stage-auto-pay(1) invokes it. It is documented here because of its privileged installation.

95.1.64.1.4. Options

preview | pay | balance | withdraw | push | pull

The operation. preview prints a demand’s price without paying; pay settles it; balance prints the wallet balance; withdraw sets up a manual top-up and prints the wire instructions; push accepts an incoming peer payment; pull initiates a peer pull and prints the resulting URI.

–uri TALER-URI

The taler://pay/… (preview/pay) or taler://pay-push/… (push) URI to act on. Required for those operations. The helper validates it again here, at the privileged boundary: preview/pay refuse anything that is not a taler://pay/ URI, push refuses anything that is not taler://, and any URI is refused outright if it holds a character outside the RFC 3986 repertoire (so quotes, backslashes and whitespace can never reach the wallet).

–amount CURRENCY:VALUE

The GNU Taler amount, required for withdraw and pull.

–exchange URL

The exchange base URL for a manual withdraw (required).

–subject TEXT

An optional payment subject/summary for pull.

–uid N

Local-user mode: drop to uid N and use that user’s default wallet. Mutually exclusive with –user.

–user NAME –wallet-db KEY

Shared mode: drop to account NAME and use the wallet database named by the opaque, validated KEY under that account’s home. Both are required together.

–wallet-cli PATH

Refused with an error. The program that runs as another account is fixed at build time. Otherwise any caller able to name it, which means any code that runs as the pepsi account, could run a program of its choosing as that account.

–pay-option OPT

An extra argument appended to the pay invocation (repeatable; none is needed, since handle-uri already waits for the payment to reach a terminal state); --yes is added to pay as well, since a helper run from a stage has nobody to ask.

Neither applies to push, which is not a handle-uri call at all but a two-command preparePeerPushCredit / continue-tx flow: continue-tx rejects those flags outright, and it waits for the credit itself. The options are accepted and ignored on that path, so a WALLET_PAY_OPTIONS set for a self-service push has no effect.

95.1.64.1.5. Exit Status

0

Success. For preview the proposed amount is on standard output; for balance, withdraw and pull the report text is on standard output; for pay and push standard output is empty.

2

The operation failed (bad arguments, not setuid-root, a refused account, the price could not be read, or the wallet operation failed). A human-readable diagnostic is written to standard output and standard error.

3

The wallet requires KYC (identity verification); the KYC URL is on standard output.

95.1.64.1.6. Security

The helper deliberately does no configuration, database or logging work. Its only privileged action is to become the target user before running the wallet; it refuses to act as root and, after dropping privilege, verifies that root cannot be regained. Access to it is gated by the pepsi-wallets group, granted to the caller through pepsi-stage-auto-pay(1)’s SGID bit and to no one else. The manual’s Security model chapter (The privilege split) lists every program that carries a setuid or setgid bit; its Threat model chapter (the local-user section) states what the helpers may and may not be made to do.

95.1.64.1.7. See Also

pepsi-stage-auto-pay(1), pepsi-stage-anti-spam(1), pepsi-helper-dot-forward(1), pepsi-dispatch(1), pepsi.conf(5)

95.1.64.1.8. Bugs

Report bugs to the Pepsi issue tracker.