70.1.39. pepsi-secure-link

inspect and manage messages held in the portal

Manual section:

1

70.1.39.1.1. Name

pepsi-secure-link - operator CLI for the secure-link fallback portal.

70.1.39.1.2. Synopsis

pepsi-secure-link [GLOBAL-OPTIONS] list [–limit N] [–expired] [–json]

pepsi-secure-link [GLOBAL-OPTIONS] show TOKEN [–json]

pepsi-secure-link [GLOBAL-OPTIONS] revoke TOKEN

pepsi-secure-link [GLOBAL-OPTIONS] prune [–grace-hours N]

70.1.39.1.3. Description

pepsi-secure-link inspects and manages the messages held in the secure-link fallback portal (see pepsi-stage-secure-link(1) and pepsi-httpd(1)). It is an operator tool, not a stage.

Global options (-c/--config, -L/--log, -v) come before the subcommand. Run as root the tool adopts the pepsi service account, so it authenticates to PostgreSQL as the role that owns the queue.

70.1.39.1.4. What it can and cannot show

It reports who and when, never what. There is no subcommand that displays a stored message, no --decrypt flag and no escrow key, and their absence is the design rather than an omission: the content key is derived with Argon2id from the recipient’s PIN, a per-message salt and a server-side pepper, and the PIN is never sent to this server. Nothing an administrator holds — the database, the pepper, both together — reconstructs it.

The consequence to plan for is a support call. When a recipient loses the PIN, the answer is that the sender sends the message again; a new PIN is issued and a new link mailed. There is no “resend the PIN”, because the PIN no longer exists anywhere but in the recipient’s hands.

70.1.39.1.5. Commands

list

Outstanding messages, newest first: token, sender, recipient, expiry, read count, failed-PIN count and any lockout. --expired also shows messages that have run out but have not been pruned yet. --limit caps the listing (50 by default) and --json prints the same fields as JSON.

show TOKEN

One message’s metadata plus its access log: when each attempt happened, from which address, and how it ended (read, bad-pin, locked, reply). The log is capped per message by [pepsi-secure-link] ACCESS_LOG_ROWS and is deleted with the message.

revoke TOKEN

Destroy one message. This does not put the mail back in the queue — it withdraws it, and the recipient’s link stops working. If it was a mistake, the sender re-sends.

prune

Delete every message past its expiry, and with it the only copy. Intended for a daily cron job or systemd timer, like pepsi-tlsrpt prune. --grace-hours keeps expired messages a little longer. A deployment that never prunes keeps unreadable ciphertext in the database for ever: the portal already refuses an expired token, so this is a database-size problem rather than a confidentiality one, but it is still a problem.

70.1.39.1.6. Privileges

The tool runs as the pepsi database role, which is granted INSERT, DELETE and SELECT on every column of pepsi.secure_message except ciphertext. That is why list and show work and why nothing here can print a message even by accident; pepsi-setup verifies the boundary against the live database on every run.

70.1.39.1.7. Exit status

0 on success, non-zero on error (including show/revoke for a token that does not exist).

70.1.39.1.8. See also

pepsi-stage-secure-link(1), pepsi-stage-encrypt(1), pepsi-httpd(1), pepsi-setup(1), pepsi.conf(5)